Skip to content

useFocusTrap

focus-trap 的反应式封装。

¥Reactive wrapper for focus-trap.

有关可以传递哪些选项的更多信息,请参阅 focus-trap 文档中的 createOptions

¥For more information on what options can be passed, see createOptions in the focus-trap documentation.

示例

Available in the @vueuse/integrations add-on.

安装

¥Install

bash
npm i focus-trap@^7

用法

¥Usage

基本用法

¥Basic Usage

vue
<script setup lang="ts">
import { useFocusTrap } from '@vueuse/integrations/useFocusTrap'
import { useTemplateRef } from 'vue'

const target = useTemplateRef<HTMLDivElement>('target')
const { hasFocus, activate, deactivate } = useFocusTrap(target)
</script>

<template>
  <div>
    <button @click="activate()">
      Activate
    </button>
    <div ref="target">
      <span>Has Focus: {{ hasFocus }}</span>
      <input type="text">
      <button @click="deactivate()">
        Deactivate
      </button>
    </div>
  </div>
</template>

多个引用

¥Multiple Refs

vue
<script setup lang="ts">
import { useFocusTrap } from '@vueuse/integrations/useFocusTrap'
import { useTemplateRef } from 'vue'

const targetOne = useTemplateRef<HTMLDivElement>('targetOne')
const targetTwo = useTemplateRef<HTMLDivElement>('targetTwo')
const { hasFocus, activate, deactivate } = useFocusTrap([targetOne, targetTwo])
</script>

<template>
  <div>
    <button @click="activate()">
      Activate
    </button>
    <div ref="targetOne">
      <span>Has Focus: {{ hasFocus }}</span>
      <input type="text">
    </div>
    ...
    <div ref="targetTow">
      <p>Another target here</p>
      <input type="text">
      <button @click="deactivate()">
        Deactivate
      </button>
    </div>
  </div>
</template>

自动对焦

¥Automatically Focus

vue
<script setup lang="ts">
import { useFocusTrap } from '@vueuse/integrations/useFocusTrap'
import { useTemplateRef } from 'vue'

const target = useTemplateRef<HTMLDivElement>('target')
const { hasFocus, activate, deactivate } = useFocusTrap(target, { immediate: true })
</script>

<template>
  <div>
    <div ref="target">
      ...
    </div>
  </div>
</template>

条件渲染

¥Conditional Rendering

此函数无法正确激活使用 v-if 进行条件渲染的元素的焦点。这是因为在焦点激活时它们不存在于 DOM 中。要解决此问题,你需要在下一个滴答时激活。

¥This function can't properly activate focus on elements with conditional rendering using v-if. This is because they do not exist in the DOM at the time of the focus activation. To solve this you need to activate on the next tick.

vue
<script setup lang="ts">
import { nextTick, useTemplateRef } from 'vue'

const target = useTemplateRef<HTMLDivElement>('target')
const { activate, deactivate } = useFocusTrap(target, { immediate: true })

const show = ref(false)

async function reveal() {
  show.value = true

  await nextTick()
  activate()
}
</script>

<template>
  <div>
    <div v-if="show" ref="target">
      ...
    </div>

    <button @click="reveal">
      Reveal and Focus
    </button>
  </div>
</template>

使用组件

¥Using Component

对于 UseFocusTrap 组件,焦点陷阱将在安装该组件时自动激活,并在卸载时停用。

¥With the UseFocusTrap component, Focus Trap will be activated automatically on mounting this component and deactivated on unmount.

vue
<script setup lang="ts">
import { UseFocusTrap } from '@vueuse/integrations/useFocusTrap/component'
import { shallowRef } from 'vue'

const show = shallowRef(false)
</script>

<template>
  <UseFocusTrap v-if="show" :options="{ immediate: true }">
    <div class="modal">
      ...
    </div>
  </UseFocusTrap>
</template>