Reka UI 徽标Reka
backdrop
示例
实用工具

焦点范围

在组件边界内管理焦点，支持焦点捕获和循环导航。

焦点范围提供对组件边界内键盘焦点管理的增强控制。它可以将焦点捕获在其容器内，并可选地循环焦点导航，使其成为模态界面和其他需要管理焦点状态的交互式组件的理想选择。

API 参考

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

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

asChild
布尔值

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

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

loop
false
布尔值

当设置为 true 时，从最后一个可Tab的项目跳转将焦点移动到第一个可Tab的项目，从第一个可Tab的项目Shift+Tab将焦点移动到最后一个可Tab的项目。

trapped
false
布尔值

当设置为 true 时，焦点无法通过键盘、指针或编程方式逃离焦点范围。

事件触发载荷
mountAutoFocus
[事件: Event]

在组件挂载时自动聚焦时调用的事件处理函数。可以被阻止。

unmountAutoFocus
[事件: Event]

在组件卸载时自动聚焦时调用的事件处理函数。可以被阻止。

示例

带焦点捕获的基本用法

vue
<template>
  <FocusScope :trapped="true">
    <div>
      <button>Action 1</button>
      <button>Action 2</button>
      <button>Close</button>
    </div>
  </FocusScope>
</template>

带焦点循环

启用捕获和循环，实现完整的焦点管理

vue
<template>
  <FocusScope :trapped="true" :loop="true">
    <div>
      <button v-for="item in items" :key="item.id">
        {{ item.label }}
      </button>
    </div>
  </FocusScope>
</template>

处理焦点事件

vue
<script setup>
function handleMountFocus(event) {
  // Prevent default auto-focus behavior if needed
  event.preventDefault()
}
</script>

<template>
  <FocusScope
    @mount-auto-focus="handleMountFocus"
    @unmount-auto-focus="handleUnmountFocus"
  >
    <div>
      …
    </div>
  </FocusScope>
</template>

警告

在使用捕获模式时，请确保作用域内始终至少有一个可聚焦元素，以防止焦点被困在无法访问的状态。