Toggle & Group 切换按钮与组

可在开与关两种状态之间切换的按钮。

基础用法

SToggle({ icon: 'bold', label: 'Toggle bold' })
SToggle({ variant: 'outline', icon: 'italic', label: 'Toggle italic' })
SToggle({ icon: 'underline', text: 'Underline', defaultPressed: true })
SToggle({ sizing: 'sm', icon: 'bold', label: 'Small' })
SToggle({ sizing: 'lg', icon: 'bold', label: 'Large' })
SToggle({ icon: 'bold', label: 'Disabled', disabled: true })

网页近似预览，真机效果以 HarmonyOS 渲染为准。

受控

像 v-model:pressed 一样用 !! 绑定 pressed。

@Local bold: boolean = true;

SToggle({ pressed: this.bold!!, variant: 'outline', icon: 'bold', text: 'Bold' })

网页近似预览，真机效果以 HarmonyOS 渲染为准。

切换按钮组

把一组双态按钮拼接成一个控件。无论单选还是多选，value 都是字符串数组。

SToggleGroup({ type: 'multiple', variant: 'outline' }) {
  SToggleGroupItem({ value: 'bold', icon: 'bold', label: 'Toggle bold' })
  SToggleGroupItem({ value: 'italic', icon: 'italic', label: 'Toggle italic' })
  SToggleGroupItem({ value: 'underline', icon: 'underline', label: 'Toggle underline' })
}
SToggleGroup({ type: 'single', sizing: 'sm' }) { ... }

网页近似预览，真机效果以 HarmonyOS 渲染为准。

切换按钮组——受控

@Local alignValue: string[] = ['left'];

SToggleGroup({ type: 'single', variant: 'outline', value: this.alignValue!! }) {
  SToggleGroupItem({ value: 'left', text: 'Left' })
  SToggleGroupItem({ value: 'center', text: 'Center' })
  SToggleGroupItem({ value: 'right', text: 'Right' })
}

网页近似预览，真机效果以 HarmonyOS 渲染为准。

API

从组件库源码中的 @Param / @Event / @BuilderParam 声明自动提取。

SToggle

shadcn-vue 的 Toggle：可开可关的两态按钮。

切换按钮自行处理点按；请通过 onPressedChange（或 !!）监听变化。在 SToggle 上使用原生 .onClick() 不会触发，因为内部的点按会优先。

属性	类型	默认值	说明
pressed!!	boolean | undefined	undefined	受控状态（配合 !! 使用）。留空则为非受控。
defaultPressed	boolean	false
variant	ToggleVariant ToggleVariant = 'default' | 'outline'	'default'
sizing	ToggleSize ToggleSize = 'default' | 'sm' | 'lg'	'default'
text	ResourceStr | undefined	undefined
icon	string | undefined	undefined	前导 lucide 图标名称。
label	string | undefined	undefined	无障碍名称；纯图标切换按钮必须设置。
disabled	boolean	false
tokens	ToggleTokens	{}	实例级令牌覆盖（实例 → 主题 --toggle-* → 配方），参见 {@link ToggleTokens}。

事件	类型	默认值	说明
onPressedChange	(pressed: boolean) => void	() => { }

插槽: 子组件（尾随闭包）

SToggleGroup

shadcn-vue 的 ToggleGroup：一组两态按钮，连接为一个控件。

value 始终为字符串数组（type: 'single' 时最多只包含一项；再次点击已选中的项会将其清除，与 Radix 一致）。在 single 模式下，选中状态是一个在各项之间滑动的指示器（动效 key 为 toggle-group），因此切换选中项时不会出现两个项同时闪烁或交叉淡化的情况。

属性	类型	默认值	说明
type	ToggleGroupType ToggleGroupType = 'single' | 'multiple'	'single'
value!!	string[] | undefined	undefined	受控的按下项（配合 !! 使用）。留空则为非受控。
defaultValue	string[]	[]
variant	ToggleVariant ToggleVariant = 'default' | 'outline'	'default'
sizing	ToggleSize ToggleSize = 'default' | 'sm' | 'lg'	'default'
disabled	boolean	false
spacing	number	0	项目之间的间距，单位 vp（对应 shadcn 的 spacing）。0 表示相连的分段。
wrap	boolean	false	放不下时将项目换行到多行（与 spacing 一起使用）。
deselectable	boolean	true	仅适用于 single：再次点击已选中的项会清除选中状态（Radix 默认值：true）。

事件	类型	默认值	说明
onValueChange	(value: string[]) => void	() => { }

插槽: 子组件（尾随闭包）

SToggleGroupItem

切换按钮组中的一项；继承该组的变体 / 尺寸。

属性	类型	默认值	说明
value	string	''
text	ResourceStr | undefined	undefined
icon	string | undefined	undefined	前导 lucide 图标名称。
label	string | undefined	undefined	无障碍名称；纯图标项必须设置。
disabled	boolean	false

插槽: 子组件（尾随闭包）