漫游焦点

实现漫游 tabindex 方法以管理项目之间焦点的实用组件。

查看代码

Tab 键聚焦

提示

结构

导入所有部分并将其组合。

vue

<script setup>
import { RovingFocusGroup, RovingFocusItem } from 'reka-ui'
</script>

<template>
  <RovingFocusGroup>
    <RovingFocusItem />
  </RovingFocusGroup>
</template>

API 参考

分组

包含漫游焦点组件的所有部分

属性	默认	类型
`as`	`'div'`	`AsTag \| Component` 此组件应渲染为的元素或组件。可通过 `asChild` 覆盖。
`asChild`		`布尔值` 更改默认渲染元素为作为子项传递的元素，合并它们的属性和行为。阅读我们的组合指南了解更多详情。
`currentTabStopId`		`string \| null` 当前停止项的受控值。可以绑定为 `v-model`。
`defaultCurrentTabStopId`		`string` 当前停止项的值。当您不需要控制停止项的状态时使用。
`dir`		`'ltr' \| 'rtl'` 项目之间的导航方向。
`loop`	`false`	`布尔值` 键盘导航是否应该循环。
`orientation`		`'vertical' \| 'horizontal'` 组的方向。主要用于根据方向（左右或上下）进行箭头导航。
`preventScrollOnEntryFocus`	`false`	`布尔值` 当为 `true` 时，在聚焦时将阻止滚动到聚焦项。

事件触发	载荷
`entryFocus`	`[事件: Event]` 容器获得焦点时调用的事件处理程序。可阻止其默认行为。
`update:currentTabStopId`	`[value: string \| null]`

方法	类型
`getItems`	`(includeDisabledItem?: boolean) => { ref: HTMLElement; value?: any; }[]`

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

项

将继承漫游 tabindex 的项。

属性	默认	类型
`active`		`布尔值` 当为 `true` 时，项目将最初获得焦点。
`allowShiftKey`		`布尔值` 当为 `true` 时，按住 Shift + 方向键将允许聚焦到下一个/上一个项目。
`as`	`'span'`	`AsTag \| Component` 此组件应渲染为的元素或组件。可通过 `asChild` 覆盖。
`asChild`		`布尔值` 更改默认渲染元素为作为子项传递的元素，合并它们的属性和行为。阅读我们的组合指南了解更多详情。
`focusable`	`true`	`布尔值` 当为 `false` 时，项目将不可聚焦。
`tabStopId`		`string`

数据属性	值
`[data-active]`	当不活跃时存在
`[data-disabled]`	当不可聚焦时存在
`[data-orientation]`	`"vertical" \| "horizontal" \| "undefined"`

示例

垂直方向

vue

<template>
  <RovingFocusGroup :orientation="'vertical'">
    …
  </RovingFocusGroup>
</template>

循环

使用 loop 属性启用从最后一个项目到第一个项目的漫游，反之亦然。

vue

<template>
  <RovingFocusGroup loop>
    …
  </RovingFocusGroup>
</template>

初始焦点项

将 active 属性设置为项目以最初聚焦该项目。

vue

<template>
  <RovingFocusGroup>
    <RovingFocusItem>1</RovingFocusItem>
    <RovingFocusItem active>2</RovingFocusItem>
    <RovingFocusItem>3</RovingFocusItem>
  </RovingFocusGroup>
</template>

不可聚焦项

将 focusable="false" 属性设置为项目将阻止它们被聚焦。

vue

<template>
  <RovingFocusGroup>
    <RovingFocusItem>1</RovingFocusItem>
    <RovingFocusItem :focusable="false">2</RovingFocusItem>
    <RovingFocusItem>3</RovingFocusItem>
  </RovingFocusGroup>
</template>

可访问性

遵循《组合组件内的键盘导航》。

键盘交互

键	描述
`向下箭头键`	将焦点移动到组中的下一个漫游焦点项。
`向右箭头`	将焦点移动到组中的下一个漫游焦点项。
`向上箭头键`	将焦点移动到组中的上一个漫游焦点项。
`向左箭头`	将焦点移动到组中的上一个漫游焦点项。
`SpaceEnter`	触发漫游焦点项的点击。

漫游焦点 ​

结构 ​

API 参考 ​

分组 ​

项 ​

示例 ​

垂直方向 ​

循环 ​

初始焦点项 ​

不可聚焦项 ​

可访问性 ​

键盘交互 ​