64 lines
2.3 KiB
Markdown
64 lines
2.3 KiB
Markdown
# 033 ToggleGroup · 切换按钮组
|
||
|
||
## 用途
|
||
|
||
一排相连的切换按钮，单选（如对齐方式）或多选（如粗体、斜体、下划线）。可设置是否允许全部松开。
|
||
|
||
## 最小示例
|
||
|
||
```go
|
||
align := []string{"left"}
|
||
items := []input.ToggleItem[string]{
|
||
{Value: "left", Label: "Left"},
|
||
{Value: "center", Label: "Center"},
|
||
{Value: "right", Label: "Right"},
|
||
}
|
||
view := func(c *ui.Context) {
|
||
core.Use(c, core.Settings{})
|
||
input.ToggleGroup(c, &align, items, input.ToggleGroupOptions{Label: "Align"})
|
||
}
|
||
ui.Render(view, 400, 300, 1)
|
||
```
|
||
|
||
## 参数
|
||
|
||
`func ToggleGroup[T comparable](c *ui.Context, value *[]T, items []ToggleItem[T], opts ToggleGroupOptions) ChoiceResult`。单选模式下 `*value` 最多一个元素，否则 panic。
|
||
|
||
`ToggleItem[T]`：
|
||
|
||
| 字段 | 类型 | 默认值 | 含义 |
|
||
| --- | --- | --- | --- |
|
||
| `Value` | `T` | — | 稳定的选项值。 |
|
||
| `Label` | `string` | "" | 文字。 |
|
||
| `Icon` | `*ui.SVG` | nil | 图标。 |
|
||
| `Name` | `string` | "" | 仅图标时的无障碍名称。 |
|
||
| `Disabled` | `bool` | false | 单项禁用，键盘导航跳过它。 |
|
||
|
||
`ToggleGroupOptions`：
|
||
|
||
| 字段 | 类型 | 默认值 | 含义 |
|
||
| --- | --- | --- | --- |
|
||
| `Multiple` | `bool` | false | 允许同时按下多项。 |
|
||
| `AllowEmpty` | `bool` | false | 允许松开最后一个已按下项。 |
|
||
| `Vertical` | `bool` | false | 纵向排列，↑/↓ 导航。 |
|
||
| `Disabled` | `bool` | false | 禁用整组。 |
|
||
| `Label` | `string` | "" | 组的无障碍名称。 |
|
||
|
||
## 状态
|
||
|
||
未按下、按下（玫瑰底 + 酒红文字 + 底部横条）、悬停、按住、聚焦、单项禁用、整组禁用。
|
||
|
||
## 事件
|
||
|
||
返回的 `ChoiceResult.Changed()` 在值变化的那一帧返回 true。不允许空选时点击唯一按下项不产生事件。
|
||
|
||
## 键盘操作
|
||
|
||
- Tab：进入组。首次落在第一个可用项（与哪项按下无关）；之后回到组内上次聚焦的项。再按 Tab 离开。
|
||
- ←/→（纵向为 ↑/↓）、Home、End：在项之间移动焦点，跳过禁用项，首尾循环。
|
||
- Space：按下或松开当前项。
|
||
|
||
## 限制
|
||
|
||
- 每项基于 `ui.ToggleBase`，组用 MyGo `FocusGroup` 实现方向键导航；MyGo 的 `Key` 不能用于自带输入处理的控件（ui/element.go:474），所以项以位置区分，`items` 在帧之间增删时焦点可能落到相邻项。
|