Toggle

切换按钮,支持三种视觉变体。包含 Toggle(单个切换)、ToggleGroup 与 ToggleGroupItem(分组切换)。

Anatomy

• Toggle独立的切换按钮,状态为按压 / 未按压
• ToggleGroup一组切换按钮的容器,支持单选或多选
  • ToggleGroupItem分组内的单个切换项,必须提供唯一 value

基本用法

受控 v-model

状态: false

<script setup lang="ts">
import { Toggle } from '@tripo3d/design';
import { ref } from 'vue';

const pressed = ref(false);
</script>

<template>
  <Toggle v-model="pressed" variant="button">
    {{ pressed ? '已选中' : '未选中' }}
  </Toggle>
</template>

变体

variant="button"

按钮样式

<Toggle variant="button">默认</Toggle>
<Toggle variant="button" :default-value="true">已选中</Toggle>
<Toggle variant="button" disabled>禁用</Toggle>

variant="navigation"

导航样式

<Toggle variant="navigation">默认</Toggle>
<Toggle variant="navigation" :default-value="true">已选中</Toggle>

variant="icon"

图标样式

<Toggle variant="icon">
  <Icon icon="i-tripo:line-visible" class="size-5" />
</Toggle>

ToggleGroup

单选

type='single'

仅允许选中一项,modelValue 为字符串。

<script setup lang="ts">
import { ToggleGroup, ToggleGroupItem } from '@tripo3d/design';
import { ref } from 'vue';

const value = ref('left');
</script>

<template>
  <ToggleGroup v-model="value" type="single" variant="button">
    <ToggleGroupItem value="left">左</ToggleGroupItem>
    <ToggleGroupItem value="center">中</ToggleGroupItem>
    <ToggleGroupItem value="right">右</ToggleGroupItem>
  </ToggleGroup>
</template>

多选

type='multiple'

允许选中多项,modelValue 为字符串数组。

<script setup lang="ts">
import { ref } from 'vue';

const value = ref<string[]>(['1']);
</script>

<template>
  <ToggleGroup v-model="value" type="multiple" variant="icon">
    <ToggleGroupItem value="1">...</ToggleGroupItem>
    <ToggleGroupItem value="2">...</ToggleGroupItem>
  </ToggleGroup>
</template>

API

Toggle Props

名称	类型	默认值	说明
variant	'button' | 'navigation' | 'icon'	—	视觉变体
modelValue	boolean	—	受控按压状态,可使用 v-model
defaultValue	boolean	—	非受控默认值
disabled	boolean	—	禁用
class	string	—	额外 class

Toggle Events

事件	Payload	说明
update:modelValue	(value: boolean)	按压状态变化

ToggleGroup Props

名称	类型	默认值	说明
type	'single' | 'multiple'	—	选择模式
variant	'button' | 'navigation' | 'icon'	—	视觉变体,作用于子项
modelValue	string | string[]	—	受控值,类型随 type 而定
class	string	—	额外 class

其余 props 透传至 reka-ui ToggleGroupRoot,详见 reka-ui 文档。

ToggleGroup Events

事件	Payload	说明
update:modelValue	(value: string | string[])	选中值变化

ToggleGroupItem Props

名称	类型	默认值	说明
value	string	—	必填。分组内的唯一标识
disabled	boolean	—	禁用该子项
class	string	—	额外 class

可访问性

• 基于 reka-ui,Toggle 渲染为 <button> 并设置 aria-pressed
• ToggleGroup 内部启用焦点漫游,支持方向键切换焦点、Space/Enter 选中
• 图标变体请在父容器或按钮上设置 aria-label 说明操作含义