Reka UI logoReka UI 中文文档
backdrop
Examples
组件

ToggleGroup

一组可以开关的双态按钮。

特性

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

安装

通过命令行安装该组件。

sh
$ npm add reka-ui

结构

导入组件。

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

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

API 参考

Root

包含切换组的所有部分。

PropDefaultType
as
'div'
AsTag | Component

The element or component this component should render as. Can be overwritten by asChild.

asChild
boolean

Change the default rendered element for the one passed as a child, merging their props and behavior.

Read our Composition guide for more details.

defaultValue
AcceptableValue | AcceptableValue[]

The default active value of the item(s).

Use when you do not need to control the state of the item(s).

dir
'ltr' | 'rtl'

The reading direction of the combobox when applicable.
If omitted, inherits globally from ConfigProvider or assumes LTR (left-to-right) reading mode.

disabled
false
boolean

When true, prevents the user from interacting with the toggle group and all its items.

loop
true
boolean

When loop and rovingFocus is true, keyboard navigation will loop from last item to first, and vice versa.

modelValue
AcceptableValue | AcceptableValue[]

The controlled value of the active item(s).

Use this when you need to control the state of the items. Can be binded with v-model

name
string

The name of the field. Submitted with its owning form as part of a name/value pair.

orientation
'vertical' | 'horizontal'

The orientation of the component, which determines how focus moves: horizontal for left/right arrows and vertical for up/down arrows.

required
boolean

When true, indicates that the user must set the value before the owning form can be submitted.

rovingFocus
true
boolean

When false, navigating through the items using arrow keys will be disabled.

type
'single' | 'multiple'

Determines whether a "single" or "multiple" items can be selected at a time.

This prop will overwrite the inferred type from modelValue and defaultValue.

EmitPayload
update:modelValue
[payload: AcceptableValue | AcceptableValue[]]

Event handler called when the value of the toggle changes.

Slots (default)Payload
modelValue
AcceptableValue | AcceptableValue[] | undefined

Current toggle values

Data AttributeValue
[data-orientation]"vertical" | "horizontal"

Item

组中的一个项目。

PropDefaultType
as
'button'
AsTag | Component

The element or component this component should render as. Can be overwritten by asChild.

asChild
boolean

Change the default rendered element for the one passed as a child, merging their props and behavior.

Read our Composition guide for more details.

disabled
boolean

When true, prevents the user from interacting with the toggle.

value*
AcceptableValue

A string value for the toggle group item. All items within a toggle group should use a unique value.

Slots (default)Payload
modelValue
boolean

Current value

state
'on' | 'off'

Current state

pressed
boolean

Current pressed state

disabled
boolean

Current disabled state

Data AttributeValue
[data-state]"on" | "off"
[data-disabled]禁用时出现
[data-orientation]"vertical" | "horizontal"

示例

确保始终存在一个值

您可以控制组件以确保存在一个值。

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>

无障碍访问

使用 roving tabindex 来管理项目间的焦点移动。

键盘交互

KeyDescription
Tab
将焦点移动到当前选中项或组中的第一个项目。
Space
激活/停用项目。
Enter
激活/停用项目。
ArrowDown
将焦点移动到组中的下一个项目。
ArrowRight
将焦点移动到组中的下一个项目。
ArrowUp
将焦点移动到组中的上一个项目。
ArrowLeft
将焦点移动到组中的上一个项目。
Home
将焦点移动到第一个项目。
End
将焦点移动到最后一个项目。