> Leaf UI 0.17.3 · Package: @ifhover/leaf-ui · Source: c3221834f84f2f48481a2054026b713456f8e5dc
> Browser documentation: https://ifhover.github.io/leaf-ui/components/date-range-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.

# DateRangePicker 日期区间选择器

选择起止日期、日期时间或时间区间。日期模式使用本地 `Date` 元组，纯时间模式使用字符串元组；选择单值使用 [DatePicker](https://ifhover.github.io/leaf-ui/components/date-picker.md)。


## 基础用法

先选起点，再选终点，完整区间会提交并收起。日期模式支持逆序选择，结果按起止顺序排列；`defaultValue` 设置非受控初始区间。


日期区间

basic.tsx

复制代码

```tsx lineNumbers file="../../src/examples/date-range-picker/basic.tsx"
import { DateRangePicker, Form, FormField } from '@ifhover/leaf-ui';

export function DateRangePickerBasic() {
  return (
    <Form layout="vertical" onSubmit={(event) => event.preventDefault()}>
      <FormField label="日期区间">
        <DateRangePicker />
      </FormField>
    </Form>
  );
}
```

展开代码


## 示例

### 受控值与选择过程

`onChange` 接收提交后的区间和两个格式化字符串，清除时为 `null` 和 `['', '']`。`onCalendarChange` 用于观察面板选择草稿和当前端点，不代表整个区间已经提交，也不覆盖文本输入或快捷区间的所有变化。受控重置由应用更新状态。


受控日期区间

已提交：2026-10-05 ~ 2026-10-09最近面板操作：尚未调整重置

controlled.tsx

复制代码

```tsx lineNumbers file="../../src/examples/date-range-picker/controlled.tsx"
import { Button, type DateRange, DateRangePicker, Form, FormField, Text } from '@ifhover/leaf-ui';
import { useState } from 'react';

const initialRange: DateRange = [new Date(2026, 9, 5), new Date(2026, 9, 9)];

function formatDate(date: Date | null) {
  if (!date) return '-';
  return [date.getFullYear(), date.getMonth() + 1, date.getDate()]
    .map((part, index) => (index === 0 ? String(part) : String(part).padStart(2, '0')))
    .join('-');
}

export function DateRangePickerControlled() {
  const [value, setValue] = useState<DateRange | null>(initialRange);
  const [committed, setCommitted] = useState('2026-10-05 ~ 2026-10-09');
  const [draft, setDraft] = useState('尚未调整');

  return (
    <Form
      layout="vertical"
      onSubmit={(event) => event.preventDefault()}
      onReset={() => {
        setValue(initialRange);
        setCommitted('2026-10-05 ~ 2026-10-09');
        setDraft('尚未调整');
      }}
    >
      <FormField label="受控日期区间">
        <DateRangePicker
          value={value}
          onChange={(next: DateRange | null, texts: readonly [string, string]) => {
            setValue(next);
            setCommitted(next ? texts.join(' ~ ') : '空值');
          }}
          onCalendarChange={(next, { position }) => {
            setDraft(`${position}: ${next.map(formatDate).join(' ~ ')}`);
          }}
        />
      </FormField>
      <Text tone="muted" role="status">
        已提交：{committed}
      </Text>
      <Text tone="muted" role="status">
        最近面板操作：{draft}
      </Text>
      <Button type="reset">重置</Button>
    </Form>
  );
}
```

展开代码

### 选择粒度

通过 `picker` 选择年、季度、月或周区间，两个 `Date` 都表示对应周期的起点。周起点由 [ConfigProvider](https://ifhover.github.io/leaf-ui/components/config-provider.md) 的 `weekStartsOn` 设置，默认星期一。


年份区间

季度区间

月份区间

周区间

modes.tsx

复制代码

```tsx lineNumbers file="../../src/examples/date-range-picker/modes.tsx"
import { DateRangePicker, Form, FormField } from '@ifhover/leaf-ui';

export function DateRangePickerModes() {
  return (
    <Form layout="vertical" onSubmit={(event) => event.preventDefault()}>
      <FormField label="年份区间">
        <DateRangePicker picker="year" />
      </FormField>
      <FormField label="季度区间">
        <DateRangePicker picker="quarter" />
      </FormField>
      <FormField label="月份区间">
        <DateRangePicker picker="month" />
      </FormField>
      <FormField label="周区间">
        <DateRangePicker picker="week" />
      </FormField>
    </Form>
  );
}
```

展开代码

### 日期时间区间

设置 `picker="datetime"`，选择开始日期和时间，点击“下一步”进入结束端，再点击“确定”提交。日期时间面板需要结束值不早于开始值；`defaultTime` 只提供新选端点的初始时间，不是初始区间。


预约时段

datetime.tsx

复制代码

```tsx lineNumbers file="../../src/examples/date-range-picker/datetime.tsx"
import { DateRangePicker, Form, FormField } from '@ifhover/leaf-ui';

export function DateRangePickerDateTime() {
  return (
    <Form layout="vertical" onSubmit={(event) => event.preventDefault()}>
      <FormField label="预约时段">
        <DateRangePicker picker="datetime" defaultTime={['09:00', '18:00']} minuteStep={15} />
      </FormField>
    </Form>
  );
}
```

展开代码

此模式默认 `needConfirm={true}`，点击外部会放弃尚未确定的区间。其他日期模式默认选完终点即提交，也可以设置 `needConfirm` 要求确认；`Escape` 放弃当前编辑。清除或选择有效快捷区间会直接提交。

### 限制可选端点

`minDate` / `maxDate` 包含边界，`disabledDate` 可按 `position` 区分起点和终点。下面只允许十月内的端点，周日不能作为端点；区间中间仍可经过周日，需要整段可用性校验时由应用处理。


十月交付周期

disabled-dates.tsx

复制代码

```tsx lineNumbers file="../../src/examples/date-range-picker/disabled-dates.tsx"
import { DateRangePicker, Form, FormField } from '@ifhover/leaf-ui';

export function DisabledDates() {
  return (
    <Form layout="vertical" onSubmit={(event) => event.preventDefault()}>
      <FormField label="十月交付周期">
        <DateRangePicker
          defaultValue={[new Date(2026, 9, 5), new Date(2026, 9, 9)]}
          minDate={new Date(2026, 9, 1)}
          maxDate={new Date(2026, 9, 31)}
          disabledDate={(date) => date.getDay() === 0}
        />
      </FormField>
    </Form>
  );
}
```

展开代码

限制同时用于输入和面板，不会自动清除已有值。日期时间边界按完整时间戳比较，`disabledTime` 接收时间部分、端点位置和当前日期。`inputReadOnly` 只禁止输入，`readOnly` 才禁止修改。

### 开放端点

`allowEmpty` 可逐位允许端点为空。示例使用 `[false, true]` 保留必需的开始日期和可空的结束日期，值类型为从根入口导入的 `OpenDateRange`。至少需要一个非空端点；整个控件清空使用 `null`，不是 `[null, null]`。


进行中的项目周期

起点：2026-10-05；终点：空

open-end.tsx

复制代码

```tsx lineNumbers file="../../src/examples/date-range-picker/open-end.tsx"
import { DateRangePicker, Form, FormField, type OpenDateRange, Text } from '@ifhover/leaf-ui';
import { useState } from 'react';

export function OpenEnd() {
  const [value, setValue] = useState<OpenDateRange | null>([new Date(2026, 9, 5), null]);
  const [texts, setTexts] = useState<readonly [string, string]>(['2026-10-05', '']);

  return (
    <Form layout="vertical" onSubmit={(event) => event.preventDefault()}>
      <FormField label="进行中的项目周期">
        <DateRangePicker
          allowEmpty={[false, true]}
          value={value}
          onChange={(next: OpenDateRange | null, dateStrings: readonly [string, string]) => {
            setValue(next);
            setTexts(dateStrings);
          }}
        />
      </FormField>
      <Text tone="muted" role="status">
        起点：{texts[0] || '空'}；终点：{texts[1] || '空'}
      </Text>
    </Form>
  );
}
```

展开代码

允许的端点可通过面板底部操作清空，缺失端点的回调字符串为 `''`。只有开始值时，再次打开面板会继续编辑结束端。

### 时间区间

`picker="time"` 的值和回调为 `['HH:mm', 'HH:mm']` 或 `null`，开启 `showSeconds` 时使用 `HH:mm:ss`。`use12Hours` 只改变显示，值仍使用 24 小时制；`minTime` / `maxTime` 对两个端点生效。纯时间不支持 `allowEmpty`。


工作时段

当前值：09:00 ~ 18:00

time.tsx

复制代码

```tsx lineNumbers file="../../src/examples/date-range-picker/time.tsx"
import { DateRangePicker, Form, FormField, Text, type TimeRange } from '@ifhover/leaf-ui';
import { useState } from 'react';

export function DateRangePickerTime() {
  const [value, setValue] = useState<TimeRange | null>(['09:00', '18:00']);

  return (
    <Form layout="vertical" onSubmit={(event) => event.preventDefault()}>
      <FormField label="工作时段">
        <DateRangePicker picker="time" value={value} onChange={setValue} />
      </FormField>
      <Text tone="muted" role="status">
        当前值：{value ? value.join(' ~ ') : '空值'}
      </Text>
    </Form>
  );
}
```

展开代码

### 跨越午夜

默认要求结束时间不早于开始时间。设置 `allowOvernight` 后可以提交 `22:00` 到次日 `06:00`，不交换两个端点。时间模式默认离开时提交有效调整，需要明确确认时设置 `needConfirm`。


夜间值班

overnight.tsx

复制代码

```tsx lineNumbers file="../../src/examples/date-range-picker/overnight.tsx"
import { DateRangePicker, Form, FormField } from '@ifhover/leaf-ui';

export function DateRangePickerOvernight() {
  return (
    <Form layout="vertical" onSubmit={(event) => event.preventDefault()}>
      <FormField label="夜间值班">
        <DateRangePicker picker="time" allowOvernight defaultValue={['22:00', '06:00']} />
      </FormField>
    </Form>
  );
}
```

展开代码

### 快捷区间

[](#)
`presets` 提供常用区间，悬停或聚焦时预览，点击有效区间后立即提交并收起。`value` 可以是区间或同步返回区间的函数，不接收 Promise；函数可能多次求值，应保持无副作用。


统计区间

presets.tsx

复制代码

```tsx lineNumbers file="../../src/examples/date-range-picker/presets.tsx"
import { type DateRange, DateRangePicker, Form, FormField } from '@ifhover/leaf-ui';

function recentSevenDays(): DateRange {
  const end = new Date();
  end.setHours(0, 0, 0, 0);
  const start = new Date(end);
  start.setDate(start.getDate() - 6);
  return [start, end];
}

export function Presets() {
  return (
    <Form layout="vertical" onSubmit={(event) => event.preventDefault()}>
      <FormField label="统计区间">
        <DateRangePicker presets={[{ label: '最近七天', value: recentSevenDays }]} />
      </FormField>
    </Form>
  );
}
```

展开代码

### 显示格式与表单提交

`format` 改变显示及 `onChange` 的字符串元组，FormData 仍使用规范格式，以 `start/end` 连接。示例显示 `DD/MM/YYYY`，提交如 `2026-10-05/2026-10-09`；开放尾端为 `2026-10-05/`，全空为空字符串。非受控重置恢复 `defaultValue`。


报表周期

提交重置

FormData：尚未提交

form.tsx

复制代码

```tsx lineNumbers file="../../src/examples/date-range-picker/form.tsx"
import { Button, DateRangePicker, Form, FormField, Space, Text } from '@ifhover/leaf-ui';
import { useState } from 'react';

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

  return (
    <Form
      layout="vertical"
      onSubmit={(event) => {
        event.preventDefault();
        setSubmitted(String(new FormData(event.currentTarget).get('reportingRange') ?? ''));
      }}
      onReset={() => setSubmitted(null)}
    >
      <FormField label="报表周期">
        <DateRangePicker
          name="reportingRange"
          format="DD/MM/YYYY"
          defaultValue={[new Date(2026, 9, 5), new Date(2026, 9, 9)]}
        />
      </FormField>
      <Space>
        <Button type="submit">提交</Button>
        <Button type="reset">重置</Button>
      </Space>
      <Text tone="muted" role="status">
        FormData：{submitted === null ? '尚未提交' : JSON.stringify(submitted)}
      </Text>
    </Form>
  );
}
```

展开代码

周期与日期时间的规范格式及自定义 `parse` 见 [DatePicker：显示格式与表单提交](https://ifhover.github.io/leaf-ui/components/date-picker.md#%E6%98%BE%E7%A4%BA%E6%A0%BC%E5%BC%8F%E4%B8%8E%E8%A1%A8%E5%8D%95%E6%8F%90%E4%BA%A4)。日期是本地日历值，业务时区转换由应用处理。更多表单配置见 [Form](https://ifhover.github.io/leaf-ui/components/form.md)。

日期区间可完整粘贴以 `~` 或“至”分隔的两个值。`Enter` 提交有效输入，无效或未完成输入在离开整个控件时恢复已提交值，`Escape` 放弃编辑；更多分段输入方式见 [DatePicker：输入与确认](https://ifhover.github.io/leaf-ui/components/date-picker.md#%E8%BE%93%E5%85%A5%E4%B8%8E%E7%A1%AE%E8%AE%A4)。


## API

### DateRangePicker API

主表覆盖日期与纯时间分支，参数并非所有模式都适用：`allowEmpty`、`format`、`parse`、`presets`、日期边界及日历配置属于日期分支；`allowOvernight`、`minTime` / `maxTime` 属于纯时间分支。

| 属性                  | 类型                                                                                                                                                                                                                                                                                                 | 默认值                        | 说明                                                                 |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- | ------------------------------------------------------------------ |
| `picker`            | `'year' \| 'quarter' \| 'month' \| 'week' \| 'date' \| 'datetime' \| 'time'`                                                                                                                                                                                                                       | `'date'`                   | 选择日期、时间、日期时间、周、月、季度或年。                                             |
| `value`             | `readonly [Date, Date] \| null \| readonly [Date \| null, Date \| null] \| readonly [string, string]`                                                                                                                                                                                              | —                          | 受控区间；日期模式使用 Date 元组，allowEmpty 允许空端点；纯时间使用 24 小时制字符串元组。整个空值为 null。 |
| `defaultValue`      | `readonly [Date, Date] \| null \| readonly [Date \| null, Date \| null] \| readonly [string, string]`                                                                                                                                                                                              | `null`                     | 非受控初始区间，类型由 picker 决定；表单重置时恢复。                                     |
| `onChange`          | `(((value: readonly [Date, Date] \| null, dateStrings: readonly [string, string]) => void)) \| (((value: readonly [Date \| null, Date \| null] \| null, dateStrings: readonly [string, string]) => void)) \| ((value: readonly [string, string] \| null) => void)`                                 | —                          | 提交整个区间时调用；日期模式返回 Date 元组和字符串元组，纯时间返回字符串元组，清空为 null。                |
| `onCalendarChange`  | `(range: readonly [Date \| null, Date \| null], info: { position: 'start' \| 'end' }) => void`                                                                                                                                                                                                     | —                          | 日期面板草稿、时间或端点清除变化时调用，不代表提交；文本输入和快捷项不保证触发。                           |
| `allowEmpty`        | `false \| true \| readonly [boolean, boolean]`                                                                                                                                                                                                                                                     | `false`                    | 明确允许空的起止端点。                                                        |
| `size`              | `'sm' \| 'md' \| 'lg'`                                                                                                                                                                                                                                                                             | `'md'`                     | 控件尺寸                                                               |
| `status`            | `'error' \| 'warning'`                                                                                                                                                                                                                                                                             | —                          | 校验状态                                                               |
| `disabled`          | `boolean`                                                                                                                                                                                                                                                                                          | `false`                    | 禁用交互。                                                              |
| `inputReadOnly`     | `boolean`                                                                                                                                                                                                                                                                                          | —                          | 只禁止手动输入，仍可在面板中选择。                                                  |
| `allowClear`        | `boolean`                                                                                                                                                                                                                                                                                          | `true`                     | 展示清除按钮                                                             |
| `minDate`           | `Date`                                                                                                                                                                                                                                                                                             | —                          | 最早 / 最晚可选边界                                                        |
| `maxDate`           | `Date`                                                                                                                                                                                                                                                                                             | —                          | 最早 / 最晚可选边界                                                        |
| `disabledDate`      | `(date: Date, position: 'start' \| 'end') => boolean`                                                                                                                                                                                                                                              | —                          | 限制可选端点，不检查区间内的每一天；position 区分开始与结束。                                |
| `minTime`           | `string`                                                                                                                                                                                                                                                                                           | —                          | 最早可选时间（含边界），格式为 HH:mm 或 HH:mm:ss。                                  |
| `maxTime`           | `string`                                                                                                                                                                                                                                                                                           | —                          | 最晚可选时间（含边界），格式为 HH:mm 或 HH:mm:ss。                                  |
| `disabledTime`      | `((parts: `[`TimeParts`](https://ifhover.github.io/leaf-ui/components/date-picker.md#timeparts)`, position: 'start' \| 'end', date: Date) => boolean) \| ((parts: `[`TimeParts`](https://ifhover.github.io/leaf-ui/components/date-picker.md#timeparts)`, position: 'start' \| 'end') => boolean)` | —                          | 限制端点时间；日期时间模式还接收该端点的 Date。                                         |
| `allowOvernight`    | `boolean`                                                                                                                                                                                                                                                                                          | `false`                    | 允许时间区间跨越午夜。                                                        |
| `needConfirm`       | `boolean`                                                                                                                                                                                                                                                                                          | `picker === "datetime"`    | 要求点击确定或按 Enter 提交；开启后失焦放弃草稿。                                       |
| `showSeconds`       | `boolean`                                                                                                                                                                                                                                                                                          | `false`                    | 日期时间区间展示秒，关闭时秒为 0                                                  |
| `use12Hours`        | `boolean`                                                                                                                                                                                                                                                                                          | `false`                    | 使用 12 小时制展示及上午、下午选项                                                |
| `minuteStep`        | `number`                                                                                                                                                                                                                                                                                           | `1`                        | 分钟段步进与分钟列间隔，保留已有的非步长值。                                             |
| `secondStep`        | `number`                                                                                                                                                                                                                                                                                           | `1`                        | 秒段步进与秒列间隔，保留已有的非步长值。                                               |
| `defaultTime`       | `readonly [string, string]`                                                                                                                                                                                                                                                                        | `['00:00:00', '23:59:59']` | datetime 模式下新选开始、结束日期使用的时间，格式为 HH:mm\[:ss]。                        |
| `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/components/date-picker.md#datepreset)`<readonly [Date \| null, Date \| null]>[]`                                                                                                                                                       | —                          | 快捷选项；value 可以动态计算。                                                 |
| `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)。

### DateRange

非开放日期区间的类型是 `readonly [Date, Date]`；设置 `allowEmpty` 时使用根入口导出的 `OpenDateRange`，即 `readonly [Date | null, Date | null]`。快捷项类型见 [DatePreset](https://ifhover.github.io/leaf-ui/components/date-picker.md#datepreset)。

| 属性  | 类型     | 默认值 | 说明           |
| --- | ------ | --- | ------------ |
| `0` | `Date` | 必填  | 起始值，早于或等于终止值 |
| `1` | `Date` | 必填  | 终止值          |

### TimeRangePickerMode API

`picker="time"` 的属性；值类型 `TimeRange` 为 `readonly [string, string]`。

| 属性                  | 类型                                                                                                                                                                   | 默认值       | 说明                                |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | --------------------------------- |
| `picker`            | `'time'`                                                                                                                                                             | 必填        | 纯时间区间模式，必须传 time。                 |
| `value`             | `readonly [string, string] \| null`                                                                                                                                  | —         | 受控的 24 小时制字符串元组；整个空值为 null。       |
| `defaultValue`      | `readonly [string, string] \| null`                                                                                                                                  | `null`    | 初始值；非受控模式支持表单重置。                  |
| `onChange`          | `(value: readonly [string, 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`](https://ifhover.github.io/leaf-ui/components/date-picker.md#timeparts)`, position: 'start' \| 'end') => boolean`                             | —         | 按业务规则禁用时间，输入和面板选择使用同一规则。          |
| `allowOvernight`    | `boolean`                                                                                                                                                            | `false`   | 允许时间区间跨越午夜。                       |
| `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。        |
