由 GPUI 的 Web 后端渲染的真实组件。需要支持 WebGPU 的浏览器。
Toggle::new(id).pressed(bool) 是一个受控的切换按钮。它组合了
现有的 Button,复用原生的点击/Enter/Space 激活、禁用行为
和焦点。它新增的约定是按下的无障碍状态以及
on_change(next_pressed, event, window, cx)。应用存储该值,
通知其视图,并提供内容和按下状态的样式。稳定的标签
为操作命名,而按下元数据描述其当前状态。
Toggle 接受 accessibility_label、disabled、track_focus、tab_index
和 tab_stop,以及常规的 GPUI 样式和子元素。
对于可以同时按下的独立选项,请使用固定有序的
ToggleItem::new(value, label) 条目(值唯一)创建
ToggleGroupState::new(items, cx)。使用 .disabled(true) 标记不可用的条目,
并可选地设置 .default_values([values])。默认值
必须指向已启用的条目。未提供默认值时,选择初始为空。
使用 .single_selection() 实现可选的互斥选择。激活另一个选项
会替换之前的值;激活已按下的选项会清除选择。
单选的默认值最多只能包含一个不同的值,无论
.single_selection() 和 .default_values(...) 的先后顺序如何。
渲染 ToggleGroup::new(id, &state).accessibility_label(...),并为每个条目渲染一个
ToggleOption::new(&state, index)。每个选项都组合了 Toggle。
该组提供 Group 角色和方向;布局代码由应用
另行提供。读取 items()、is_pressed(index) 和 selected_values() 获得
当前的呈现。观察该实体,并订阅
ToggleGroupEvent::Change(values) 以获知所选集合的变化;值遵循
原始的条目顺序。
set_selected_values(values, window, cx) 会替换按下的集合,且不触发用户
事件、焦点变化或光标变化。重复的值会被去重;空的
迭代器会将其清空。未知/已禁用的值,或单选
模式下的多个不同的值,会返回 false 且不改变任何内容。该组被禁用时,
仍允许应用更新。会话示例通过这些保留状态的设置方法应用其初始的单选和
格式值。
该组有一个 Tab 停靠点,位于上一次获得焦点的已启用选项,或初始时的第一个 已启用选项。水平方向的左/右或垂直方向的上/下在 已启用的选项之间移动并循环。Home/End 到达第一个/最后一个已启用的选项。另一个 轴则向上传播。移动焦点绝不会改变所选的集合;点击、Enter 和 Space 会根据选择模式切换获得焦点的选项。Tab 离开该组。
set_disabled(disabled, window, cx) 禁用整个组,同时保留
选择。option_focus_handle(index) 暴露稳定的选项焦点。RadioGroup
提供互斥选择,并在方向键导航期间立即选中;
ToggleGroup 在两种模式下都使焦点移动与选择保持独立。
会话示例使用独立的粗体/斜体摘要文本样式,而
目录使用单选实现可选的文档对齐方式 Center/End。