033 ToggleGroup · 切换按钮组

用途

一排相连的切换按钮，单选（如对齐方式）或多选（如粗体、斜体、下划线）。可设置是否允许全部松开。

最小示例

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 在帧之间增删时焦点可能落到相邻项。