由 GPUI 的 Web 后端渲染的真实组件。需要支持 WebGPU 的浏览器。
目录中的录制日期范围日历支持直接选择月份和年份。调用 display_month(date, window, cx)
可以跳转到指定月份,保留所选日期,并按该月天数与日历边界调整光标日期。
日期单元格的焦点随光标移动,通过外部月份选择器跳转时焦点则留在选择器上。
CalendarState 保留一个 CalendarSelection、获得焦点的日期,以及
可见的月份。Date 重新导出自 jiff 的民用日期(jiff::civil::Date);不引入第二套日期模型或
时区转换。只需创建一次状态:
let calendar = cx.new(|cx| {
let initial = Date::new(2026, 11, 9).unwrap();
CalendarState::new(initial, cx)
.bounds(
Date::new(2026, 1, 1).unwrap(),
Date::new(2027, 12, 31).unwrap(),
)
.default_selection(CalendarSelection::Single(Some(initial)))
});不设置 default_selection 时,选择状态初始为 CalendarSelection::Single(None)。默认边界涵盖
1–9998 年(9998 年 12 月的六周网格仍在 jiff 的范围内);bounds 会在挂载前收窄包含两端的可选范围。
网格通过 days() 提供六个完整的周,默认以周一开头。相邻月份的
日期仍然可见;超出所配置边界的日期会被禁用。
在挂载前,.week_starts_on(Weekday::Sunday) 会改变网格以及 Home/End
的边界。使用 weekdays() 获得与之匹配的表头顺序;Weekday 与
Date 一同重新导出。.disabled_dates(|date| ...) 提供应用规则,
例如周末或已预订的日期。它会过滤已有的单选/多选值,并
清除端点不可用的范围。默认值和程序化设置方法会拒绝
不可用的日期/端点;范围内部可以包含不可用的日期。
请在状态的整个生命周期内保持该谓词的结果稳定。
渲染 Calendar::new(id, &calendar),并提供无障碍的月/年标签。使用
带标识的普通 div().id(...).role(Role::Row) 容器,分别用于一个包含七个单元格的星期表头
和六个日期行。星期标题使用 Role::ColumnHeader,并带有从零开始的
列索引。每个 CalendarDay::new(&calendar, date) 组合了 Button 的
激活/焦点行为,并提供其原生的 GridCell 角色、选中状态、
禁用状态以及行/列索引。网格声明共七行,包括
星期表头。请将 days() 返回的每个日期按顺序渲染且仅渲染一次。
请保持每一天的子元素为非交互式。
应用负责网格几何、星期名称、本地化的完整日期标签、
选中日期的样式以及月份导航按钮。CalendarDay 默认使用
ISO 日期作为无障碍标签,支持 .accessibility_label(...),并接受
普通的 GPUI 样式,以及用于选中/禁用状态的 Button .styles(...)。
完整的组合方式请参阅原生示例中的 Demo::calendar_content。
| 输入 | 结果 |
|---|---|
| Tab / Shift+Tab | 进入唯一保留的日期停靠点,或离开网格 |
| 左 / 右 | 按物理单元格移动一格焦点,在 RTL 中会反转时间顺序方向 |
| 上 / 下 | 按一周移动焦点 |
| Home / End | 移到当前周中所配置的第一天 / 最后一天 |
| Page Up / Page Down | 按一个月移动,并对月末日期进行截断 |
| Shift+Page Up / Shift+Page Down | 按一年移动 |
| Enter / Space / 点击 | 提交已启用的日期;仅当值发生变化时才触发 Change |
键盘移动会跨月,并在可选边界处截断,且
不会改变已提交的值。新获得焦点的日期会请求原生的显示到可见区域,
外层的 ScrollArea 可以满足该请求。月份按钮调用 previous_month 或
next_month,并使用 can_previous_month/can_next_month 决定禁用状态。
这些方法会保留外部导航按钮的焦点。需要显式将焦点移入日历时,
请读取 focus_handle();其网格槽位会随可见月份的变化而改变,
因此不要将该句柄缓存为某个日期的永久标识。
边界内的不可用日期仍可通过键盘获得焦点以便发现, 但无法通过指针、Enter 或 Space 激活。即使整个日历都不可用, 它仍保留一个网格 Tab 停靠点;禁用整个 Calendar 则会移除正常的 进入和导航。边界之外的单元格不参与焦点遍历。
Calendar 继承 DirectionProvider,或接受 .direction(Direction::Rtl)。
应用必须对星期/日期行应用相同的 Direction::row,并
镜像星期表头的列索引。CalendarDay 会根据其外层 Calendar 推导物理列
和水平键盘方向。标签和文本
格式仍由应用负责;Selection 目录展示了这种布局。
CalendarSelection 还支持 Multiple(Vec<Date>) 和
Range { start: Option<Date>, end: Option<Date> }。使用
.default_selection(CalendarSelection::Range { start: None, end: None }) 配置空
范围。第一次激活选择其起点;第二次激活完成包含两端的有序
端点,包括反向或同一天的选择。激活已完成的范围会
开始一个新的部分范围。多选会切换日期,并以升序存储且
不重复。is_selected(date) 涵盖范围内的每个已选日期。
selection() 返回完整的值,selection().first_date() 可用于
摘要。set_selection(selection, window, cx) 会在不触发用户事件的情况下更改模式/值;
它会拒绝超出边界的日期、反向的范围,以及有终点而无
起点的情况。非空的值还会更新可见月份和光标;清除
选择则保留当前导航位置。CalendarEvent::Change(selection) 报告用户
所做的更改。set_disabled 会阻止用户导航/选择以及正常的 Tab 进入。
该日历始终为公历。不提供非公历的运算、时钟和时区 转换。Selection 目录演示了以周日开头、 禁用周末的范围/多选日期以及 RTL;会话示例则保留其以周一开头的 单选录制日期。