表单

Toggle Group 切换控件组

用于切换控件组场景的 MoriUI 组件。

资源

导入

import { ToggleGroup, ToggleGroupItem } from 'moriui'

单选与多选

type="single" 使用单个 AcceptableValue，type="multiple" 使用值数组；也可由 v-model/defaultValue 的形状推断。

变体、尺寸与间距

根组件统一向 Item 提供 variant、size 和 spacing，单个 Item 仍可覆盖视觉变体或尺寸。

垂直方向

orientation="vertical" 切换布局与上下方向键；默认 horizontal 使用左右方向键。

禁用与自定义

根 disabled 禁用整组，Item 也可单独禁用；默认插槽可组合图标、文字和自定义内容。

RTL

水平组的左右方向键顺序遵循 dir，垂直组继续使用上下方向键。

示例

概览

multiple 模式控制多个文字格式。

<script setup lang="ts">
  import { shallowRef } from 'vue'
  import { Bold, Italic, Underline } from '@lucide/vue'
  import { ToggleGroup, ToggleGroupItem } from 'moriui'

  const formats = shallowRef(['bold'])
</script>

<template>
  <ToggleGroup
    v-model="formats"
    aria-label="文字格式"
    type="multiple"
    variant="outline"
  >
    <ToggleGroupItem value="bold" aria-label="切换粗体">
      <Bold aria-hidden="true" />
    </ToggleGroupItem>
    <ToggleGroupItem value="italic" aria-label="切换斜体">
      <Italic aria-hidden="true" />
    </ToggleGroupItem>
    <ToggleGroupItem value="underline" aria-label="切换下划线">
      <Underline aria-hidden="true" />
    </ToggleGroupItem>
  </ToggleGroup>
</template>

描边

single 模式在全部与未接筛选之间切换。

<script setup lang="ts">
  import { shallowRef } from 'vue'
  import { ToggleGroup, ToggleGroupItem } from 'moriui'

  const filter = shallowRef('all')
</script>

<template>
  <ToggleGroup
    v-model="filter"
    aria-label="来电筛选"
    type="single"
    variant="outline"
  >
    <ToggleGroupItem value="all">
      全部
    </ToggleGroupItem>
    <ToggleGroupItem value="missed">
      未接
    </ToggleGroupItem>
  </ToggleGroup>
</template>

尺寸

sm 与 default 展示不同密度。

<script setup lang="ts">
  import { shallowRef } from 'vue'
  import { ToggleGroup, ToggleGroupItem } from 'moriui'

  const small = shallowRef('top')
  const normal = shallowRef('left')
  const options = [
    { value: 'top', label: '上' },
    { value: 'bottom', label: '下' },
    { value: 'left', label: '左' },
    { value: 'right', label: '右' }
  ]
</script>

<template>
  <div class="flex flex-col gap-4">
    <ToggleGroup
      v-model="small"
      aria-label="小号对齐"
      size="sm"
      type="single"
      variant="outline"
    >
      <ToggleGroupItem v-for="item in options" :key="item.value" :value="item.value">
        {{ item.label }}
      </ToggleGroupItem>
    </ToggleGroup>
    <ToggleGroup
      v-model="normal"
      aria-label="默认对齐"
      type="single"
      variant="outline"
    >
      <ToggleGroupItem v-for="item in options" :key="item.value" :value="item.value">
        {{ item.label }}
      </ToggleGroupItem>
    </ToggleGroup>
  </div>
</template>

间距

spacing 调整 Item 之间的组件局部间距。

<script setup lang="ts">
  import { shallowRef } from 'vue'
  import { ToggleGroup, ToggleGroupItem } from 'moriui'

  const alignment = shallowRef('top')
</script>

<template>
  <ToggleGroup
    v-model="alignment"
    :spacing="4"
    aria-label="对齐方向"
    size="sm"
    type="single"
    variant="outline"
  >
    <ToggleGroupItem value="top">
      上
    </ToggleGroupItem>
    <ToggleGroupItem value="bottom">
      下
    </ToggleGroupItem>
    <ToggleGroupItem value="left">
      左
    </ToggleGroupItem>
    <ToggleGroupItem value="right">
      右
    </ToggleGroupItem>
  </ToggleGroup>
</template>

垂直

垂直多选组使用上下方向键。

<script setup lang="ts">
  import { shallowRef } from 'vue'
  import { Bold, Italic, Underline } from '@lucide/vue'
  import { ToggleGroup, ToggleGroupItem } from 'moriui'

  const formats = shallowRef(['bold', 'italic'])
</script>

<template>
  <ToggleGroup
    v-model="formats"
    :spacing="1"
    aria-label="文字格式"
    orientation="vertical"
    type="multiple"
  >
    <ToggleGroupItem value="bold" aria-label="切换粗体">
      <Bold aria-hidden="true" />
    </ToggleGroupItem>
    <ToggleGroupItem value="italic" aria-label="切换斜体">
      <Italic aria-hidden="true" />
    </ToggleGroupItem>
    <ToggleGroupItem value="underline" aria-label="切换下划线">
      <Underline aria-hidden="true" />
    </ToggleGroupItem>
  </ToggleGroup>
</template>

禁用

根 disabled 阻止整组状态变化。

<script setup lang="ts">
  import { shallowRef } from 'vue'
  import { Bold, Italic, Underline } from '@lucide/vue'
  import { ToggleGroup, ToggleGroupItem } from 'moriui'

  const formats = shallowRef(['bold'])
</script>

<template>
  <ToggleGroup
    v-model="formats"
    aria-label="禁用的文字格式"
    disabled
    type="multiple"
  >
    <ToggleGroupItem value="bold" aria-label="粗体">
      <Bold aria-hidden="true" />
    </ToggleGroupItem>
    <ToggleGroupItem value="italic" aria-label="斜体">
      <Italic aria-hidden="true" />
    </ToggleGroupItem>
    <ToggleGroupItem value="underline" aria-label="下划线">
      <Underline aria-hidden="true" />
    </ToggleGroupItem>
  </ToggleGroup>
</template>

自定义字重

Item 默认插槽组合字样与辅助标签。

字重

当前使用 font-normal。

<script setup lang="ts">
  import { shallowRef } from 'vue'
  import { Field, FieldDescription, FieldLabel, ToggleGroup, ToggleGroupItem } from 'moriui'

  const fontWeight = shallowRef('normal')
  const weights = [
    { value: 'light', label: '细体', class: 'font-light' },
    { value: 'normal', label: '常规', class: 'font-normal' },
    { value: 'medium', label: '中等', class: 'font-medium' },
    { value: 'bold', label: '粗体', class: 'font-bold' }
  ]
</script>

<template>
  <Field class="w-full max-w-sm">
    <FieldLabel>字重</FieldLabel>
    <ToggleGroup
      v-model="fontWeight"
      aria-label="字重"
      size="lg"
      type="single"
      variant="outline"
    >
      <ToggleGroupItem
        v-for="item in weights"
        :key="item.value"
        :aria-label="item.label"
        class="size-16 flex-col rounded-xl"
        :value="item.value"
      >
        <span class="text-2xl leading-none" :class="[item.class]">Aa</span>
        <span class="text-muted-foreground text-xs">{{ item.label }}</span>
      </ToggleGroupItem>
    </ToggleGroup>
    <FieldDescription>当前使用 <code class="bg-muted rounded-md px-1 py-0.5 font-mono">font-{{ fontWeight }}</code>。</FieldDescription>
  </Field>
</template>

RTL

阿拉伯语单选组使用 RTL 键盘顺序。

<script setup lang="ts">
  import { shallowRef } from 'vue'
  import { ToggleGroup, ToggleGroupItem } from 'moriui'

  const layout = shallowRef('list')
</script>

<template>
  <ToggleGroup
    v-model="layout"
    aria-label="طريقة العرض"
    dir="rtl"
    type="single"
    variant="outline"
  >
    <ToggleGroupItem value="list">
      قائمة
    </ToggleGroupItem>
    <ToggleGroupItem value="grid">
      شبكة
    </ToggleGroupItem>
    <ToggleGroupItem value="cards">
      بطاقات
    </ToggleGroupItem>
  </ToggleGroup>
</template>

API

属性	类型	默认值	说明
ToggleGroup v-model	`AcceptableValue \| AcceptableValue[]`	`undefined`	single 单值或 multiple 值数组。
ToggleGroup type	`'single' \| 'multiple'`	`按值形状推断`	显式指定单选或多选模式。
ToggleGroup defaultValue	`AcceptableValue \| AcceptableValue[]`	`undefined`	非受控初始选择。
ToggleGroup variant	`'default' \| 'outline'`	`'default'`	整组 Item 的默认视觉层级。
ToggleGroup size	`'sm' \| 'default' \| 'lg'`	`'default'`	整组 Item 的默认尺寸。
ToggleGroup spacing	`number`	`2`	Item 之间的间距倍数。
ToggleGroup orientation	`'horizontal' \| 'vertical'`	`'horizontal'`	布局与方向键导航方向。
ToggleGroup disabled / rovingFocus / loop	`boolean`	`false / true / true`	整组禁用、移动焦点与循环导航。
ToggleGroupItem value	`AcceptableValue`	`—`	必填项目值。
ToggleGroupItem disabled	`boolean`	`false`	单独禁用当前项目。

无障碍说明

ToggleGroup 复用 Reka UI 的 group、aria-pressed、roving focus、方向键与循环导航。根组件需要 aria-label 或 aria-labelledby；每个仅图标 Item 必须有 aria-label，orientation 应与视觉排列一致。

关联组件

按钮编组切换控件