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>

动态焦点目标

¥Dynamic Focus Target

vue
<script setup lang="ts">
import { 
useFocusTrap
} from '@vueuse/integrations/useFocusTrap'
import {
computed
,
shallowRef
,
useTemplateRef
} from 'vue'
const
left
=
useTemplateRef
('left')
const
right
=
useTemplateRef
('right')
const
currentRef
=
shallowRef
<'left' | 'right'>('left')
const
target
=
computed
(() =>
currentRef
.
value
=== 'left'
?
left
:
currentRef
.
value
=== 'right'
?
right
: null, ) const {
activate
} =
useFocusTrap
(
target
)
</script> <template> <
div
>
<
div
ref
="
left
"
class
="left">
... </
div
>
<
div
ref
="
right
"
class
="right">
... </
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 { 
useFocusTrap
} from '@vueuse/integrations/useFocusTrap'
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>

类型声明

显示类型声明
ts
export interface UseFocusTrapOptions extends Options {
  /**
   * Immediately activate the trap
   */
  
immediate
?: boolean
} export interface UseFocusTrapReturn { /** * Indicates if the focus trap is currently active */
hasFocus
:
ShallowRef
<boolean>
/** * Indicates if the focus trap is currently paused */
isPaused
:
ShallowRef
<boolean>
/** * Activate the focus trap * * @see https://github.com/focus-trap/focus-trap#trapactivateactivateoptions * @param opts Activate focus trap options */
activate
: (
opts
?:
ActivateOptions
) => void
/** * Deactivate the focus trap * * @see https://github.com/focus-trap/focus-trap#trapdeactivatedeactivateoptions * @param opts Deactivate focus trap options */
deactivate
: (
opts
?:
DeactivateOptions
) => void
/** * Pause the focus trap * * @see https://github.com/focus-trap/focus-trap#trappause */
pause
:
Fn
/** * Unpauses the focus trap * * @see https://github.com/focus-trap/focus-trap#trapunpause */
unpause
:
Fn
} /** * Reactive focus-trap * * @see https://vueuse.org/useFocusTrap */ export declare function
useFocusTrap
(
target
:
Arrayable
<
MaybeRefOrGetter
<string> |
MaybeComputedElementRef
>,
options
?: UseFocusTrapOptions,
): UseFocusTrapReturn

源代码

源代码示例文档

变更日志

3d5e5 - feat: expose updateContainerElements for dynamic contai… (#4849)