コンテンツにスキップ

useFocusTrap

カテゴリー
エクスポートサイズ
718 B
パッケージ
@vueuse/integrations
最終変更
先週

focus-trap のリアクティブなラッパー。

渡すことができるオプションの詳細については、focus-trap ドキュメントの createOptions を参照してください。

デモ

@vueuse/integrations アドオンで利用できます。

インストール

bash
npm i focus-trap@^7

使い方

基本的な使い方

vue
<script setup>
import { useFocusTrap } from '@vueuse/integrations/useFocusTrap'
import { ref } from 'vue'

const target = ref()
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>
import { useFocusTrap } from '@vueuse/integrations/useFocusTrap'
import { ref } from 'vue'

const targetOne = ref()
const targetTwo = ref()
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>
import { useFocusTrap } from '@vueuse/integrations/useFocusTrap'
import { ref } from 'vue'

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

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

条件付きレンダリング

この関数は、v-if を使用した条件付きレンダリングを持つ要素のフォーカスを適切にアクティブ化できません。これは、フォーカスがアクティブ化される時点で DOM に存在しないためです。これを解決するには、次のティックでアクティブ化する必要があります。

vue
<script setup>
import { nextTick, ref } from 'vue'

const target = ref()
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>
import { UseFocusTrap } from '@vueuse/integrations/useFocusTrap/component'
import { ref } from 'vue'

const show = ref(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: Ref<boolean>
  /**
   * Indicates if the focus trap is currently paused
   */
  isPaused: Ref<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.dokyumento.jp/useFocusTrap
 */
export declare function useFocusTrap(
  target: Arrayable<MaybeRefOrGetter<string> | MaybeComputedElementRef>,
  options?: UseFocusTrapOptions,
): UseFocusTrapReturn

ソース

ソースデモドキュメント

貢献者

Anthony Fu
Anthony Fu
Sma11X
Doctorwu
Soviut
vaakian X
azaleta
Agénor Debriat
Curt Grimes
Roman Harmyder
Alex Kozack
Jordy
wheat

変更履歴

v12.0.0-beta.1 2024/11/21
0a9ed - feat!: Vue 2 のサポートを終了、バンドルを最適化し、クリーンアップします (#4349)
v11.0.0-beta.2 2024/07/17
83c41 - feat: 複数のrefをサポート (#4022)
v9.11.0 2023/01/17
d5321 - fix(components): defineComponent を純粋としてマーク (#2623)
v9.3.1 2022/10/17
578bc - feat: コンポーネントでオプションを有効化 (#2321)

MIT Licenseの下でリリースされています。