GPUI Deck

表单

原生设置示例是公开 API 的完整使用方。

原生设置示例是公开 API 的完整使用方。 请使用 README 中的命令,以任一外观运行它。它把 Button、Input、Select、 Textarea、Field、Label、Combobox、Calendar、DatePicker、Checkbox、Switch、RadioGroup、Slider、Progress、Toggle 和 ToggleGroup 与导航和浮层控件组合在一起, 而不把外观放进库中。导航与浮层指南 介绍了其标签页和键盘帮助弹出层。布局与数据指南 涵盖 Schedule 表格以及表单的 ScrollArea 组合。

只需调用一次 gpui_deck::init(cx),并把窗口内容托管在 gpui_deck::Root 中。 Root 提供 Tab 遍历,并在打开的 Dialog 内限定该遍历。请为每个控件提供稳定的元素 ID 和无障碍标签。

状态归属

控件状态所有者更新应用
Textarea保留的 Entity<TextareaState>观察它以更新周围的呈现;现有的 Input 事件会报告编辑
Field应用的标签、帮助文本、必填要求和校验错误在现有的 Input、Textarea 或 Combobox 查询周围渲染当前元数据;不引入新的输入状态
Label应用的文本、目标 FocusHandle 和禁用标志点击时聚焦现有控件;使其无障碍名称和禁用状态保持同步
Combobox保留的 Entity<ComboboxState>观察它以进行渲染;ComboboxEvent::Change 报告用户已提交的选中值
Calendar保留的 Entity<CalendarState>观察它以进行渲染;CalendarEvent::Change 报告变化后的单选/多选/范围选择
DatePicker保留的 Entity<DatePickerState>,组合现有的 Calendar/Popover 状态观察它以渲染选择和弹出层;单选和完整范围事件在弹出层关闭后触发,部分范围/多选事件则保持其打开
Checkbox类型为 CheckboxState 或 bool 的应用字段on_change 报告下一个状态;保存它并调用 cx.notify()
Toggle应用的 boolon_change 请求下一个按下值;用 pressed 把它渲染回来
ToggleGroup保留的 Entity<ToggleGroupState>观察它以进行渲染;ToggleGroupEvent::Change 按项顺序报告选中值
Switch应用的 boolon_change 报告下一个值;保存它并调用 cx.notify()
RadioGroup保留的 Entity<RadioGroupState>观察该实体以进行渲染;订阅 RadioGroupEvent::Change 以获取用户的选择变化
Select保留的 Entity<SelectState>观察该实体以进行渲染;订阅 SelectEvent::Change 以获取用户已提交的变化
Slider保留的 Entity<SliderState>观察它以进行渲染;SliderEvent::Change 报告变化后的有序值
Progress应用的百分比和不确定状态标志每次渲染时传入当前值和状态;没有交互回调

Checkbox 和 Switch 是受控的。渲染它们绝不会改变应用状态。 如果应用在回调之后保持所提供的值不变,控件会继续显示该值。 程序对字段的更改会在下一次渲染时生效,并且不会调用 on_change。

像原生示例那样,把保留的实体及其订阅放在视图中。 在每次渲染时重新创建 RadioGroupState 会丢弃其选中项和稳定的选项焦点句柄。

键盘与禁用行为

输入Checkbox / SwitchRadioGroup
Tab / Shift-Tab进入或离开已启用的控件进入已选中的已启用选项;未选中时进入第一个已启用选项;整个组只有一个 Tab 停靠点
Space / Enter通过原生激活路径请求下一个值选中当前聚焦的选项
Right / Down无选择导航选中并聚焦下一个已启用选项,到末尾时循环
Left / Up无选择导航选中并聚焦上一个已启用选项,到开头时循环
Escape向上传递给所在的容器界面向上传递给所在的容器界面

RadioGroup 的方向键选择是即时的。Select 在其弹出层打开时保留一个待定的键盘光标, 仅在激活时提交。两者都会跳过禁用的选项。空的或全部禁用的 RadioGroup 没有 Tab 停靠点。

禁用的控件会忽略激活,并在 Tab 遍历时被跳过。如果获得焦点的控件变为禁用, 它会保留其焦点绑定直到焦点离开,这样 Tab 和 Shift-Tab 仍能到达相邻的控件。

验证边界

现有的 GPUI 测试涵盖指针和原生按键事件的路由、选中/混合状态元数据、禁用行为、分组导航、 数值控件,以及跨两种外观的典型设置流程。无头的事件模拟无法验证操作系统的 IME、屏幕阅读器、混合 DPI 显示器,也无法验证原生窗口的实际渲染外观。 这些检查与自动化的行为测试是分开的。