Lzh on GitHub

漫游焦点

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

RovingFocus 是一个用于管理一组可聚焦元素间焦点行为的实用组件，它实现了一种称为 Roving TabIndex（游走 TabIndex）的方法。

省略代码

在 复合组件内的键盘导航 中了解有关漫游 tabindex 的更多信息。

结构

导入所有部件并将其组合在一起。

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

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

API 参考

组 (Group)

包含漫游焦点的所有部分。

Prop默认值类型说明
as'div'AsTag | Component此组件应渲染为的元素或组件。可以通过 asChild 覆盖。
asChildboolean将默认渲染的元素更改为作为子元素传递的元素，合并它们的 props 和行为。 阅读我们的组合指南了解更多详情。
currentTabStopIdstring | null当前停止项目的受控值。可以绑定为 v-model。
defaultCurrentTabStopIdstring当前停止项目的值。当您不需要控制停止项目的状态时使用。
dir'ltr' | 'rtl'项目之间的导航方向。
loopfalseboolean键盘导航是否应循环。
orientation'vertical' | 'horizontal'组的方向。主要用于相应地进行箭头导航（左 & 右 vs. 上 & 下）。
preventScrollOnEntryFocusfalseboolean当为 true 时，在聚焦时将阻止滚动到焦点项目。

EmitPayload

事件EmitPayload类型说明
entryFocus[event: Event]容器被聚焦时调用的事件处理程序。可以阻止默认行为。
update:currentTabStopId[value: string | null]

方法 (Methods)

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

Data Attribute (数据属性)

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

项目 (Item)

将继承漫游 tabindex 的项目。

Prop默认值类型说明
activeboolean当为 true 时，项目最初将被聚焦。
allowShiftKeyboolean当为 true 时，Shift + 箭头键将允许聚焦下一个/上一个项目。
as'span'AsTag | Component此组件应渲染为的元素或组件。可以通过 asChild 覆盖。
asChildboolean将默认渲染的元素更改为作为子元素传递的元素，合并它们的 props 和行为。 阅读我们的 组合 指南了解更多详情。
focusabletrueboolean当为 false 时，项目将不可聚焦。
tabStopIdstring

Data Attribute (数据属性)

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

示例

垂直方向

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

循环

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

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

初始焦点项目

将 active prop 设置为项目以使项目最初聚焦。

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

不可聚焦的项目

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

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

可访问性

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

键盘交互

键描述
ArrowDown将焦点移动到组中的下一个漫游焦点项。
ArrowRight将焦点移动到组中的下一个漫游焦点项。
ArrowUp将焦点移动到组中的上一个漫游焦点项。
ArrowLeft将焦点移动到组中的上一个漫游焦点项。
Space + Enter触发漫游焦点项的点击。