DateRangePicker

date-range-picker

日期区间 · 自研零依赖双月范围日历(避开 MUI Pro 收费) + Popover 引擎 + 快捷预设/min-max/disabledDate · ISO 数组受控

用法

基础用法

点击触发器弹出双月日历，依次选起止两端确定区间。

tsx

<DateRangePicker defaultValue={["2026-06-08", "2026-06-20"]} />

受控

对外受控值为 [start, end]（ISO YYYY-MM-DD），清空回传 null。

tsx

const [range, setRange] = useState<DateRangeValue | null>(["2026-06-08", "2026-06-20"]);

<DateRangePicker value={range} onValueChange={setRange} />

无快捷预设

presets={false} 隐藏左侧「今天 / 最近 7 天…」预设栏。

tsx

<DateRangePicker defaultValue={["2026-06-03", "2026-06-09"]} presets={false} />

限定范围 + 禁用周末

minDate / maxDate 框定可选区间，disabledDate 进一步禁选某些天。

tsx

<DateRangePicker
  defaultValue={["2026-06-10", "2026-06-12"]}
  minDate="2026-06-01"
  maxDate="2026-06-30"
  disabledDate={(iso) => {
    const day = new Date(iso + "T00:00:00").getDay();
    return day === 0 || day === 6;
  }}
/>

禁用

整体置灰，触发器不可打开。

tsx

<DateRangePicker defaultValue={["2026-06-01", "2026-06-15"]} disabled />

何时用

选一段日期区间（起止两端）时用，自带双月并排 + 快捷预设（今天/最近7天/30天/本月）。选单个日期用 DatePicker；连时间一起选用 DateTimePicker；月历常驻铺开用 Calendar。本组件零依赖自研，不引 MUI Pro。

导入

import { DateRangePicker } from "@hulianui/ui"

Props

名称	类型	默认	说明
value	`[string, string] \| null`	—	受控值 `[start, end]`（ISO `YYYY-MM-DD`）；`null` = 已清空；传入即受控
defaultValue	`[string, string] \| null`	—	非受控初始值
minDate	`string`	—	最早可选日（ISO），早于此禁选
maxDate	`string`	—	最晚可选日（ISO），晚于此禁选
disabledDate	`(isoDate: string) => boolean`	—	自定义禁用某天，入参为 ISO `YYYY-MM-DD`
presets	`boolean \| DateRangePreset[]`	`true`	快捷预设：`true`/省略 = 默认四项；数组 = 自定义；`false` = 隐藏
placeholder	`[string, string]`	`["开始日期","结束日期"]`	占位文案 [开始, 结束]
displayFormat	`string`	`"YYYY-MM-DD"`	展示格式（dayjs format）；对外受控值始终为 ISO `YYYY-MM-DD`
disabled	`boolean`	`false`	禁用
readOnly	`boolean`	`false`	只读：可打开查看，无端点选择/无预设/无清除
className	`string`	—	容器类名

Events

事件	类型	说明
onValueChange	`(range: [string, string] \| null) => void`	区间变化（含清空 → null）

DateRangePreset：{ label: string; getValue: () => [string, string] }，点击时调用、可基于"今天"动态计算。

禁忌 / 坑

受控/非受控二选一：给 value 走受控须配 onValueChange；只想要初值用 defaultValue，别同时给。
对外受控值恒为 ISO YYYY-MM-DD 数组（不是 Date）；displayFormat 只改输入框展示，回传值不变。
disabledDate 入参是 ISO 字符串，自己拼 new Date(iso + "T00:00:00") 算 getDay 时注意时区，别直接 new Date(iso)（会按 UTC 解析偏一天）。

Playground

快捷预设禁用只读

<DateRangePicker
  value={range}
  onValueChange={setRange}
/>

用法

基础用法

点击触发器弹出双月日历，依次选起止两端确定区间。

tsx

<DateRangePicker defaultValue={["2026-06-08", "2026-06-20"]} />

受控

对外受控值为 [start, end]（ISO YYYY-MM-DD），清空回传 null。

tsx

const [range, setRange] = useState<DateRangeValue | null>(["2026-06-08", "2026-06-20"]);

<DateRangePicker value={range} onValueChange={setRange} />

无快捷预设

presets={false} 隐藏左侧「今天 / 最近 7 天…」预设栏。

tsx

<DateRangePicker defaultValue={["2026-06-03", "2026-06-09"]} presets={false} />

限定范围 + 禁用周末

minDate / maxDate 框定可选区间，disabledDate 进一步禁选某些天。

tsx

<DateRangePicker
  defaultValue={["2026-06-10", "2026-06-12"]}
  minDate="2026-06-01"
  maxDate="2026-06-30"
  disabledDate={(iso) => {
    const day = new Date(iso + "T00:00:00").getDay();
    return day === 0 || day === 6;
  }}
/>

禁用

整体置灰，触发器不可打开。

tsx

<DateRangePicker defaultValue={["2026-06-01", "2026-06-15"]} disabled />

Props

名称	类型	默认	说明
value	`[string, string] \| null`	—	受控值 `[start, end]`（ISO `YYYY-MM-DD`）；`null` = 已清空；传入即受控
defaultValue	`[string, string] \| null`	—	非受控初始值
minDate	`string`	—	最早可选日（ISO），早于此禁选
maxDate	`string`	—	最晚可选日（ISO），晚于此禁选
disabledDate	`(isoDate: string) => boolean`	—	自定义禁用某天，入参为 ISO `YYYY-MM-DD`
presets	`boolean \| DateRangePreset[]`	`true`	快捷预设：`true`/省略 = 默认四项；数组 = 自定义；`false` = 隐藏
placeholder	`[string, string]`	`["开始日期","结束日期"]`	占位文案 [开始, 结束]
displayFormat	`string`	`"YYYY-MM-DD"`	展示格式（dayjs format）；对外受控值始终为 ISO `YYYY-MM-DD`
disabled	`boolean`	`false`	禁用
readOnly	`boolean`	`false`	只读：可打开查看，无端点选择/无预设/无清除
className	`string`	—	容器类名

事件

类型

说明

onValueChange

(range: [string, string] | null) => void

区间变化（含清空 → null）

禁忌 / 坑

受控/非受控二选一：给 value 走受控须配 onValueChange；只想要初值用 defaultValue，别同时给。

对外受控值恒为 ISO YYYY-MM-DD 数组（不是 Date）；displayFormat 只改输入框展示，回传值不变。

disabledDate 入参是 ISO 字符串，自己拼 new Date(iso + "T00:00:00") 算 getDay 时注意时区，别直接 new Date(iso)（会按 UTC 解析偏一天）。

DateRangePicker

用法

基础用法

受控

无快捷预设

限定范围 + 禁用周末

禁用

何时用

导入

Props

Events

禁忌 / 坑

相关

Playground

DateRangePicker

用法

基础用法

受控

无快捷预设

限定范围 + 禁用周末

禁用

何时用

导入

Props

Events

禁忌 / 坑

相关

Playground