> Leaf UI 0.6.0 · Package: @ifhover/leaf-ui · Source: b30c3d3a8fa9c5e15d0d0522cebfbd33f60c6b06
> Browser documentation: https://ifhover.github.io/leaf-ui/v/0.6.0/components/date-time-picker.html
> For AI agents: the complete documentation index is available at https://ifhover.github.io/leaf-ui/v/0.6.0/llms.txt, the full documentation bundle is available at https://ifhover.github.io/leaf-ui/v/0.6.0/llms-full.txt.
# DateTimePicker 日期时间选择器
选择一个具体的日期与时间。
## 日期与时间
预约时间
12小时预约时间
限定时间
basic.tsx
复制代码
```tsx lineNumbers file="../../src/examples/date-time-picker/basic.tsx"
import { DateTimePicker, Form, FormField } from '@ifhover/leaf-ui';
export function DateTimePickerBasic() {
return (
);
}
```
展开代码
## 自定义格式与营业时间
营业时间、自定义格式与快捷预设
capabilities.tsx
复制代码
```tsx lineNumbers file="../../src/examples/date-time-picker/capabilities.tsx"
import { DateTimePicker, Space, Text } from '@ifhover/leaf-ui';
export function Capabilities() {
return (
{'营业时间、自定义格式与快捷预设'}
date.getDay() === 0}
disabledTime={(date) => date.hour < 9 || date.hour > 18}
presets={[
{
label: '明天十点',
value: () => {
const date = new Date();
date.setDate(date.getDate() + 1);
date.setHours(10, 0, 0, 0);
return date;
},
},
]}
/>
);
}
```
展开代码
## 显示格式与提交值
`format` 改变显示文字和 `onChange` 的字符串参数；FormData 保持日期或周期的稳定序列化格式。方括号可以转义固定文字，例如 `YYYY-[Q]Q`。使用函数格式化时，请同时提供 `parse`。Date 表示本地日历值，业务时区在应用的数据边界完成转换。周起点通过 ConfigProvider 的 `weekStartsOn` 设置。
## DateTimePicker 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` | — | 面板初始展开状态。 |
| `value` | `Date \| null` | `null` | 受控值 / 初始值 |
| `defaultValue` | `Date \| null` | `null` | 受控值 / 初始值 |
| `minDate` | `Date` | — | 可选边界，精确到时间 |
| `maxDate` | `Date` | — | 可选边界，精确到时间 |
| `use12Hours` | `boolean` | `false` | 使用 12 小时制展示及上午、下午选项 |
| `showSeconds` | `boolean` | `true` | 显示秒选项；关闭时提交秒为 0 |
| `minuteStep` | `number` | `1` | 分钟 / 秒间隔，1–60 的整数 |
| `secondStep` | `number` | `1` | 分钟 / 秒间隔，1–60 的整数 |
| `showToday` | `boolean` | `true` | 展示今天快捷按钮 |
| `todayText` | `ReactNode` | 语言默认值 | 自定义今天按钮文字 |
| `renderExtraFooter` | `ReactNode` | — | 额外底部内容，可放快捷操作 |
| `onChange` | `(value: Date \| null, dateString: string) => void` | — | 确认返回 Date 与本地日期时间字符串；清除返回 null |
| `onOpenChange` | `(open: boolean) => void` | — | 面板展开或收起 |
| `disabledDate` | `(date: Date) => boolean` | — | 按业务规则禁用日期。 |
| `disabledTime` | `(parts: `[`TimeParts`](https://ifhover.github.io/leaf-ui/v/0.6.0/components/time-picker.md#timeparts)`, date: Date) => boolean` | — | 按业务规则禁用时间，输入和面板选择使用同一规则。 |
| `format` | `string \| ((date: Date) => string)` | — | 显示格式；日期支持 YYYY、MM、DD、HH、mm、ss、Q。 |
| `parse` | `(text: string) => Date \| null` | — | 自定义文本解析，失败时返回 null。 |
| `presets` | `readonly `[`DatePreset`](https://ifhover.github.io/leaf-ui/v/0.6.0/components/date-picker.md#datepreset)`[]` | — | 快捷选项；value 可以动态计算。 |
| `panelValue` | `Date` | — | 受控的日历显示日期。 |
| `onPanelChange` | `(date: Date) => void` | — | 日历显示的周期改变时调用。 |
| `cellRender` | `(date: Date) => ReactNode` | — | 自定义日历单元格内容。 |
| `disabled` | `boolean` | `false` | 禁用交互。 |
| `required` | `boolean` | `false` | 要求整体值非空，复合控件只校验一次。 |
| `name` | `string` | — | 原生 FormData 中的字段名。 |
| `form` | `string` | — | 关联的原生表单 ID。 |
| `ref` | `Ref` | — | 输入框引用 |
## 类型
定义组件属性或组装变量时可导入相关类型。
```ts
import type { DateTimePickerProps } from '@ifhover/leaf-ui';
```
## 使用说明
点击面板右上角的时间，在日历与时间面板间切换。“今天”调整草稿日期；时间面板中的“当前时间”设置当前日期时间。可通过 `showToday`、`todayText`、`renderExtraFooter` 定制快捷操作。
可以输入 `YYYY-MM-DD HH:mm:ss`，关闭秒时使用 `YYYY-MM-DD HH:mm`。时间支持 24 小时制、AM/PM 和上午/下午。按 Enter 或点击确定提交草稿；Escape 或点击外部放弃调整。无效或越界输入不会提交。
日期使用本地时区；12 小时制只影响展示，Date 与 FormData 保持 24 小时格式。原生 input 属性与 aria-\* 透传至输入框，className / style 作用于外层。非受控组件支持表单 reset；受控时自行重置 value。