> Leaf UI 0.17.3 · Package: @ifhover/leaf-ui · Source: c3221834f84f2f48481a2054026b713456f8e5dc
> Browser documentation: https://ifhover.github.io/leaf-ui/components/date-picker.html

> 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.

# DatePicker 日期选择器

选择日期、时间或日期时间。日期模式使用本地 `Date`，`picker="time"` 使用时间字符串；选择区间请使用 [DateRangePicker](https://ifhover.github.io/leaf-ui/components/date-range-picker.md)。


## 基础用法

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


默认日期

basic.tsx

复制代码

```tsx lineNumbers file="../../src/examples/date-picker/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

复制代码

```tsx lineNumbers file="../../src/examples/date-picker/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

复制代码

```tsx lineNumbers file="../../src/examples/date-picker/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](https://ifhover.github.io/leaf-ui/components/config-provider.md) 的 `weekStartsOn` 设置，默认星期一。


年份

季度

月份

周

extensions.tsx

复制代码

```tsx lineNumbers file="../../src/examples/date-picker/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

复制代码

```tsx lineNumbers file="../../src/examples/date-picker/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

复制代码

```tsx lineNumbers file="../../src/examples/date-picker/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

复制代码

```tsx lineNumbers file="../../src/examples/date-picker/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`。


12 小时制

精确到秒

twelve-hours.tsx

复制代码

```tsx lineNumbers file="../../src/examples/date-picker/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

复制代码

```tsx lineNumbers file="../../src/examples/date-picker/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](https://ifhover.github.io/leaf-ui/components/form.md)。

### 快捷日期

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


交付日期

presets.tsx

复制代码

```tsx lineNumbers file="../../src/examples/date-picker/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'`                | 选择日期、时间、日期时间、周、月、季度或年。                             |
| `value`             | `Date \| null \| string`                                                                                                                                             | —                       | 受控值：日期 / 日期时间为 Date，纯时间为 HH:mm\[:ss] 字符串；空值为 null。 |
| `defaultValue`      | `Date \| null \| string`                                                                                                                                             | `null`                  | 非受控初始值，类型由 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'`                                                                                                                                               | —                       | 校验状态                                               |
| `disabled`          | `boolean`                                                                                                                                                            | `false`                 | 禁用交互。                                              |
| `inputReadOnly`     | `boolean`                                                                                                                                                            | —                       | 只禁止手动输入，仍可在面板中选择。                                  |
| `allowClear`        | `boolean`                                                                                                                                                            | `true`                  | 展示清除按钮                                             |
| `minDate`           | `Date`                                                                                                                                                               | —                       | 最早可选日期；datetime 模式按完整时间戳比较，含边界。                    |
| `maxDate`           | `Date`                                                                                                                                                               | —                       | 最晚可选日期；datetime 模式按完整时间戳比较，含边界。                    |
| `disabledDate`      | `(date: Date) => boolean`                                                                                                                                            | —                       | 限制可选择日期                                            |
| `minTime`           | `string`                                                                                                                                                             | —                       | 最早可选时间（含边界），格式为 HH:mm 或 HH:mm:ss。                  |
| `maxTime`           | `string`                                                                                                                                                             | —                       | 最晚可选时间（含边界），格式为 HH:mm 或 HH:mm:ss。                  |
| `disabledTime`      | `((parts: `[`TimeParts`](#timeparts)`, date: Date) => boolean) \| ((parts: `[`TimeParts`](#timeparts)`) => boolean)`                                                 | —                       | 按业务规则禁用时间，输入和面板选择使用同一规则。                           |
| `needConfirm`       | `boolean`                                                                                                                                                            | `picker === "datetime"` | 要求点击确定或按 Enter 提交；开启后失焦放弃草稿。                       |
| `showSeconds`       | `boolean`                                                                                                                                                            | `false`                 | 显示并编辑秒，关闭时秒为 0。                                    |
| `use12Hours`        | `boolean`                                                                                                                                                            | `false`                 | 使用 12 小时制与上午 / 下午。                                 |
| `minuteStep`        | `number`                                                                                                                                                             | `1`                     | 分钟段步进与分钟列间隔，保留已有的非步长值。                             |
| `secondStep`        | `number`                                                                                                                                                             | `1`                     | 秒段步进与秒列间隔，保留已有的非步长值。                               |
| `format`            | `string \| ((date: Date) => string)`                                                                                                                                 | —                       | 显示格式；日期支持 YYYY、MM、DD、HH、mm、ss、Q。                   |
| `parse`             | `(text: string) => Date \| null`                                                                                                                                     | —                       | 自定义文本解析，失败时返回 null。                                |
| `presets`           | `readonly `[`DatePreset`](#datepreset)`[]`                                                                                                                           | —                       | 快捷选项；value 可以动态计算。                                 |
| `showToday`         | `boolean`                                                                                                                                                            | `true`                  | 展示今天快捷按钮                                           |
| `todayText`         | `ReactNode`                                                                                                                                                          | 语言默认值                   | 自定义今天按钮文字                                          |
| `renderExtraFooter` | `ReactNode`                                                                                                                                                          | —                       | 额外底部内容，可放快捷操作                                      |
| `panelValue`        | `Date`                                                                                                                                                               | —                       | 受控的日历显示日期。                                         |
| `onPanelChange`     | `(date: Date) => void`                                                                                                                                               | —                       | 日历显示的周期改变时调用。                                      |
| `cellRender`        | `(date: Date) => ReactNode`                                                                                                                                          | —                       | 自定义日历单元格内容。                                        |
| `open`              | `boolean`                                                                                                                                                            | —                       | 控制面板是否展开。                                          |
| `defaultOpen`       | `boolean`                                                                                                                                                            | —                       | 面板初始展开状态。                                          |
| `onOpenChange`      | `(open: boolean) => void`                                                                                                                                            | —                       | 日历展开或收起                                            |
| `panelVariant`      | `'plain' \| 'card'`                                                                                                                                                  | `'plain'`               | 面板外观；card 在柔和画布上以内嵌内容卡呈现。                          |
| `name`              | `string`                                                                                                                                                             | —                       | 原生 FormData 中的字段名。                                 |
| `form`              | `string`                                                                                                                                                             | —                       | 关联的原生表单 ID。                                        |
| `required`          | `boolean`                                                                                                                                                            | `false`                 | 要求整体值非空，复合控件只校验一次。                                 |
| `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。                         |
| `ref`               | `Ref<HTMLInputElement>`                                                                                                                                              | —                       | 输入框引用                                              |

其余原生 input 属性和 `aria-*` 传给输入框，`className` / `style` 作用于外层。共享浮层配置见 [PopupOptions](https://ifhover.github.io/leaf-ui/api/popup-options.md)。

### SingleDatePicker API

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

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

### DatePreset

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

| 属性      | 类型               | 默认值 | 说明                           |
| ------- | ---------------- | --- | ---------------------------- |
| `key`   | `string`         | —   | 稳定且唯一的标识。                    |
| `label` | `ReactNode`      | 必填  | 展示文字或内容。                     |
| `value` | `T \| (() => T)` | 必填  | 快捷项的值或同步取值函数；函数应无副作用，允许多次求值。 |

### TimePickerMode API

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

| 属性                  | 类型                                                                                                                                                                   | 默认值       | 说明                                        |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ----------------------------------------- |
| `picker`            | `'time'`                                                                                                                                                             | 必填        | 纯时间模式，必须传 time。                           |
| `value`             | `string \| null`                                                                                                                                                     | —         | 受控的 24 小时制 HH:mm 或 HH:mm:ss 字符串；空值为 null。 |
| `defaultValue`      | `string \| null`                                                                                                                                                     | `null`    | 初始值；非受控模式支持表单重置。                          |
| `onChange`          | `(value: string \| null) => void`                                                                                                                                    | —         | 提交时只返回 24 小时制字符串；清空返回 null。               |
| `size`              | `'sm' \| 'md' \| 'lg'`                                                                                                                                               | `'md'`    | 展示尺寸。                                     |
| `status`            | `'error' \| 'warning'`                                                                                                                                               | —         | 显示错误或警告的校验外观，不执行校验。                       |
| `allowClear`        | `boolean`                                                                                                                                                            | `true`    | 展示清除操作。                                   |
| `inputReadOnly`     | `boolean`                                                                                                                                                            | —         | 只禁止手动输入，仍可在面板中选择。                         |
| `minTime`           | `string`                                                                                                                                                             | —         | 最早可选时间（含边界），格式为 HH:mm 或 HH:mm:ss。         |
| `maxTime`           | `string`                                                                                                                                                             | —         | 最晚可选时间（含边界），格式为 HH:mm 或 HH:mm:ss。         |
| `disabledTime`      | `(parts: `[`TimeParts`](#timeparts)`) => boolean`                                                                                                                    | —         | 按业务规则禁用时间，输入和面板选择使用同一规则。                  |
| `needConfirm`       | `boolean`                                                                                                                                                            | `false`   | 要求点击确定或按 Enter 提交；开启后失焦放弃草稿。              |
| `showSeconds`       | `boolean`                                                                                                                                                            | `false`   | 显示并编辑秒，关闭时秒为 0。                           |
| `use12Hours`        | `boolean`                                                                                                                                                            | `false`   | 使用 12 小时制与上午 / 下午。                        |
| `minuteStep`        | `number`                                                                                                                                                             | `1`       | 分钟段步进与分钟列间隔，保留已有的非步长值。                    |
| `secondStep`        | `number`                                                                                                                                                             | `1`       | 秒段步进与秒列间隔，保留已有的非步长值。                      |
| `open`              | `boolean`                                                                                                                                                            | —         | 控制面板是否展开。                                 |
| `defaultOpen`       | `boolean`                                                                                                                                                            | —         | 面板初始展开状态。                                 |
| `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'` | —         | 浮层相对触发控件的位置。                              |
| `popupClassName`    | `string`                                                                                                                                                             | —         | 浮层的自定义类名。                                 |
| `popupStyle`        | `CSSProperties`                                                                                                                                                      | —         | 浮层的自定义样式。                                 |
| `popupRender`       | `(content: React.ReactNode) => React.ReactNode`                                                                                                                      | —         | 包装或补充面板内容，保留传入的内容以维持交互。                   |
| `getPopupContainer` | `() => Element \| DocumentFragment`                                                                                                                                  | —         | 返回浮层的挂载容器，也可返回 ShadowRoot。                |

### TimeParts

`disabledTime` 接收的时间部分。

| 属性       | 类型       | 默认值 | 说明              |
| -------- | -------- | --- | --------------- |
| `hour`   | `number` | 必填  | 小时，使用 0–23 的整数。 |
| `minute` | `number` | 必填  | 分钟，使用 0–59 的整数。 |
| `second` | `number` | 必填  | 秒，使用 0–59 的整数。  |
