DateRangePicker 日期区间选择器

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

受控区间

basic.tsx

import { type DateRange, DateRangePicker, Form, FormField, Text } from '@ifhover/leaf-ui';

import { useState } from 'react';

export function DateRangePickerBasic() {
  const [range, setRange] = useState<DateRange | null>(null);
  return (
    <Form layout="vertical">
      <FormField label="日期区间">
        <DateRangePicker aria-label="日期区间" value={range} onChange={setRange} />
      </FormField>
      {range && (
        <output>
          <Text tone="muted">
            {range[0].toLocaleDateString()} – {range[1].toLocaleDateString()}
          </Text>
        </output>
      )}
    </Form>
  );
}

选择粒度

modes.tsx

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

export function DateRangePickerModes() {
  return (
    <Form layout="vertical">
      <FormField label="年份区间">
        <DateRangePicker aria-label="年份区间" picker="year" placeholder="年份区间" />
      </FormField>
      <FormField label="月份区间">
        <DateRangePicker aria-label="月份区间" picker="month" placeholder="月份区间" />
      </FormField>
      <FormField label="周区间">
        <DateRangePicker aria-label="周区间" picker="week" placeholder="周区间" />
      </FormField>
      <FormField label="日期时间区间">
        <DateRangePicker
          aria-label="日期时间区间"
          picker="datetime"
          placeholder="日期时间区间"
          use12Hours
        />
      </FormField>
    </Form>
  );
}

季度、预设与开放端点

季度区间

允许结束为空，或选择最近七天

capabilities.tsx

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

export function Capabilities() {
  return (
    <Space direction="vertical" align="stretch">
      <Flex direction="column" gap="sm" align="center">
        <Text>{'季度区间'}</Text>
        <DateRangePicker picker="quarter" format="YYYY-[Q]Q" />
      </Flex>
      <Flex direction="column" gap="sm" align="center">
        {'允许结束为空，或选择最近七天'}
        <DateRangePicker
          allowEmpty={[false, true]}
          disabledDate={(date) => date.getDay() === 0}
          presets={[
            {
              label: '最近七天',
              value: () => {
                const end = new Date();
                const start = new Date();
                start.setDate(start.getDate() - 6);
                return [start, end];
              },
            },
          ]}
        />
      </Flex>
    </Space>
  );
}

显示格式与提交值

format 改变显示文字和 onChange 的字符串参数；FormData 保持日期或周期的稳定序列化格式。方括号可以转义固定文字，例如 YYYY-[Q]Q。使用函数格式化时，请同时提供 parse。Date 表示本地日历值，业务时区在应用的数据边界完成转换。周起点通过 ConfigProvider 的 weekStartsOn 设置。

DateRangePicker 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`	—	面板初始展开状态。
`picker`	`'year' \| 'quarter' \| 'month' \| 'week' \| 'date' \| 'datetime'`	`'date'`	选择粒度
`minDate`	`Date`	—	最早 / 最晚可选边界
`maxDate`	`Date`	—	最早 / 最晚可选边界
`use12Hours`	`boolean`	`false`	使用 12 小时制展示及上午、下午选项
`showSeconds`	`boolean`	`true`	日期时间区间展示秒，关闭时秒为 0
`minuteStep`	`number`	`1`	分钟 / 秒间隔，1–60 的整数
`secondStep`	`number`	`1`	分钟 / 秒间隔，1–60 的整数
`onOpenChange`	`(open: boolean) => void`	—	面板展开或收起
`disabledDate`	`(date: Date, position: 'start' \| 'end') => boolean`	—	按业务规则禁用日期。
`disabledTime`	`(parts: TimeParts, position: 'start' \| 'end', date: Date) => boolean`	—	按业务规则禁用时间，输入和面板选择使用同一规则。
`format`	`string \| ((date: Date) => string)`	—	显示格式；日期支持 YYYY、MM、DD、HH、mm、ss、Q。
`parse`	`(text: string) => Date \| null`	—	自定义文本解析，失败时返回 null。
`presets`	`readonly DatePreset<readonly [Date \| null, Date \| null]>[]`	—	快捷选项；value 可以动态计算。
`onCalendarChange`	`(range: readonly [Date \| null, Date \| null], info: { position: 'start' \| 'end' }) => void`	—	选择过程中的日期变化，包含当前起止位置。
`panelValue`	`Date`	—	受控的日历显示日期。
`onPanelChange`	`(date: Date) => void`	—	日历显示的周期改变时调用。
`cellRender`	`(date: Date) => ReactNode`	—	自定义日历单元格内容。
`allowEmpty`	`false \| true \| readonly [boolean, boolean]`	`false`	明确允许空的起止端点。
`value`	`readonly [Date, Date] \| null \| readonly [Date \| null, Date \| null] \| null`	`null`	受控区间 / 初始区间
`defaultValue`	`readonly [Date, Date] \| null \| readonly [Date \| null, Date \| null] \| null`	`null`	受控区间 / 初始区间
`onChange`	`((value: readonly [Date, Date] \| null, dateStrings: readonly [string, string]) => void) \| ((value: readonly [Date \| null, Date \| null] \| null, dateStrings: readonly [string, string]) => void)`	—	完成选择后返回有序区间与字符串；清除返回 null
`disabled`	`boolean`	`false`	禁用交互。
`required`	`boolean`	`false`	要求整体值非空，复合控件只校验一次。
`name`	`string`	—	原生 FormData 中的字段名。
`form`	`string`	—	关联的原生表单 ID。
`ref`	`Ref<HTMLInputElement>`	—	输入框引用

DateRange

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

类型

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

import type { DateRangePickerProps, DateRange } from '@ifhover/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

#类型

#使用说明