For AI agents: the complete documentation index is available at https://ifhover.github.io/leaf-ui/llms.txt, the full documentation bundle is available at https://ifhover.github.io/leaf-ui/llms-full.txt, and this page is available as Markdown at https://ifhover.github.io/leaf-ui/components/date-picker.md.

DatePicker 日期选择器

选择日期、时间或日期时间。日期模式使用本地 Date,picker="time" 使用时间字符串;选择区间请使用 DateRangePicker。

基础用法

通过 defaultValue 设置初始日期,选择日期后自动收起。空值使用 null。

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

export function DatePickerBasic() {
  return (
    <Form layout="vertical" onSubmit={(event) => event.preventDefault()}>
      <FormField label="默认日期">
        <DatePicker defaultValue={new Date(2026, 9, 15)} />
      </FormField>
    </Form>
  );
}

示例

受控值与清除

通过 value 与 onChange 管理选中值。日期模式回调同时提供 Date 和格式化字符串,清除时为 null 和 ''。受控组件的表单重置需要同步重置应用状态。

回调文本:2026-10-15
controlled.tsx
import { Button, DatePicker, Form, FormField, Text } from '@ifhover/leaf-ui';
import { useState } from 'react';

const initialDate = new Date(2026, 9, 15);

export function DatePickerControlled() {
  const [value, setValue] = useState<Date | null>(initialDate);
  const [dateString, setDateString] = useState('2026-10-15');

  return (
    <Form
      layout="vertical"
      onSubmit={(event) => event.preventDefault()}
      onReset={() => {
        setValue(initialDate);
        setDateString('2026-10-15');
      }}
    >
      <FormField label="截止日期">
        <DatePicker
          value={value}
          onChange={(next, text) => {
            setValue(next);
            setDateString(text);
          }}
        />
      </FormField>
      <Text tone="muted" role="status">
        回调文本:{dateString || '空字符串'}
      </Text>
      <Button type="reset">重置</Button>
    </Form>
  );
}

交互状态

disabled 禁用整个控件,readOnly 保留只读值且不能修改。inputReadOnly 只禁止键盘输入,仍可从面板选择。

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

export function DatePickerStates() {
  return (
    <Form layout="vertical" onSubmit={(event) => event.preventDefault()}>
      <FormField label="禁用">
        <DatePicker defaultValue={new Date(2026, 9, 15)} disabled />
      </FormField>
      <FormField label="只读">
        <DatePicker defaultValue={new Date(2026, 9, 15)} readOnly />
      </FormField>
      <FormField label="仅面板选择">
        <DatePicker defaultValue={new Date(2026, 9, 15)} inputReadOnly />
      </FormField>
    </Form>
  );
}

选择粒度

通过 picker 选择年份、季度、月份或周;返回的 Date 为对应周期的起始日期。周起点由 ConfigProvider 的 weekStartsOn 设置,默认星期一。

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

export function ExtensionDemo() {
  return (
    <Form layout="vertical" onSubmit={(event) => event.preventDefault()}>
      {(['year', 'quarter', 'month', 'week'] as const).map((picker) => (
        <FormField
          key={picker}
          label={{ year: '年份', quarter: '季度', month: '月份', week: '周' }[picker]}
        >
          <DatePicker picker={picker} />
        </FormField>
      ))}
    </Form>
  );
}

限制可选日期

minDate / maxDate 包含边界,disabledDate 返回 true 时禁用该日期。下面只允许选择十月的工作日。限制同时用于输入和面板选择,但不会自动清除已有值;业务规则变化后由应用检查原值。日期时间模式按完整时间戳比较边界。

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

export function DisabledDates() {
  return (
    <Form layout="vertical" onSubmit={(event) => event.preventDefault()}>
      <FormField label="十月工作日">
        <DatePicker
          defaultValue={new Date(2026, 9, 15)}
          minDate={new Date(2026, 9, 1)}
          maxDate={new Date(2026, 9, 31)}
          disabledDate={(date) => date.getDay() === 0 || date.getDay() === 6}
        />
      </FormField>
    </Form>
  );
}

日期与时间

设置 picker="datetime" 后选择日期和时间,再点击“确定”提交。此模式默认 needConfirm={true},点击外部会放弃尚未确定的日期和时间。

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

export function DatePickerDateTime() {
  return (
    <Form layout="vertical" onSubmit={(event) => event.preventDefault()}>
      <FormField label="预约时间">
        <DatePicker picker="datetime" defaultValue={new Date(2026, 9, 3, 14, 30)} />
      </FormField>
    </Form>
  );
}

仅选择时间

picker="time" 的值和 onChange 参数为 24 小时制 HH:mm 字符串,清除时为 null;开启 showSeconds 后使用 HH:mm:ss。用 minTime / maxTime 限制时间,或通过 disabledTime 排除业务禁用时间。

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

export function DatePickerTime() {
  return (
    <Form layout="vertical" onSubmit={(event) => event.preventDefault()}>
      <FormField label="默认时间">
        <DatePicker picker="time" defaultValue="09:30" />
      </FormField>
    </Form>
  );
}

12 小时制与秒

use12Hours 只改变显示方式,值仍为 24 小时制。minuteStep / secondStep 控制步进,已有的非步长值仍可保留;不显示秒时提交值的秒为 0。

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

export function DatePickerTwelveHours() {
  return (
    <Form layout="vertical" onSubmit={(event) => event.preventDefault()}>
      <FormField label="12 小时制">
        <DatePicker picker="time" use12Hours defaultValue="14:30" />
      </FormField>
      <FormField label="精确到秒">
        <DatePicker picker="time" use12Hours showSeconds secondStep={10} defaultValue="00:05:30" />
      </FormField>
    </Form>
  );
}

显示格式与表单提交

format 改变显示和 onChange 的字符串参数,不改变 FormData 的规范值。下面显示 DD/MM/YYYY,提交 YYYY-MM-DD;清除后提交空字符串,非受控字段重置后恢复 defaultValue。

FormData:尚未提交
format.tsx
import { Button, DatePicker, Form, FormField, Space, Text } from '@ifhover/leaf-ui';
import { useState } from 'react';

export function Format() {
  const [submitted, setSubmitted] = useState<string | null>(null);

  return (
    <Form
      layout="vertical"
      onSubmit={(event) => {
        event.preventDefault();
        setSubmitted(String(new FormData(event.currentTarget).get('meetingDate') ?? ''));
      }}
      onReset={() => setSubmitted(null)}
    >
      <FormField label="会议日期">
        <DatePicker name="meetingDate" format="DD/MM/YYYY" defaultValue={new Date(2026, 9, 15)} />
      </FormField>
      <Space>
        <Button type="submit">提交</Button>
        <Button type="reset">重置</Button>
      </Space>
      <Text tone="muted" role="status">
        FormData:{submitted === null ? '尚未提交' : JSON.stringify(submitted)}
      </Text>
    </Form>
  );
}

各模式的规范值为 date: YYYY-MM-DD、year: YYYY、quarter: YYYY-QN、month: YYYY-MM、week: YYYY-Www,日期时间为 YYYY-MM-DD HH:mm[:ss]。日期使用本地时间,业务时区转换由应用处理,避免把 UTC 日期字符串当成本地日历值。

字符串格式支持 YYYY、MM、DD、HH、mm、ss、Q,用方括号转义文字,例如 YYYY-[Q]Q。函数格式化若不能由默认解析识别,应同时提供 parse,失败时返回 null。更多表单配置见 Form。

快捷日期

通过 presets 提供常用日期。快捷值可以是 Date 或同步返回 Date 的函数,不接收 Promise;点击有效快捷项会立即提交并收起,不等待“确定”。今天按钮可通过 showToday / todayText 配置,自定义底部内容使用 renderExtraFooter,其中的业务操作由应用处理。

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

function tomorrow() {
  const date = new Date();
  date.setDate(date.getDate() + 1);
  date.setHours(0, 0, 0, 0);
  return date;
}

export function DatePickerPresets() {
  return (
    <Form layout="vertical" onSubmit={(event) => event.preventDefault()}>
      <FormField label="交付日期">
        <DatePicker presets={[{ label: '明天', value: tomorrow }]} />
      </FormField>
    </Form>
  );
}

输入与确认

可直接输入或粘贴完整值,点击或用左右键选择日期分段。Enter 提交有效输入,Escape 放弃当前编辑;无效或未完成输入在焦点离开整个选择器时恢复已提交值。Alt + ↓ 可将焦点移入面板。

日期和纯时间模式默认不要求确认,有效改动可在离开时提交。设置 needConfirm 后,未确认的编辑在离开时放弃;清除和快捷日期仍会直接提交。

API

DatePicker API

主表包含不同 picker 模式的参数:format、parse、presets、minDate / maxDate 和日历展示配置用于日期模式;minTime / maxTime 用于纯时间模式。disabledTime 在日期时间模式额外接收当前 Date。

属性类型默认值说明
picker'date' | 'datetime' | 'year' | 'quarter' | 'month' | 'week' | 'time''date'选择日期、时间、日期时间、周、月、季度或年。
valueDate | null | string—受控值:日期 / 日期时间为 Date,纯时间为 HH:mm[:ss] 字符串;空值为 null。
defaultValueDate | null | stringnull非受控初始值,类型由 picker 决定,表单重置时恢复。
onChange((value: Date | null, dateString: string) => void) | ((value: string | null) => void)—提交时调用;日期模式返回 Date 和字符串,纯时间只返回 HH:mm[:ss] 或 null。
size'sm' | 'md' | 'lg''md'选择器尺寸
status'error' | 'warning'—校验状态
disabledbooleanfalse禁用交互。
inputReadOnlyboolean—只禁止手动输入,仍可在面板中选择。
allowClearbooleantrue展示清除按钮
minDateDate—最早可选日期;datetime 模式按完整时间戳比较,含边界。
maxDateDate—最晚可选日期;datetime 模式按完整时间戳比较,含边界。
disabledDate(date: Date) => boolean—限制可选择日期
minTimestring—最早可选时间(含边界),格式为 HH:mm 或 HH:mm:ss。
maxTimestring—最晚可选时间(含边界),格式为 HH:mm 或 HH:mm:ss。
disabledTime((parts: TimeParts, date: Date) => boolean) | ((parts: TimeParts) => boolean)—按业务规则禁用时间,输入和面板选择使用同一规则。
needConfirmbooleanpicker === "datetime"要求点击确定或按 Enter 提交;开启后失焦放弃草稿。
showSecondsbooleanfalse显示并编辑秒,关闭时秒为 0。
use12Hoursbooleanfalse使用 12 小时制与上午 / 下午。
minuteStepnumber1分钟段步进与分钟列间隔,保留已有的非步长值。
secondStepnumber1秒段步进与秒列间隔,保留已有的非步长值。
formatstring | ((date: Date) => string)—显示格式;日期支持 YYYY、MM、DD、HH、mm、ss、Q。
parse(text: string) => Date | null—自定义文本解析,失败时返回 null。
presetsreadonly DatePreset[]—快捷选项;value 可以动态计算。
showTodaybooleantrue展示今天快捷按钮
todayTextReactNode语言默认值自定义今天按钮文字
renderExtraFooterReactNode—额外底部内容,可放快捷操作
panelValueDate—受控的日历显示日期。
onPanelChange(date: Date) => void—日历显示的周期改变时调用。
cellRender(date: Date) => ReactNode—自定义日历单元格内容。
openboolean—控制面板是否展开。
defaultOpenboolean—面板初始展开状态。
onOpenChange(open: boolean) => void—日历展开或收起
panelVariant'plain' | 'card''plain'面板外观;card 在柔和画布上以内嵌内容卡呈现。
namestring—原生 FormData 中的字段名。
formstring—关联的原生表单 ID。
requiredbooleanfalse要求整体值非空,复合控件只校验一次。
popupPlacement'top' | 'top-start' | 'top-end' | 'bottom' | 'bottom-start' | 'bottom-end' | 'left' | 'left-start' | 'left-end' | 'right' | 'right-start' | 'right-end'—浮层相对触发控件的位置。
popupClassNamestring—浮层的自定义类名。
popupStyleCSSProperties—浮层的自定义样式。
popupRender(content: React.ReactNode) => React.ReactNode—包装或补充面板内容,保留传入的内容以维持交互。
getPopupContainer() => Element | DocumentFragment—返回浮层的挂载容器,也可返回 ShadowRoot。
refRef<HTMLInputElement>—输入框引用

其余原生 input 属性和 aria-* 传给输入框,className / style 作用于外层。共享浮层配置见 PopupOptions。

SingleDatePicker API

日期模式的值与回调类型;通用参数见主表。

属性类型默认值说明
valueDate | null—受控值。
defaultValueDate | nullnull初始值;非受控模式支持表单重置。
onChange(value: Date | null, dateString: string) => void—提交选择时返回日期和格式化字符串;清空返回 null 和空字符串。

DatePreset

presets 使用的快捷项类型。T 在单值中为 Date,在区间中为日期元组;函数应同步、无副作用,并允许多次求值。

属性类型默认值说明
keystring—稳定且唯一的标识。
labelReactNode必填展示文字或内容。
valueT | (() => T)必填快捷项的值或同步取值函数;函数应无副作用,允许多次求值。

TimePickerMode API

picker="time" 的属性与回调,值始终使用 24 小时制字符串。

属性类型默认值说明
picker'time'必填纯时间模式,必须传 time。
valuestring | null—受控的 24 小时制 HH:mm 或 HH:mm:ss 字符串;空值为 null。
defaultValuestring | nullnull初始值;非受控模式支持表单重置。
onChange(value: string | null) => void—提交时只返回 24 小时制字符串;清空返回 null。
size'sm' | 'md' | 'lg''md'展示尺寸。
status'error' | 'warning'—显示错误或警告的校验外观,不执行校验。
allowClearbooleantrue展示清除操作。
inputReadOnlyboolean—只禁止手动输入,仍可在面板中选择。
minTimestring—最早可选时间(含边界),格式为 HH:mm 或 HH:mm:ss。
maxTimestring—最晚可选时间(含边界),格式为 HH:mm 或 HH:mm:ss。
disabledTime(parts: TimeParts) => boolean—按业务规则禁用时间,输入和面板选择使用同一规则。
needConfirmbooleanfalse要求点击确定或按 Enter 提交;开启后失焦放弃草稿。
showSecondsbooleanfalse显示并编辑秒,关闭时秒为 0。
use12Hoursbooleanfalse使用 12 小时制与上午 / 下午。
minuteStepnumber1分钟段步进与分钟列间隔,保留已有的非步长值。
secondStepnumber1秒段步进与秒列间隔,保留已有的非步长值。
openboolean—控制面板是否展开。
defaultOpenboolean—面板初始展开状态。
onOpenChange(open: boolean) => void—面板展开或收起时调用。
panelVariant'plain' | 'card''plain'面板外观;card 在柔和画布上以内嵌内容卡呈现。
popupPlacement'top' | 'top-start' | 'top-end' | 'bottom' | 'bottom-start' | 'bottom-end' | 'left' | 'left-start' | 'left-end' | 'right' | 'right-start' | 'right-end'—浮层相对触发控件的位置。
popupClassNamestring—浮层的自定义类名。
popupStyleCSSProperties—浮层的自定义样式。
popupRender(content: React.ReactNode) => React.ReactNode—包装或补充面板内容,保留传入的内容以维持交互。
getPopupContainer() => Element | DocumentFragment—返回浮层的挂载容器,也可返回 ShadowRoot。

TimeParts

disabledTime 接收的时间部分。

属性类型默认值说明
hournumber必填小时,使用 0–23 的整数。
minutenumber必填分钟,使用 0–59 的整数。
secondnumber必填秒,使用 0–59 的整数。