Lzh on GitHub

ToggleGroup

一组可以打开或关闭的双状态按钮。
<script setup lang="ts">
import { Icon } from '@iconify/vue'
import { ToggleGroupItem, ToggleGroupRoot } from 'reka-ui'
import { ref } from 'vue'

const toggleStateSingle = ref('left')
const toggleStateMultiple = ref(['italic'])

const toggleGroupItemClasses
  = 'hover:bg-stone-50 text-gray-700 data-[state=on]:bg-stone-100 flex h-[35px] w-[35px] items-center justify-center bg-white text-base leading-4 first:rounded-l-[7px] last:rounded-r-[7px] focus:z-10 focus:shadow-[0_0_0_2px] focus:shadow-black focus:outline-none'
</script>

<template>
  <div>
    <ToggleGroupRoot
      v-model="toggleStateSingle"
      type="single"
      class="flex border shadow-sm rounded-lg"
    >
      <ToggleGroupItem
        value="left"
        aria-label="Toggle italic"
        :class="toggleGroupItemClasses"
      >
        <Icon
          icon="radix-icons:text-align-left"
          class="w-[15px] h-[15px]"
        />
      </ToggleGroupItem>
      <ToggleGroupItem
        value="center"
        aria-label="Toggle italic"
        :class="toggleGroupItemClasses"
        class="border-x"
      >
        <Icon
          icon="radix-icons:text-align-center"
          class="w-[15px] h-[15px]"
        />
      </ToggleGroupItem>
      <ToggleGroupItem
        value="right"
        aria-label="Toggle italic"
        :class="toggleGroupItemClasses"
      >
        <Icon
          icon="radix-icons:text-align-right"
          class="w-[15px] h-[15px]"
        />
      </ToggleGroupItem>
    </ToggleGroupRoot>
    <br>
    <ToggleGroupRoot
      v-model="toggleStateMultiple"
      type="multiple"
      class="flex border shadow-sm rounded-lg"
    >
      <ToggleGroupItem
        value="bold"
        aria-label="Toggle italic"
        :class="toggleGroupItemClasses"
      >
        <Icon
          icon="radix-icons:font-bold"
          class="w-[15px] h-[15px]"
        />
      </ToggleGroupItem>
      <ToggleGroupItem
        value="italic"
        aria-label="Toggle italic"
        :class="toggleGroupItemClasses"
        class="border-x"
      >
        <Icon
          icon="radix-icons:font-italic"
          class="w-[15px] h-[15px]"
        />
      </ToggleGroupItem>
      <ToggleGroupItem
        value="strikethrough"
        aria-label="Toggle italic"
        :class="toggleGroupItemClasses"
      >
        <Icon
          icon="radix-icons:strikethrough"
          class="w-[15px] h-[15px]"
        />
      </ToggleGroupItem>
    </ToggleGroupRoot>
  </div>
</template>

特性 (Features)

  • 完整的键盘导航。
  • 支持水平/垂直方向。
  • 支持单个和多个按下按钮。
  • 可控或非控。

安装 (Installation)

从命令行安装组件。

$ npm add reka-ui

结构 (Anatomy)

导入组件。

<script setup>
import { ToggleGroupItem, ToggleGroupRoot } from 'reka-ui'
</script>

<template>
  <ToggleGroupRoot>
    <ToggleGroupItem />
  </ToggleGroupRoot>
</template>

API 参考 (API Reference)

根 (Root)

包含切换组的所有部分。

属性默认值类型描述
as'div'AsTag | Component此组件应渲染为的元素或组件。可通过 asChild 覆盖。
asChildboolean将默认渲染的元素替换为作为子元素传递的元素，合并它们的 props 和行为。阅读我们的组合指南了解更多详情。
defaultValueAcceptableValue | AcceptableValue[]项目的默认活动值。当您不需要控制项目状态时使用。
dir'ltr' | 'rtl'组合框的阅读方向（如果适用）。如果省略，则全局继承自 ConfigProvider 或假定为 LTR（从左到右）阅读模式。
disabledfalseboolean当 true 时，阻止用户与切换组及其所有项目交互。
looptrueboolean当 loop 和 rovingFocus 都为 true 时，键盘导航将从最后一项循环到第一项，反之亦然。
modelValueAcceptableValue | AcceptableValue[]活动项目的受控值。当您需要控制项目状态时使用。可与 v-model 绑定。
namestring字段的名称。作为名称/值对的一部分随其所属的表单一起提交。
orientation'vertical' | 'horizontal'组件的方向，它决定了焦点移动方式：horizontal 用于左右箭头，vertical 用于上下箭头。
requiredboolean当 true 时，表示用户必须在提交所属表单之前设置值。
rovingFocustrueboolean当 false 时，使用箭头键在项目之间导航将被禁用。
type'single' | 'multiple'决定一次可以选择“单个”或“多个”项目。此属性将覆盖从 modelValue 和 defaultValue 推断的类型。

发送事件

事件名称Payload描述
update:modelValue[payload: AcceptableValue | AcceptableValue[]]切换值更改时调用的事件处理程序。

默认插槽

插槽参数插槽参数类型描述
modelValueAcceptableValue | AcceptableValue[] | undefined当前切换值

数据属性 (Data Attributes)

数据属性值
[data-orientation]"vertical" | "horizontal"

项目 (Item)

组中的一个项目。

属性默认值类型描述
as'button'AsTag | Component此组件应渲染为的元素或组件。可通过 asChild 覆盖。
asChildboolean将默认渲染的元素替换为作为子元素传递的元素，合并它们的 props 和行为。阅读我们的组合指南了解更多详情。
disabledboolean当 true 时，阻止用户与切换开关交互。
valueAcceptableValue切换组项目的字符串值。切换组中的所有项目都应使用唯一值。

默认插槽

插槽参数插槽参数类型描述
modelValueboolean当前值
state'on' | 'off'当前状态
pressedboolean当前按下状态
disabledboolean当前禁用状态

数据属性 (Data Attributes)

数据属性值
[data-state]"on" | "off"
[data-disabled]禁用时存在
[data-orientation]"vertical" | "horizontal"

示例 (Examples)

确保始终有值 (Ensuring there is always a value)

您可以控制组件以确保始终有一个值。

<script setup>
import { ToggleGroupItem, ToggleGroupRoot } from 'reka-ui'
import { ref } from 'vue'

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

<template>
  <ToggleGroupRoot
    :model-value="value"
    @update:model-value="(val) => {
      if (val) value = val
    }"
  >
    <ToggleGroupItem value="left">
      <TextAlignLeftIcon />
    </ToggleGroupItem>
    <ToggleGroupItem value="center">
      <TextAlignCenterIcon />
    </ToggleGroupItem>
    <ToggleGroupItem value="right">
      <TextAlignRightIcon />
    </ToggleGroupItem>
  </ToggleGroupRoot>
</template>

可访问性 (Accessibility)

使用漫游 Tab 索引 (roving tabindex) 来管理项目之间的焦点移动。

键盘交互 (Keyboard Interactions)

按键描述
Tab将焦点移动到已按下的项目或组中的第一个项目。
Space激活/禁用项目。
Enter激活/禁用项目。
ArrowDown将焦点移动到组中的下一个项目。
ArrowRight将焦点移动到组中的下一个项目。
ArrowUp将焦点移动到组中的上一个项目。
ArrowLeft将焦点移动到组中的上一个项目。
Home将焦点移动到第一个项目。
End将焦点移动到最后一个项目。