DateRangePicker 日期区间选择器

选择起止日期或时间，限定一个区间。

受控区间

交互预览受控区间

basic.tsx

import { type DateRange, DateRangePicker } from '@sudden3/leaf-ui';
import { useState } from 'react';
export function DateRangePickerBasic() {
  const [range, setRange] = useState<DateRange | null>(null);
  return (
    <div className="leaf-demo-stack">
      <DateRangePicker aria-label="日期区间" value={range} onChange={setRange} />
      {range && (
        <output className="leaf-demo-note">
          {range[0].toLocaleDateString()} – {range[1].toLocaleDateString()}
        </output>
      )}
    </div>
  );
}

选择粒度

交互预览选择粒度

modes.tsx

import { DateRangePicker } from '@sudden3/leaf-ui';
export function DateRangePickerModes() {
  return (
    <div className="leaf-demo-stack leaf-demo-stack--wide">
      <DateRangePicker aria-label="年份区间" picker="year" placeholder="年份区间" />
      <DateRangePicker aria-label="月份区间" picker="month" placeholder="月份区间" />
      <DateRangePicker aria-label="周区间" picker="week" placeholder="周区间" />
      <DateRangePicker
        aria-label="日期时间区间"
        picker="datetime"
        placeholder="日期时间区间"
        use12Hours
      />
    </div>
  );
}

DateRangePicker API

属性	类型	默认值	说明
`value / defaultValue`	`DateRange \| null`	`null`	受控区间 / 初始区间
`onChange`	`(value: DateRange \| null, dateStrings: readonly [string, string]) => void`	—	完成选择后返回有序区间与字符串；清除返回 null
`picker`	`'year' \| 'month' \| 'week' \| 'date' \| 'datetime'`	`'date'`	选择粒度
`minDate / maxDate`	`Date`	—	最早 / 最晚可选边界
`showSeconds`	`boolean`	`true`	日期时间区间展示秒，关闭时秒为 0
`use12Hours`	`boolean`	`false`	使用 12 小时制展示及上午、下午选项
`minuteStep / secondStep`	`number`	`1`	分钟 / 秒间隔，1–60 的整数
`allowClear`	`boolean`	`true`	展示清除按钮
`size`	`'sm' \| 'md' \| 'lg'`	`'md'`	控件尺寸
`status`	`'error' \| 'warning'`	—	校验状态
`disabled / required`	`boolean`	`false`	禁用 / 必填，可继承 FormField
`placeholder / name / form`	`string`	—	提示文字 / 字段名 / 表单 ID
`onOpenChange`	`(open: boolean) => void`	—	面板展开或收起
`ref`	`Ref<HTMLInputElement>`	—	输入框引用

DateRange

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

类型

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

import type { DateRangePickerProps, DateRange } from '@sudden3/leaf-ui';

使用说明

DateRange 是 readonly [Date, Date]，可导入它组装变量。年取 1 月 1 日，月取当月 1 日，周从星期一开始并使用 ISO 周编号。日期使用本地时间。

两个日历联动导航。选好起点后，悬停年份、月份、周或日期即可预览区间；选好终点立即完成，所有模式都没有底部确定按钮。逆序选择会自动排列。

日期时间区间通过两个日历右上角的时间按钮分别调整起止时间，再返回日期面板选择日期。请在选定结束日期前调整时间。“当前时间”设置该端点的时间。

已有完整区间时，调整任一端点的时间会直接更新有效区间，无需重新选择日期。

也可以输入以 ~ 分隔的两个值，按 Enter 或移走焦点提交。格式依次为 YYYY、YYYY-MM、YYYY-Www、YYYY-MM-DD、YYYY-MM-DD HH:mm:ss；关闭秒时省略秒。无效或越界输入不会提交，Escape 放弃未完成的输入。

FormData 使用 start/end 格式提交对应字符串。非受控组件支持表单 reset；受控组件需同步重置自己的状态。

#DateRangePicker 日期区间选择器

#受控区间

#选择粒度

#DateRangePicker API

#DateRange

#类型