DatePicker 日期选择器
Forms
智能自动检测
简介
一个交互式表单控件，将文本输入框与弹出式日历叠加层相结合。它支持单日期选择器、日期范围选择、多选切换、自定义日历边界、本地化星期标题以及键盘导航。
DatePicker 已作为 datePicker 区块完整集成到 Page Builder 中，使内容管理者和开发者能够直接在 Sveltia CMS 页面模板内定义文本标签、占位符格式、选择模式以及强调配色主题。
用法
以下配置示例精确展示了页面构建器区块条目是如何被构建的。
1. 单日期选择器（非受控 / 标准）
我们标准的日期选择器布局，允许用户从日历下拉框中选择一个特定的日期。适用于表单、注册或预约排期。
{
"type": "datePicker",
"label": "Choose Date",
"selectionMode": "single",
"placeholder": "YYYY-MM-DD",
"colorPalette": "blue",
"interactive": true
}
2. 行程范围选择器（有界日历）
将可选日历限制在特定的日期之间。非常适合机票选择、酒店预订或财务结算窗口。将 selectionMode 设置为 "range" 会渲染起始和结束两个输入框。
{
"type": "datePicker",
"label": "Travel Dates",
"selectionMode": "range",
"min": "2026-01-01",
"max": "2026-12-31",
"colorPalette": "purple",
"interactive": true
}
属性
| 属性 | CMS 字段类型 | 默认值 | 说明 / 可选项 |
|---|---|---|---|
标签文本 (label) | string | - | 渲染在文本输入框相邻位置的表单描述性标签文本。 |
占位符 (placeholder) | string | "YYYY-MM-DD" | 当文本输入框为空时显示在其内部的引导格式文本。 |
选择模式 (selectionMode) | select | "single" | 定义日期的收集方式。 • "single" —— 解析单个日期。 • "range" —— 解析一个跨度的区块（创建双输入框）。 • "multiple" —— 切换多个独立的日期。 |
最小日期 (min) | string | - | 以 YYYY-MM-DD ISO 格式表示的最早可选日期。之前的单元格被禁用。 |
最大日期 (max) | string | - | 以 YYYY-MM-DD ISO 格式表示的最晚可选日期。 |
显示周数 (showWeekNumbers) | boolean | false | 为 true 时，在日期网格左边缘渲染一个 ISO-8601 周数列。 |
配色主题 (colorPalette) | select | "blue" | 应用于选中日、今日高亮和激活边界的视觉主题。 • 选项： blue、green、red、purple、orange、amber、cyan、slate。 |
启用水合 (interactive) | boolean | true | 为 true 时，将组件作为岛屿进行水合，以处理日历弹出层与外部点击。 |
键盘与无障碍支持
当日历面板叠加层打开且焦点定位到其内部时，用户可以通过标准键盘按键完整操作选择：
- ← / → —— 将焦点移动到上一天或下一天的单元格。
- ↑ / ↓ —— 垂直按 ±1 周（7 天）移动焦点。
- PageUp / PageDown —— 将日历视图前进或后退一个完整的月份。
- Shift+PageUp / Shift+PageDown —— 前进或后退一整年。
- Enter / Space —— 选中当前聚焦的日期单元格并提交。
- Esc —— 立即关闭弹出叠加层并将焦点返回到触发器输入框。
在底层，日期网格利用漫游 tabIndex 焦点停靠，以防止在每一个日历日期之间切换 Tab 焦点。所有单元格网格都会播报正确的语义化屏幕阅读器描述（role="grid"、aria-multiselectable、aria-current="date"）。