DatePicker 日期选择器

用于选择日期。

需要同时选择时间时，使用 DateTimePicker；需要起止区间时，使用 DateRangePicker。

基础选择

点击控件打开日历，选择日期后收起。defaultValue 设置初始日期，disabled 禁用整个控件。

basic.tsx

import { DatePicker, Form, FormField } from '@ifhover/leaf-ui';

export function DatePickerBasic() {
  return (
    <Form layout="vertical">
      <FormField label="选择日期">
        <DatePicker aria-label="选择日期" placeholder="选择一个好日子" />
      </FormField>
      <FormField label="默认日期">
        <DatePicker aria-label="默认日期" defaultValue={new Date(2026, 9, 15)} />
      </FormField>
      <FormField label="禁用日期">
        <DatePicker aria-label="禁用日期" defaultValue={new Date(2026, 9, 15)} disabled />
      </FormField>
    </Form>
  );
}

受控与日期限制

通过 minDate / maxDate 限定可选日期，边界当天也可以选择。onChange 同时提供 Date 对象和本地日期字符串。

controlled.tsx

import { DatePicker, Form, FormField, Text } from '@ifhover/leaf-ui';

import { useState } from 'react';

export function DatePickerControlled() {
  const [date, setDate] = useState<Date | null>(new Date(2026, 9, 15));
  const [dateString, setDateString] = useState('2026-10-15');
  return (
    <Form layout="vertical">
      <FormField label="十月的日期">
        <DatePicker
          aria-label="十月的日期"
          value={date}
          minDate={new Date(2026, 9, 5)}
          maxDate={new Date(2026, 9, 25)}
          onChange={(next, text) => {
            setDate(next);
            setDateString(text);
          }}
        />
      </FormField>
      <Text tone="muted">可选 10 月 5–25 日，当前值：{dateString || '未选择'}</Text>
      <FormField label="必填日期 · 错误">
        <DatePicker aria-label="必填日期" status="error" required placeholder="请设置截止日期" />
      </FormField>
    </Form>
  );
}

快捷日期

通过 todayText 修改今天按钮文字，renderExtraFooter 增加快捷操作，showToday=false 隐藏今天按钮。

自定义快捷日期

footer.tsx

import { Button, DatePicker, Flex, Text } from '@ifhover/leaf-ui';

import { useState } from 'react';

export function DatePickerFooter() {
  const [value, setValue] = useState<Date | null>(null);
  const tomorrow = () => {
    const next = new Date();
    next.setDate(next.getDate() + 1);
    next.setHours(0, 0, 0, 0);
    setValue(next);
  };
  return (
    <Flex direction="column" gap="sm" align="start">
      <Text>自定义快捷日期</Text>
      <DatePicker
        aria-label="自定义快捷日期"
        value={value}
        onChange={setValue}
        todayText="今天"
        renderExtraFooter={
          <Button variant="ghost" size="sm" onClick={tomorrow}>
            明天
          </Button>
        }
      />
    </Flex>
  );
}

扩展用法

年份

季度

月份

周

extensions.tsx

import { DatePicker, Space } from '@ifhover/leaf-ui';

export function ExtensionDemo() {
  return (
    <Space wrap>
      {(['year', 'quarter', 'month', 'week'] as const).map((picker) => (
        <label key={picker} htmlFor={`period-${picker}`}>
          {{ year: '年份', quarter: '季度', month: '月份', week: '周' }[picker]}
          <DatePicker id={`period-${picker}`} picker={picker} />
        </label>
      ))}
    </Space>
  );
}

格式、预设与多日期

自定义显示格式与工作日限制

选择最多三个日期

capabilities.tsx

import { DatePicker, Flex, Space, Text } from '@ifhover/leaf-ui';

export function Capabilities() {
  return (
    <Space direction="vertical" align="stretch">
      <Flex direction="column" gap="sm" align="center">
        <Text>
          {'自定义显示格式与工作日限制'}
        </Text>
        <DatePicker
          format="DD/MM/YYYY"
          disabledDate={(date) => date.getDay() === 0 || date.getDay() === 6}
          presets={[{ label: '今天', value: () => new Date() }]}
        />
      </Flex>
      <Flex direction="column" gap="sm" align="center">
        <Text>{'选择最多三个日期'}</Text>
        <DatePicker multiple maxCount={3} format="MM/DD" />
      </Flex>
    </Space>
  );
}

显示格式与提交值

format 改变显示文字和 onChange 的字符串参数；FormData 保持日期或周期的稳定序列化格式。方括号可以转义固定文字，例如 YYYY-[Q]Q。使用函数格式化时，请同时提供 parse。Date 表示本地日历值，业务时区在应用的数据边界完成转换。周起点通过 ConfigProvider 的 weekStartsOn 设置。

DatePicker API

属性	类型	默认值	说明
`popupPlacement`	`'top' \| 'top-start' \| 'top-end' \| 'bottom' \| 'bottom-start' \| 'bottom-end' \| 'left' \| 'left-start' \| 'left-end' \| 'right' \| 'right-start' \| 'right-end'`	—	浮层相对触发控件的位置。
`popupClassName`	`string`	—	浮层的自定义类名。
`popupStyle`	`CSSProperties`	—	浮层的自定义样式。
`popupRender`	`(content: React.ReactNode) => React.ReactNode`	—	包装或补充面板内容，保留传入的内容以维持交互。
`getPopupContainer`	`() => Element \| DocumentFragment`	—	返回浮层的挂载容器，也可返回 ShadowRoot。
`size`	`'sm' \| 'md' \| 'lg'`	`'md'`	选择器尺寸
`status`	`'error' \| 'warning'`	—	校验状态
`allowClear`	`boolean`	`true`	展示清除按钮
`inputReadOnly`	`boolean`	—	只禁止手动输入，仍可在面板中选择。
`open`	`boolean`	—	控制面板是否展开。
`defaultOpen`	`boolean`	—	面板初始展开状态。
`multiple`	`false \| true`	—	启用多选；value 和回调的类型随之变化。
`value`	`Date \| null \| readonly Date[]`	`null`	受控日期 / 非受控初始日期
`defaultValue`	`Date \| null \| readonly Date[]`	`null`	受控日期 / 非受控初始日期
`minDate`	`Date`	—	最早 / 最晚可选日期，按本地年月日比较
`maxDate`	`Date`	—	最早 / 最晚可选日期，按本地年月日比较
`picker`	`'date' \| 'year' \| 'quarter' \| 'month' \| 'week'`	`'date'`	选择日期、年、季度、月或周
`disabledDate`	`(date: Date) => boolean`	—	限制可选择日期
`showToday`	`boolean`	`true`	展示今天快捷按钮
`todayText`	`ReactNode`	语言默认值	自定义今天按钮文字
`renderExtraFooter`	`ReactNode`	—	额外底部内容，可放快捷操作
`onChange`	`((value: Date \| null, dateString: string) => void) \| ((value: Date[], dateStrings: string[]) => void)`	—	日期变更；清除时返回 null 和空字符串
`onOpenChange`	`(open: boolean) => void`	—	日历展开或收起
`format`	`string \| ((date: Date) => string)`	—	显示格式；日期支持 YYYY、MM、DD、HH、mm、ss、Q。
`parse`	`(text: string) => Date \| null`	—	自定义文本解析，失败时返回 null。
`presets`	`readonly DatePreset[]`	—	快捷选项；value 可以动态计算。
`panelValue`	`Date`	—	受控的日历显示日期。
`onPanelChange`	`(date: Date) => void`	—	日历显示的周期改变时调用。
`cellRender`	`(date: Date) => ReactNode`	—	自定义日历单元格内容。
`maxCount`	`number`	—	最多可选的数量。
`disabled`	`boolean`	`false`	禁用交互。
`name`	`string`	—	原生 FormData 中的字段名。
`form`	`string`	—	关联的原生表单 ID。
`required`	`boolean`	`false`	要求整体值非空，复合控件只校验一次。
`ref`	`Ref<HTMLInputElement>`	—	输入框引用

其余原生 input 属性和 aria-* 透传至输入框；className / style 作用于外层容器。

类型

可导入 DatePickerProps 定义组件属性，或单独使用尺寸、校验状态类型：

import type { DatePickerProps, ControlSize, ControlStatus } from '@ifhover/leaf-ui';

日期与表单

传入有效 Date 对象，且 minDate 不晚于 maxDate。组件按本地日期处理：可用 new Date(2026, 9, 15) 表示 2026 年 10 月 15 日，月份从 0 开始。选择结果为本地当天零点；避免用 UTC 字符串转换代替本地日期构造。

设置 name 后，FormData 提交当前 picker 模式的字符串，清除后为空字符串。非受控组件支持表单 reset，受控组件需同步重置自己的状态。年、季度、月、周模式的 Date 值为对应周期的起始日期，日历从默认周一开始，可通过 ConfigProvider 的 weekStartsOn 修改。

键盘与主题

点击控件打开日历，↓ 移入日历。方向键按日或周移动，Home / End 移至本周首尾，PageUp / PageDown 切换月份，Enter 选择。Tab 依次访问月切换与日期；离开面板时回到表单中的后续控件，Escape 收起并聚焦输入框。

为控件提供 label 或 aria-label。日历沿用控件所在容器的主题色、圆角和浅深色变量；点击外部或移走焦点会收起。

可以直接输入 YYYY-MM-DD，按 Enter 或移走焦点提交。无效日期和超出 minDate / maxDate 的值不会提交。点击日历顶部的月份、年份可切换选择面板；默认展示“今天”快捷按钮，可通过 showToday、todayText 与 renderExtraFooter 定制。

点击输入框保留输入焦点；↓ 将焦点移入日历，Escape 放弃未完成输入。

各模式格式：date → YYYY-MM-DD、year → YYYY、quarter → YYYY-QN、month → YYYY-MM、week → YYYY-Www。显示、手动输入、onChange 字符串和 FormData 使用相同格式。

SingleDatePicker API

属性	类型	默认值	说明
`popupPlacement`	`'top' \| 'top-start' \| 'top-end' \| 'bottom' \| 'bottom-start' \| 'bottom-end' \| 'left' \| 'left-start' \| 'left-end' \| 'right' \| 'right-start' \| 'right-end'`	—	浮层相对触发控件的位置。
`popupClassName`	`string`	—	浮层的自定义类名。
`popupStyle`	`CSSProperties`	—	浮层的自定义样式。
`popupRender`	`(content: React.ReactNode) => React.ReactNode`	—	包装或补充面板内容，保留传入的内容以维持交互。
`getPopupContainer`	`() => Element \| DocumentFragment`	—	返回浮层的挂载容器，也可返回 ShadowRoot。
`size`	`'sm' \| 'md' \| 'lg'`	`'md'`	展示尺寸。
`status`	`'error' \| 'warning'`	—	设置 status。
`allowClear`	`boolean`	`true`	展示清除操作。
`inputReadOnly`	`boolean`	—	只禁止手动输入，仍可在面板中选择。
`open`	`boolean`	—	控制面板是否展开。
`defaultOpen`	`boolean`	—	面板初始展开状态。
`multiple`	`false`	—	启用多选；value 和回调的类型随之变化。
`value`	`Date \| null`	—	受控值。
`defaultValue`	`Date \| null`	`null`	初始值；非受控模式支持表单重置。
`minDate`	`Date`	—	最早可选的日期（含边界）。
`maxDate`	`Date`	—	最晚可选的日期（含边界）。
`picker`	`'date' \| 'year' \| 'quarter' \| 'month' \| 'week'`	`'date'`	设置 picker。
`disabledDate`	`(date: Date) => boolean`	—	按业务规则禁用日期。
`showToday`	`boolean`	`true`	设置 showToday。
`todayText`	`ReactNode`	—	设置 todayText。
`renderExtraFooter`	`ReactNode`	—	设置 renderExtraFooter。
`onChange`	`(value: Date \| null, dateString: string) => void`	—	值发生变化时调用。
`onOpenChange`	`(open: boolean) => void`	—	面板展开或收起时调用。
`format`	`string \| ((date: Date) => string)`	—	显示格式；日期支持 YYYY、MM、DD、HH、mm、ss、Q。
`parse`	`(text: string) => Date \| null`	—	自定义文本解析，失败时返回 null。
`presets`	`readonly DatePreset[]`	—	快捷选项；value 可以动态计算。
`panelValue`	`Date`	—	受控的日历显示日期。
`onPanelChange`	`(date: Date) => void`	—	日历显示的周期改变时调用。
`cellRender`	`(date: Date) => ReactNode`	—	自定义日历单元格内容。

MultipleDatePicker API

属性	类型	默认值	说明
`popupPlacement`	`'top' \| 'top-start' \| 'top-end' \| 'bottom' \| 'bottom-start' \| 'bottom-end' \| 'left' \| 'left-start' \| 'left-end' \| 'right' \| 'right-start' \| 'right-end'`	—	浮层相对触发控件的位置。
`popupClassName`	`string`	—	浮层的自定义类名。
`popupStyle`	`CSSProperties`	—	浮层的自定义样式。
`popupRender`	`(content: React.ReactNode) => React.ReactNode`	—	包装或补充面板内容，保留传入的内容以维持交互。
`getPopupContainer`	`() => Element \| DocumentFragment`	—	返回浮层的挂载容器，也可返回 ShadowRoot。
`size`	`'sm' \| 'md' \| 'lg'`	`'md'`	展示尺寸。
`status`	`'error' \| 'warning'`	—	设置 status。
`allowClear`	`boolean`	`true`	展示清除操作。
`inputReadOnly`	`boolean`	—	只禁止手动输入，仍可在面板中选择。
`open`	`boolean`	—	控制面板是否展开。
`defaultOpen`	`boolean`	—	面板初始展开状态。
`minDate`	`Date`	—	最早可选的日期（含边界）。
`maxDate`	`Date`	—	最晚可选的日期（含边界）。
`picker`	`'date' \| 'year' \| 'quarter' \| 'month' \| 'week'`	`'date'`	设置 picker。
`disabledDate`	`(date: Date) => boolean`	—	按业务规则禁用日期。
`showToday`	`boolean`	`true`	设置 showToday。
`todayText`	`ReactNode`	—	设置 todayText。
`renderExtraFooter`	`ReactNode`	—	设置 renderExtraFooter。
`onOpenChange`	`(open: boolean) => void`	—	面板展开或收起时调用。
`format`	`string \| ((date: Date) => string)`	—	显示格式；日期支持 YYYY、MM、DD、HH、mm、ss、Q。
`parse`	`(text: string) => Date \| null`	—	自定义文本解析，失败时返回 null。
`panelValue`	`Date`	—	受控的日历显示日期。
`onPanelChange`	`(date: Date) => void`	—	日历显示的周期改变时调用。
`cellRender`	`(date: Date) => ReactNode`	—	自定义日历单元格内容。
`multiple`	`true`	—	必需。启用多选；value 和回调的类型随之变化。
`value`	`readonly Date[]`	—	受控值。
`defaultValue`	`readonly Date[]`	—	初始值；非受控模式支持表单重置。
`maxCount`	`number`	—	最多可选的数量。
`onChange`	`(value: Date[], dateStrings: string[]) => void`	—	值发生变化时调用。

DatePreset

属性	类型	默认值	说明
`key`	`string`	—	稳定且唯一的标识。
`label`	`ReactNode`	—	必需。展示文字或内容。
`value`	`T \| (() => T)`	—	必需。受控值。

#DatePicker 日期选择器

#基础选择

#受控与日期限制

#快捷日期

#扩展用法

#格式、预设与多日期

#显示格式与提交值

#DatePicker API

#类型

#日期与表单

#键盘与主题

#SingleDatePicker API

#MultipleDatePicker API

#DatePreset