Reka UI 标志Reka
backdrop
示例
组件

切换组

一组可以开启或关闭的双状态按钮。

功能

  • 全键盘导航。
  • 支持水平/垂直方向。
  • 支持单选和多选按钮。
  • 可受控或非受控。

安装

从命令行安装此组件。

sh
$ npm add reka-ui

结构

导入组件。

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

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

API 参考

根

包含切换组的所有部分。

属性默认类型
as
'div'
AsTag | Component

此组件应渲染为的元素或组件。可通过 asChild 覆盖。

asChild
布尔值

更改默认渲染元素为作为子项传递的元素，合并它们的属性和行为。

阅读我们的 组合指南了解更多详情。

defaultValue
AcceptableValue | AcceptableValue[]

项的默认活动值。

当您不需要控制项的状态时使用。

dir
'ltr' | 'rtl'

适用时，组合框的阅读方向。
如果省略，则全局继承自 ConfigProvider 或假定为 LTR（从左到右）阅读模式。

disabled
false
布尔值

当为 true 时，防止用户与切换组及其所有项进行交互。

loop
true
布尔值

当 loop 和 rovingFocus 为 true 时，键盘导航将从最后一项循环到第一项，反之亦然。

modelValue
AcceptableValue | AcceptableValue[]

活动项的受控值。

当您需要控制项的状态时使用此项。可以通过 v-model 进行绑定

name
string

字段的名称。随其所属的表单一起作为名称/值对提交。

orientation
'vertical' | 'horizontal'

组件的方向，决定焦点如何移动：horizontal 用于左右箭头，vertical 用于上下箭头。

required
布尔值

当为 true 时，表示用户必须在所属表单提交前设置值。

rovingFocus
true
布尔值

当 `false` 时，禁用使用箭头键在项目间导航。

type
'single' | 'multiple'

确定一次可以选择“单个”或“多个”项。

此属性将覆盖从 modelValue 和 defaultValue 推断的类型。

事件触发载荷
update:modelValue
[payload: AcceptableValue | AcceptableValue[]]

当切换组件的值改变时调用的事件处理程序。

插槽（默认）载荷
modelValue
AcceptableValue | AcceptableValue[] | undefined

当前切换值

数据属性值
[data-orientation]"垂直" | "水平"

项

组中的一个项。

属性默认类型
as
'button'
AsTag | Component

此组件应渲染为的元素或组件。可通过 asChild 覆盖。

asChild
布尔值

更改默认渲染元素为作为子项传递的元素，合并它们的属性和行为。

阅读我们的 组合指南了解更多详情。

disabled
布尔值

当为 true 时，阻止用户与切换组件交互。

值*
AcceptableValue

切换组项的字符串值。切换组内的所有项都应使用唯一值。

插槽（默认）载荷
modelValue
布尔值

当前值

state
'on' | 'off'

当前状态

pressed
布尔值

当前按下状态

disabled
布尔值

当前禁用状态

数据属性值
[data-state]"on" | "off"
[data-disabled]禁用时存在
[data-orientation]"垂直" | "水平"

示例

确保始终有值

您可以控制组件以确保其有值。

vue
<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>

可访问性

使用 漫游 tabindex 来管理项之间的焦点移动。

键盘交互

键描述
Tab
将焦点移动到已按下的项或组中的第一个项。
空格键
激活/停用该项。
回车键
激活/停用该项。
向下箭头键
将焦点移动到组中的下一个项。
向右箭头
将焦点移动到组中的下一个项。
向上箭头键
将焦点移动到组中的上一个项。
向左箭头
将焦点移动到组中的上一个项。
Home
将焦点移动到第一个项。
End
将焦点移动到最后一个项。