SepDatePicker 日期选择器组件测试

1. 基础使用（占位符 / 初始值 / 不同格式）

HTML 声明式标签

JS API 初始化

2. format（面板格式）与 valueFormat（返回格式）

说明：format 控制面板和输入框显示格式，valueFormat 控制 getValue() 返回格式

HTML 声明式标签

JS API 初始化（valueFormat 分离）

getValue() 返回：—

3. disabledDate / minDate / maxDate 日期约束

HTML 声明式标签

JS API 初始化（disabledDate 函数）

禁用所有周六周日 + 2025-01-01

4. allowClear 清除 / "今天" 按钮 / onChange 回调

HTML 声明式标签

JS API 初始化（onChange 回调）

onChange 返回值：—

5. JS API 动态操作（setValue / getValue / open / close / clear / subscribe）

JS API 初始化

当前 getValue()：—

subscribe 变更日志：—

6. placement 上下智能翻转

说明：面板默认在输入框下方，当下方空间不足时自动翻转到上方

HTML 声明式标签

JS API 初始化

7. getContainer 指定渲染容器

JS API 初始化

点击下方输入框，日期面板将渲染到蓝色虚线容器内（而非 document.body）

📦 自定义容器（getContainer）

8. 尺寸（size）与无边框（bordered）

HTML 声明式标签

9. 校验状态（status）/ 只读（readonly）/ 可编辑（editable）

HTML 声明式标签

JS API 初始化

10. 自定义类名（className / style）

JS API 初始化

11. picker 选择器类型（date / month / year）

说明：picker 锁定可选择的粒度。date=完整日期，month=只能选年月，year=只能选年

HTML 声明式标签

JS API 初始化

month 模式 getValue()：—

12. showTime 日期时间选择

说明：showTime 开启后面板底部内嵌 SepTimePicker，可同时选择日期与时间

HTML 声明式标签

JS API 初始化

getValue()：—

13. onPanelChange 面板视图切换回调

说明：切换视图（date→month→year）或翻页时触发 onPanelChange(date, mode)

JS API 初始化

14. renderExtraFooter 底部插槽

说明：支持 string / function / DOM 节点，渲染在面板底部（今天按钮下方）

JS API 初始化

字符串函数返回 DOM

15. hourStep / minuteStep / secondStep 时间步长

说明：控制时间选择器中时/分/秒的步长，如 minuteStep=15 则分钟选项为 00/15/30/45

HTML 声明式标签

JS API 初始化

16. use12Hours 12 小时制

说明：开启后时间面板显示 AM/PM 切换，格式示例 hh:mm:ss A

JS API 初始化

17. disabledTime 禁用特定时间

说明：disabledTime(date) 返回 { disabledHours, disabledMinutes, disabledSeconds }，动态禁用特定时分秒

JS API 初始化

18. defaultOpenValue 打开面板默认时间

说明：无值时打开 showTime 面板，时间默认为 defaultOpenValue 指定值

JS API 初始化

19. showHour / showMinute / showSecond 显示指定列

说明：控制时间面板显示哪些列，如只显示小时和分钟 showSecond=false

JS API 初始化

20. selectableRange 可选时间范围

说明：限制可选时间在指定范围内，如 "09:00:00 - 18:00:00"

JS API 初始化

21. minTime / maxTime 时间边界

说明：全局限制可选时间范围，与 selectableRange 不同，minTime/maxTime 对所有日期生效

JS API 初始化

22. hideDisabledOptions 隐藏禁用选项

说明：配合 disabledTime 使用，不显示被禁用的时分秒选项

JS API 初始化

22b. presets 快捷预设

说明：面板底部显示快捷按钮，一键选择常用日期。支持内置字符串预设（today/yesterday/last7days/last30days/thisMonth/lastMonth/thisQuarter/thisYear）或自定义对象

JS API 初始化

22b-1. picker: 'dates' 多选日期

说明：picker: 'dates' 模式下可选择多个不连续日期，点击已选日期可取消，面板不自动关闭，底部有「确定」按钮确认后关闭面板

JS API 初始化

getValue()：—

22c. Week 周选择器

说明：picker: 'week' 模式下可选择整周，左侧显示 ISO 周号，输出格式为 YYYY-Www

JS API 初始化

22d. Quarter 季度选择器

说明：picker: 'quarter' 模式按季度选择，点击标题切换年份，格式 YYYY-Q1 ~ YYYY-Q4

JS API 初始化

22e. dateRender 自定义单元格渲染

说明：通过 dateRender 函数完全自定义日期单元格内容，返回 null 则走默认渲染。适合需要完全控制单元格展示的场景

JS API 初始化

22b. DatePicker `dateMark` 角标标注

说明：通过 dateMark 函数在日期数字下方显示小角标，日期数字依然可见。返回字符串作为角标内容，同时自动作为 tooltip 提示。适合动态逻辑标记（如生日、待办等）

JS API 初始化

22g. 农历 · 节假日 · 休班角标 · 历史纪念日 · 富信息 Tooltip

说明：开启 showLunar / showHoliday / showSolarTerm / showAnniversary 后，单元格显示农历、节气、节假日、历史纪念日；法定节假日自动标注「休/班」角标；纪念日右上角标注紫色「纪」角标 + 底部紫色标记；鼠标悬停显示富信息 tooltip（公历+农历+节气+节日+纪念日）

JS API 初始化

22h. disableFuture / disablePast 快捷禁用

说明：disableFuture 禁用未来日期，disablePast 禁用过去日期，比手写 disabledDate 更便捷

HTML 声明式标签

22i. disabledMonth / disabledYear 月/年视图禁用

说明：disabledMonth(date) 禁用月视图中特定月份，disabledYear(date) 禁用年视图中特定年份；参数为该月/年的第一天 Date 对象

JS API 初始化

禁用 1/7/12 月

禁用奇数年份

22j. firstDayOfWeek 周起始日

说明：firstDayOfWeek 设置每周起始日，0=周日（默认），1=周一，表头顺序与日历网格同步调整

HTML 声明式标签

22k. showDaysOutsideCurrentMonth 非当月日期

说明：showDaysOutsideCurrentMonth=false 时非当月日期仍显示但不可点击（禁用态），避免误选

HTML 声明式标签

22l. showNow "此刻"按钮

说明：showTime 模式下开启 showNow，面板底部显示"此刻"按钮，一键将时间设为当前时分秒（日期不变）

JS API 初始化

22m. 自定义导航图标（prevIcon / nextIcon / superPrevIcon / superNextIcon）

说明：通过 prevIcon / nextIcon / superPrevIcon / superNextIcon 自定义上/下月、上/下年按钮的图标内容，支持任意 HTML

JS API 初始化

使用文字箭头 ◀ ▶ ◀◀ ▶▶

23. DateRangePicker 日期范围选择器 — 基础使用

HTML 声明式标签

JS API 初始化

getValue()：—

24. ** DateRangePicker — 日期约束与预设 — minDate / maxDate / disabledDate / presets 预设 / maxSpan 跨度限制

HTML 声明式标签

JS API 初始化（disabledDate + presets 预设 + maxSpan 跨度限制）

禁用周末

预设：最近7天 / 最近30天 / 本月

maxSpan 最大跨度 7 天

25. needConfirm 确认模式 / closeOnSelect 选择即关闭

说明：needConfirm=true 选择范围后需点击「确定」才提交；closeOnSelect=false 选择后不关闭面板

JS API 初始化

needConfirm=true（需点确定）

closeOnSelect=false

26. firstDayOfWeek 周起始日

说明：firstDayOfWeek 设置每周起始日，0=周日（默认），1=周一

HTML 声明式标签

27. allowNonAdjacent 非相邻模式 / 年月视图切换

说明：allowNonAdjacent=true 时左右面板独立翻页（左只能向前、右只能向后），可选择不相邻月份；点击月份标题可进入月/年视图快速跳转

JS API 初始化

allowNonAdjacent=true（左右独立翻页）

28. JS API 动态操作（setValue / getStartDate / getEndDate / setRange / open / close / clear）

JS API 初始化

当前值：—

subscribe 变更日志：—

29. 尺寸（size）/ 无边框（bordered）/ 校验状态（status）

HTML 声明式标签

30. 只读（readonly）/ 清除按钮（allowClear）

HTML 声明式标签

31. showTime 日期时间范围选择

说明：showTime: true 开启后，面板底部内嵌两个时间选择器，可分别设置开始/结束时间，格式自动切换为 YYYY-MM-DD HH:mm:ss

HTML 声明式标签

JS API 初始化

showTime: true

showTime + needConfirm

getValue()：—

32. picker 月份/年份范围选择

说明：picker: 'month' | 'year' 切换范围选择模式，自动设置对应格式和视图

HTML 声明式标签

JS API 初始化

picker: 'month'

picker: 'year'

33. disabledTime 禁用特定时间

说明：disabledTime(date, type) 按开始/结束时间独立禁用特定时分秒，type 为 'start' 或 'end'，日期变化时自动重新评估

JS API 初始化（开始/结束均仅允许工作时间 9:00–18:00，其余小时禁用）

33b. 农历 · 节假日 · 休班角标 · 历史纪念日 · 富信息 Tooltip

说明：开启 showLunar / showHoliday / showSolarTerm / showAnniversary 后，双月历单元格显示农历、节气、节假日、历史纪念日；法定节假日自动标注「休/班」角标；纪念日标注紫色「纪」角标；鼠标悬停显示富信息 tooltip

JS API 初始化

34. 增强功能（monthrange / quarterrange / defaultTime / unlinkPanels / openTo / fixedWeekNumber / loading / panelRender / disableFuture / disablePast）

DatePicker — 多选日期 / disableFuture / fixedWeekNumber / openTo / loading

disableFuture=true（禁用未来日期）

fixedWeekNumber=false（动态行数）

openTo='month'（默认月视图）

DateRangePicker — monthrange / quarterrange / defaultTime / unlinkPanels

picker='monthrange'

picker='quarterrange'

defaultTime=['09:00:00','18:00:00']

unlinkPanels=true

测试断言

详细说明

组件定位

SepDatePicker 是一个企业级日期选择器，支持年/月/日日历选择、年/十年快速切换视图、日期边界约束、禁用日期函数，在交互和可访问性上做了增强。

日期格式

format 控制输入框显示和日历面板格式：YYYY / MM / DD 可自由组合
valueFormat 控制 getValue() 返回格式，默认与 format 一致
支持 YYYY、YY、MM、M、DD、D 等 token

日期约束

minDate 最小可选日期（字符串或时间戳）
maxDate 最大可选日期（字符串或时间戳）
disabledDate(date) 自定义禁用函数，返回 true 则禁用
禁用项显示 cursor: not-allowed，鼠标无法触发选中

视图模式

日期视图：7×6 网格展示当月日期，包含上月/下月填充日期
月视图：点击年份标签进入，12 个月快速选择
年视图：再点击进入十年视图，快速切换年份
左右箭头可在当前视图下翻页

placement 定位

支持 topLeft / top / bottomLeft / bottom 四种锚点
桌面端自动智能翻转：下方空间不够 → 翻到上方

受控与非受控

传入 value → 受控模式，外部驱动值
onChange(valueStr, dateObj) 值变化回调
onClear() 清除回调

picker 视图锁定

picker: 'date'（默认）— 标准日期视图
picker: 'month' — 固定月选择器
picker: 'year' — 固定年选择器
锁定后不可切换到更细粒度视图

showTime 日期时间选择

showTime: true — 在日期面板底部集成时间选择器
支持所有 TimePicker 配置透传（步长、禁用时间、12小时制等）
底部增加「确定」按钮，点击后统一提交日期+时间
选日期后不关闭面板，等用户确认时间

时间配置透传

hourStep / minuteStep / secondStep — 时间步长
use12Hours — 12 小时制（AM/PM）
showHour / showMinute / showSecond — 显示/隐藏时间列
disabledTime(date) → { disabledHours, disabledMinutes, disabledSeconds }
hideDisabledOptions — 隐藏禁用的时分秒选项

时间约束与边界

selectableRange: "09:00 - 18:00" — 可选时间范围
minTime / maxTime — 全局时间边界
defaultOpenValue: "12:00:00" — 打开面板默认时间
disabledTime(date) — 可按日期动态禁用

农历 / 节气

showLunar: true — 单元格显示农历日期（初一/十五等）
showSolarTerm: true — 单元格显示二十四节气
农历转换结果带内存缓存，避免重复计算

节假日 / 休班角标

showHoliday: true — 显示法定节假日名称
自动从 timor.tech 拉取节假日数据，localStorage 缓存
法定节假日右上角标注红色「休」角标
调休工作日标注蓝色「班」角标
按年份存储数据，避免跨年 MM-DD 冲突

富信息 Tooltip

鼠标悬停单元格显示富信息 tooltip
包含：公历日期+星期、农历干支、节气、节假日（休/班）、历史纪念日
被截断的说明文字也通过 tooltip 显示完整内容
tooltip 浮动在单元格上方，不遮挡当前日期
自动适配亮/暗主题皮肤变量

自定义标记

dateMark(date, today) — 返回字符串显示在日期数字下方小角标，同时作为 tooltip 内容
dateRender(date, today) — 完全自定义单元格 HTML，返回 null 走默认渲染
适合生日、待办、日程等动态逻辑标记
dateMark 不影响日期数字显示，dateRender 完全接管单元格

历史纪念日

showAnniversary: true — 显示历史纪念日标记
anniversaryData — 自定义纪念日数据集 { "MM-DD": [{name, year?, type?}] }
anniversaryUrl — 远程加载纪念日 JSON，自动 localStorage 缓存（30天）
纪念日右上角紫色「纪」角标 + 底部紫色细线标记
鼠标悬停显示完整纪念日名称
内置 100+ 条历史纪念日/节日数据，可与自定义数据合并

响应式与主题

输入框 max-width: 100%，移动端不溢出窗口
面板宽度自适应，最小 280px
tooltip 自动适配 [data-theme] 亮/暗主题
角标、休/班标记、纪念日标记均适配主题色

SepDatePicker、SepDateRangePicker 日期选择器组件 v1.0.0

1. 基础使用（占位符 / 初始值 / 不同格式）📋 示例代码

2. format（面板格式）与 valueFormat（返回格式）📋 示例代码

3. disabledDate / minDate / maxDate 日期约束📋 示例代码

4. allowClear 清除 / "今天" 按钮 / onChange 回调📋 示例代码

5. JS API 动态操作（setValue / getValue / open / close / clear / subscribe）📋 示例代码

6. placement 上下智能翻转📋 示例代码

7. getContainer 指定渲染容器📋 示例代码

8. 尺寸（size）与无边框（bordered）📋 示例代码

9. 校验状态（status）/ 只读（readonly）/ 可编辑（editable）📋 示例代码

10. 自定义类名（className / style）📋 示例代码

11. picker 选择器类型（date / month / year）📋 示例代码

12. showTime 日期时间选择📋 示例代码

13. onPanelChange 面板视图切换回调📋 示例代码

14. renderExtraFooter 底部插槽📋 示例代码

15. hourStep / minuteStep / secondStep 时间步长📋 示例代码

16. use12Hours 12 小时制📋 示例代码

17. disabledTime 禁用特定时间📋 示例代码

18. defaultOpenValue 打开面板默认时间📋 示例代码

19. showHour / showMinute / showSecond 显示指定列📋 示例代码

20. selectableRange 可选时间范围📋 示例代码

21. minTime / maxTime 时间边界📋 示例代码

22. hideDisabledOptions 隐藏禁用选项📋 示例代码

22b. presets 快捷预设📋 示例代码

22b-1. picker: 'dates' 多选日期📋 示例代码

22c. Week 周选择器📋 示例代码

22d. Quarter 季度选择器📋 示例代码

22e. dateRender 自定义单元格渲染📋 示例代码

22b. DatePicker dateMark 角标标注 📋 示例代码

22g. 农历 · 节假日 · 休班角标 · 历史纪念日 · 富信息 Tooltip 📋 示例代码

22h. disableFuture / disablePast 快捷禁用 📋 示例代码

22i. disabledMonth / disabledYear 月/年视图禁用 📋 示例代码

22j. firstDayOfWeek 周起始日 📋 示例代码

22k. showDaysOutsideCurrentMonth 非当月日期 📋 示例代码

22l. showNow "此刻"按钮 📋 示例代码

22m. 自定义导航图标（prevIcon / nextIcon / superPrevIcon / superNextIcon）📋 示例代码

23. DateRangePicker 日期范围选择器 — 基础使用📋 示例代码

24. ** DateRangePicker — 日期约束与预设 — minDate / maxDate / disabledDate / presets 预设 / maxSpan 跨度限制📋 示例代码

25. needConfirm 确认模式 / closeOnSelect 选择即关闭📋 示例代码

26. firstDayOfWeek 周起始日📋 示例代码

27. allowNonAdjacent 非相邻模式 / 年月视图切换📋 示例代码

28. JS API 动态操作（setValue / getStartDate / getEndDate / setRange / open / close / clear）📋 示例代码

29. 尺寸（size）/ 无边框（bordered）/ 校验状态（status）📋 示例代码

30. 只读（readonly）/ 清除按钮（allowClear）📋 示例代码

31. showTime 日期时间范围选择📋 示例代码

32. picker 月份/年份范围选择📋 示例代码

33. disabledTime 禁用特定时间📋 示例代码

33b. 农历 · 节假日 · 休班角标 · 历史纪念日 · 富信息 Tooltip 📋 示例代码

34. 增强功能（monthrange / quarterrange / defaultTime / unlinkPanels / openTo / fixedWeekNumber / loading / panelRender / disableFuture / disablePast）📋 示例代码

测试断言

详细说明

组件定位

日期格式

日期约束

视图模式

placement 定位

受控与非受控

picker 视图锁定

showTime 日期时间选择

时间配置透传

时间约束与边界

农历 / 节气

节假日 / 休班角标

富信息 Tooltip

自定义标记

历史纪念日

响应式与主题

1. 基础使用（占位符 / 初始值 / 不同格式）

2. format（面板格式）与 valueFormat（返回格式）

3. disabledDate / minDate / maxDate 日期约束

4. allowClear 清除 / "今天" 按钮 / onChange 回调

5. JS API 动态操作（setValue / getValue / open / close / clear / subscribe）

6. placement 上下智能翻转

7. getContainer 指定渲染容器

8. 尺寸（size）与无边框（bordered）

9. 校验状态（status）/ 只读（readonly）/ 可编辑（editable）

10. 自定义类名（className / style）

11. picker 选择器类型（date / month / year）

12. showTime 日期时间选择

13. onPanelChange 面板视图切换回调

14. renderExtraFooter 底部插槽

15. hourStep / minuteStep / secondStep 时间步长

16. use12Hours 12 小时制

17. disabledTime 禁用特定时间

18. defaultOpenValue 打开面板默认时间

19. showHour / showMinute / showSecond 显示指定列

20. selectableRange 可选时间范围

21. minTime / maxTime 时间边界

22. hideDisabledOptions 隐藏禁用选项

22b. presets 快捷预设

22b-1. picker: 'dates' 多选日期

22c. Week 周选择器

22d. Quarter 季度选择器

22e. dateRender 自定义单元格渲染

22b. DatePicker `dateMark` 角标标注

22g. 农历 · 节假日 · 休班角标 · 历史纪念日 · 富信息 Tooltip

22h. disableFuture / disablePast 快捷禁用

22i. disabledMonth / disabledYear 月/年视图禁用

22j. firstDayOfWeek 周起始日

22k. showDaysOutsideCurrentMonth 非当月日期

22l. showNow "此刻"按钮

22m. 自定义导航图标（prevIcon / nextIcon / superPrevIcon / superNextIcon）

23. DateRangePicker 日期范围选择器 — 基础使用

24. ** DateRangePicker — 日期约束与预设 — minDate / maxDate / disabledDate / presets 预设 / maxSpan 跨度限制

25. needConfirm 确认模式 / closeOnSelect 选择即关闭

26. firstDayOfWeek 周起始日

27. allowNonAdjacent 非相邻模式 / 年月视图切换

28. JS API 动态操作（setValue / getStartDate / getEndDate / setRange / open / close / clear）

29. 尺寸（size）/ 无边框（bordered）/ 校验状态（status）

30. 只读（readonly）/ 清除按钮（allowClear）

31. showTime 日期时间范围选择

32. picker 月份/年份范围选择

33. disabledTime 禁用特定时间

33b. 农历 · 节假日 · 休班角标 · 历史纪念日 · 富信息 Tooltip

34. 增强功能（monthrange / quarterrange / defaultTime / unlinkPanels / openTo / fixedWeekNumber / loading / panelRender / disableFuture / disablePast）