React DayPicker SelectedSingle 类型别名全解析：单日期选择模式的类型契约与 required 条件类型机制

本篇技术指南围绕 react-day-picker 中单日期选择（single mode）的核心类型别名 SelectedSingle<T> 展开，说明其条件类型定义、required 标志如何改变返回类型，以及与 SelectedValue、SelectHandlerSingle、PropsSingle 等类型的联动关系。读完本文，你将掌握 single 模式下受控/非受控选择的类型推导规律，并能正确书写强类型的 onSelect 回调与自定义选择逻辑。

类型定义与定位

SelectedSingle<T> 定义于 src/types/selection.ts:13-16，是 DayPicker 三种选择模式（single、multiple、range）各自的“选择值”类型之一：

export type SelectedSingle<T extends { required?: boolean }> =
  T["required"] extends true ? Date : Date | undefined;

同一文件还定义了 SelectedMulti<T> 与 SelectedRange<T>：

export type SelectedMulti<T extends { required?: boolean }> =
  T["required"] extends true ? Date[] : Date[] | undefined;

export type SelectedRange<T extends { required?: boolean }> =
  T["required"] extends true ? DateRange : DateRange | undefined;

可见 SelectedSingle 只关心入参 T 的 required 字段：当 required: true 时，选择值必定为 Date（不可为空）；否则为 Date | undefined（可为空）。它不关心 T 的其他任何字段。

类型参数约束

SelectedSingle<T> 对泛型参数 T 的唯一约束是：

T extends { required?: boolean }

即 T 必须是一个包含可选布尔字段 required 的对象类型。实践中 T 通常取自 mode: "single" 的 props 类型。例如 DayPickerProps 的联合成员 PropsSingle（required?: false | undefined）或 PropsSingleRequired（required: true），二者均满足该约束。两个接口定义于 src/types/props.ts:529-551：

export interface PropsSingleRequired {
  mode: "single";
  required: true;
  selected: Date | undefined;
  onSelect?: OnSelectHandler<Date>;
}

export interface PropsSingle {
  mode: "single";
  required?: false | undefined;
  selected?: Date | undefined;
  onSelect?: OnSelectHandler<Date | undefined>;
}

required 条件类型如何推导返回值

条件类型 T["required"] extends true ? Date : Date | undefined 的推导规则如下：

• 当 T["required"] 为字面量 true（如 PropsSingleRequired）时，结果是 Date；
• 当 T["required"] 为 false、undefined 或可选缺省（如 PropsSingle）时，结果落入 Date | undefined。

这一机制保证了：在 required 模式下，开发者无需在 onSelect 中处理 undefined 分支；而在非 required 模式下，选择可能被清空（点击已选中日期取消选择），因此类型上必须显式考虑 undefined。它与 SelectHandlerSingle<T> 的返回类型保持严格一致：

export type SelectHandlerSingle<T extends { required?: boolean | undefined }> = (
  triggerDate: Date,
  modifiers: Modifiers,
  e: React.MouseEvent | React.KeyboardEvent,
) => T["required"] extends true ? Date : Date | undefined;

见 src/types/selection.ts:52-57。回调的第三个参数是触发事件（鼠标或键盘），这正对应单日期选择支持键盘操作（如方向键移动、回车选中）的可访问性设计。

与 SelectedValue 的联动

SelectedSingle 并非孤立存在，它被统一入口类型 SelectedValue<T> 按模式分发引用（src/types/selection.ts:43-49）：

export type SelectedValue<T> = T extends { mode: "single"; required?: boolean }
  ? SelectedSingle<T>
  : T extends { mode: "multiple"; required?: boolean }
    ? SelectedMulti<T>
    : T extends { mode: "range"; required?: boolean }
      ? SelectedRange<T>
      : undefined;

因此当 mode 为 "single" 时，SelectedValue<T> 即解析为 SelectedSingle<T>；当 mode 缺省时解析为 undefined（此时日历仅用于展示，不可选择）。

运行时行为验证：useSingle 钩子

类型层面的契约在运行时由 useSingle.tsx 实现。其核心逻辑：

const select = (triggerDate, modifiers, e) => {
  let newDate: Date | undefined = triggerDate;
  if (!required && selected && isSameDay(triggerDate, selected)) {
    // 再次点击已选中日期 → 取消选择
    newDate = undefined;
  }
  if (!onSelect) setSelected(newDate);          // 非受控
  onSelect?.(newDate, triggerDate, modifiers, e); // 受控回调
  return newDate;
};

要点如下：

1. 非 required 且点击已选日期时，newDate 被置为 undefined——这正是 Date | undefined 联合类型存在的运行时根源；
2. 受控模式下（传入 onSelect），内部状态不更新，选择值完全由 selected prop 决定，见 selected = !onSelect ? internallySelected : initiallySelected；
3. required 模式下，取消分支被跳过，选择值永远是一个 Date，与类型推导一致。

对应测试 useSingle.test.tsx 验证了两条路径：提供 onSelect 时 selected 直接取 props 值；不提供 onSelect 时通过 select 更新内部状态。

实战用法

基础非受控用法

<DayPicker mode="single" />

仅指定 mode="single" 时（示例见 Single.tsx），required 缺省为 false，选择值类型即 Date | undefined。

受控用法（推荐）

import { DayPicker } from "@daypicker/react";
import React from "react";

export function SingleControlled() {
  const [selected, setSelected] = React.useState<Date | undefined>();
  return <DayPicker mode="single" selected={selected} onSelect={setSelected} />;
}

对应仓库示例 SingleControlled.tsx。useState<Date | undefined>() 与 SelectedSingle<PropsSingle> 的类型完全吻合，setSelected 可直接作为 onSelect 传入。

required 用法

import { DayPicker } from "@daypicker/react";
import React, { useState } from "react";

export function SingleRequired() {
  const [selectedDay, setSelectedDay] = useState<Date>();
  return (
    <DayPicker
      mode="single"
      required
      selected={selectedDay}
      onSelect={(date) => date && setSelectedDay(date)}
    />
  );
}

对应仓库示例 SingleRequired.tsx。此时 SelectedSingle<PropsSingleRequired> 解析为 Date，回调中需先判断 date 非空再写入状态。

类型层面显式使用

import type { SelectedSingle } from "react-day-picker";

// required 场景：类型为 Date
const a: SelectedSingle<{ required: true }> = new Date();

// 非 required 场景：类型为 Date | undefined
const b: SelectedSingle<{ required?: boolean }> = undefined;

与其他类型的关系小结

类型	定义位置	作用
SelectedSingle<T>	src/types/selection.ts	single 模式的选择值类型
SelectedValue<T>	src/types/selection.ts	按模式统一分发的选择值类型
SelectHandlerSingle<T>	src/types/selection.ts	single 模式的选择回调类型
Selection<T>	src/types/selection.ts	选择状态与辅助方法的聚合
PropsSingle / PropsSingleRequired	src/types/props.ts	决定 T 的 required 取值
useSingle	src/selection/useSingle.tsx	运行时实现选择逻辑

理解 SelectedSingle<T>，就抓住了 single 模式类型契约的核心：required 开关同时驱动类型推导与运行时行为，让“必选”与“可选”两种语义在编译期和运行期保持一致，这是 react-day-picker 类型安全设计的一个典型缩影。