DirectSurface UIDirectSurface UI
开始使用
文档/组件手册

DateRangeEdit

通用布局能力：DateRangeEditOptions 继承 RenderBoxOptions，可在构造时配置 width、height、min/max、margin 和槽位对齐，也可在创建后通过对应属性调整。详见组件通用布局属性。

RenderDateRangeEdit 用一个日期弹层完成起点和终点选择。它适合查询条件、统计周期、排班区间等需要表达连续日期范围的场景，不需要在业务页面手工同步两个 DatePicker。

首版只处理日历日期，不包含时间和时区。

基本使用

import { RenderDateRangeEdit } from 'ds-ui' const range = new RenderDateRangeEdit({  value: {    start: '2026-07-01',    end: '2026-07-31',  },  clearable: true,  onChange: value => {    console.log(value.start, value.end)  },})

值模型

interface DateRangeValue {  start: string | null  end: string | null}
  • 日期使用 YYYY-MM-DD。
  • 支持的日历范围为 0001-01-01 到 9999-12-31。
  • { start:null, end:null } 表示空值。
  • 选择起点后、终点尚未选择时，允许 { start:'2026-07-01', end:null }。
  • 外部值如果 start > end，组件会自动交换两端。
  • 起点无效时，终点也会被清空。

选择行为

  1. 没有完整范围时，第一次点击选择起点。
  2. 第二次点击选择终点并形成区间。
  3. 如果第二次点击的日期早于起点，该日期会成为新的起点，组件继续等待终点。
  4. 已有完整范围时再次选择，会从新的起点重新开始。
  5. 等待终点时，鼠标移动或键盘移动都会预览即将形成的区间；预览跨月时，弹层会跟随键盘日期切换月份。

弹层提供上月、下月、今天、确定和取消。确定可以提交完整范围或只有起点的部分范围；取消保持打开弹层前的值。

在 0001-01 和 9999-12，日历中越过支持范围的相邻月单元格不显示日期，也不能点击或参与范围预览。上月、下月、方向键和 PageUp / PageDown 会停在对应边界，不会生成 year 0 或 year 10000。

构造参数

参数 类型 默认值 说明
value DateRangeValue 空范围 当前受控值。
placeholder string '选择日期范围' 空值提示。
separator string ' ~ ' 起止日期之间的显示文本。
onChange (value: DateRangeValue) => void undefined 确认或清空时调用。
disabled boolean false 禁用焦点、弹层和清除。
readonly boolean false 只读显示，不允许打开弹层。
status FormFieldStatus 'default' 成功、警告和错误状态。
helperText string '' 字段下方提示。
prefixText string '' 输入区前缀。
suffixText string '' 输入区后缀。
clearable boolean false 有值时显示清除入口。

键盘行为

字段获得焦点后：

按键 行为
Enter / Space / Down 打开或关闭日期范围弹层。
Escape 关闭弹层。

弹层打开后：

按键 行为
Left / Right 前后移动一天；等待终点时同步预览起点到键盘日期的范围。
Up / Down 前后移动一周；等待终点时同步更新范围预览。
PageUp / PageDown 前后移动一个月，并同步更新键盘日期和范围预览。
Enter 选择当前键盘日期。
Tab 关闭弹层并继续外层焦点导航。
Escape 取消并关闭弹层。

鼠标位于某个日期上时，范围预览以鼠标日期为准；鼠标离开日期单元格后，继续显示键盘日期对应的预览。预览本身不会修改选择草稿或 value；Enter 把当前键盘日期写入选择草稿，点击“确定”后才提交 value。

字段清除按钮同样在指针抬起时提交：只有手势仲裁成功且抬起仍命中按钮才清空范围；父级滚动、reject、cancel 或 leave 都会取消本次清除。

方法和状态

API 说明
value 读取或替换受控日期范围。
disabled / readonly 动态改变交互状态。
status / helperText 动态设置字段状态。
debugState() 返回当前值、焦点和弹层诊断状态。

DateRangePickerPopup 也公开导出，供 DataGrid 之外的特殊宿主复用。普通表单页面应优先使用 RenderDateRangeEdit。

当前边界

  • 不包含时间范围；日期时间区间由业务组合或后续专用组件承担。
  • 不内置快捷范围，例如“最近 7 天”或“本月”；业务可以在字段旁提供命令按钮并更新 value。
  • 不接管查询提交，组件只返回日历日期范围。
  • 当前不作为 DataGrid 默认列类型。范围通常是查询条件，而不是单个业务单元格。

相关组件