GPUI Deck

Calendar

单选/多选/范围日期选择、独立的焦点、日期禁用规则、可配置的每周起始日、有界导航和 RTL。

由 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;会话示例则保留其以周一开头的 单选录制日期。