DateTimePicker 日期时间选择器

选择一个具体的日期与时间。

日期与时间

basic.tsx

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

export function DateTimePickerBasic() {
  return (
    <Form layout="vertical">
      <FormField label="预约时间">
        <DateTimePicker aria-label="预约时间" defaultValue={new Date(2026, 9, 3, 14, 30)} />
      </FormField>
      <FormField label="12小时预约时间">
        <DateTimePicker aria-label="12小时预约时间" use12Hours minuteStep={15} secondStep={10} />
      </FormField>
      <FormField label="限定时间">
        <DateTimePicker
          aria-label="限定时间"
          minDate={new Date(2026, 9, 1)}
          maxDate={new Date(2026, 9, 31, 23, 59, 59)}
          placeholder="选择十月的时间"
        />
      </FormField>
    </Form>
  );
}

自定义格式与营业时间

营业时间、自定义格式与快捷预设

capabilities.tsx

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

export function Capabilities() {
  return (
    <Space direction="vertical" align="stretch">
      <Text>
        {'营业时间、自定义格式与快捷预设'}
      </Text>
      <DateTimePicker
        format="DD/MM/YYYY HH:mm"
        showSeconds={false}
        disabledDate={(date) => 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;
            },
          },
        ]}
      />
    </Space>
  );
}

显示格式与提交值

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, date: Date) => boolean`	—	按业务规则禁用时间，输入和面板选择使用同一规则。
`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`	—	自定义日历单元格内容。
`disabled`	`boolean`	`false`	禁用交互。
`required`	`boolean`	`false`	要求整体值非空，复合控件只校验一次。
`name`	`string`	—	原生 FormData 中的字段名。
`form`	`string`	—	关联的原生表单 ID。
`ref`	`Ref<HTMLInputElement>`	—	输入框引用

类型

定义组件属性或组装变量时可导入相关类型。

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。

#DateTimePicker 日期时间选择器

#日期与时间

#自定义格式与营业时间

#显示格式与提交值

#DateTimePicker API

#类型