跳到主要内容

useFocusTrap

分类
导出大小
515 B
@vueuse/integrations
上次更改
3 个月前

focus-trap 的响应式封装。

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

演示

可在 @vueuse/integrations 插件中使用。

安装

bash
npm i focus-trap@^7

用法

基本用法

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>

多个引用

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>

动态焦点目标

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>

自动聚焦

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>

条件渲染

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

使用组件

使用 UseFocusTrap 组件时,焦点陷阱将在组件挂载时自动激活,并在卸载时停用。

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.cn/useFocusTrap */ export declare function
useFocusTrap
(
target
:
MaybeRefOrGetter
<
Arrayable
<
MaybeRefOrGetter
<string> |
MaybeComputedElementRef
>
>,
options
?: UseFocusTrapOptions,
): UseFocusTrapReturn

来源

源代码演示文档

贡献者

Anthony Fu
Anthony Fu
IlyaL
IlyaL
Vida Xie
SerKo
XiangYu Liu
Robin
Guspan Tanadi
我想静静
Sma11X
Doctorwu
Soviut
vaakian X
azaleta
Agénor Debriat
Curt Grimes
Roman Harmyder
Alex Kozack
Jordy
wheat

更新日志

d5bcd - fix(integrations): use relative import in component.ts (#5025)
8c521 - feat(components)!: 重构组件并使其保持一致 (#4912)
v13.6.0
3d5e5 - feat: 暴露 updateContainerElements 用于动态容器... (#4849)
v12.8.0
7432f - feat(types): 废弃 MaybeRefMaybeRefOrGetter,转而使用 Vue 的原生类型 (#4636)
v12.3.0
021d0 - feat(toArray): 新的实用函数 (#4432)
59f75 - feat(toValue): 废弃 @vueuse/shared 中的 toValue,转而使用 Vue 的原生函数
0a9ed - feat!: 放弃对 Vue 2 的支持,优化打包并清理 (#4349)
83c41 - feat: 支持多个引用 (#4022)

根据 MIT 许可证发布。