useFocusTrap

類別

@Integrations

導出大小

533 B

套件

@vueuse/integrations

最後變更

5 天前

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>

多個 Ref

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 { 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 { 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>

類型宣告

顯示類型宣告

typescript

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