floating-ui-vue-skilld

@floating-ui/vue 2.0.1

アンカー位置指定用の Vue 3 コンポーザブルです。useFloating() は、フローティング要素（ツールチップ、ポップオーバー、メニュー）を参照要素の隣に配置する x／y 座標を計算します。

バージョンの制限

• Vue >=3.3.0 のみ対応しています（ピア依存関係、package.json:58）。v2.0.0 で vue-demi レイヤーが削除され、Vue 2 および Vue <3.3 のサポートが終了しました。
• Vue 2 または Vue <3.3 のプロジェクトでは、npm install @floating-ui/vue@1 を引き続き使用する必要があります（https://floating-ui.com/docs/vue）。
• ランタイム依存関係：@floating-ui/dom@^1.8.0、@floating-ui/utils@^0.2.12（package.json:46-49）。
• exactOptionalPropertyTypes を有効にした TypeScript に対応しています（v2.0.1 以降。オプショナルプロパティの型は T | undefined です。dist/floating-ui.vue.d.ts:198-224）。

クイックスタート

<script setup>
import {ref} from 'vue';
import {useFloating, offset, flip, shift, autoUpdate} from '@floating-ui/vue';

const reference = ref(null);
const floating = ref(null);
const open = ref(false);

const {floatingStyles, isPositioned} = useFloating(reference, floating, {
  open,
  middleware: [offset(10), flip(), shift()],
  whileElementsMounted: autoUpdate,
});
</script>

<template>
  <button ref="reference" @click="open = !open">Button</button>
  <div v-if="open" ref="floating" :style="floatingStyles">Tooltip</div>
</template>

デフォルトの配置は bottom です。位置指定にはデフォルトで transform を使用します（https://floating-ui.com/docs/vue）。

1.x からの API 変更

• 破壊的変更（2.0.0）：vue-demi が削除されました。Vue 2 および Vue <3.3 はサポートされなくなりました。その他の破壊的な API 変更はありません。useFloating、arrow およびすべての再エクスポートのシグネチャは、1.1.x のものが維持されています（https://github.com/floating-ui/floating-ui/releases/tag/@floating-ui/[email protected]）。
• 修正（2.0.1）：exactOptionalPropertyTypes のもとで、オプショナルな useFloating オプションに明示的な undefined を指定できるようになりました（https://github.com/floating-ui/floating-ui/releases/tag/@floating-ui/[email protected]）。
• 1.x から引き継がれた変更のない動作：x／y のデフォルト値は 0（null ではありません）です。floatingStyles はバインド可能な位置指定スタイルを返します。1.1.0 以降、オプションには参照値とゲッター（MaybeReadonlyRefOrGetter）を指定できます（dist/floating-ui.vue.d.ts:193-225、dist/floating-ui.vue.mjs:83-84 で確認済み）。

ベストプラクティス

• スクロール、サイズ変更、レイアウト変更の間もフローティング要素をアンカー位置に保つため、whileElementsMounted: autoUpdate を渡します（dist/floating-ui.vue.mjs:146-156；https://floating-ui.com/docs/vue）。
• オプションを渡すために autoUpdate をラップする場合は、必ずクリーンアップ関数を返します（dist/floating-ui.vue.mjs:140-145）：

useFloating(reference, floating, {
  whileElementsMounted(...args) {
    return autoUpdate(...args, {animationFrame: true});
  },
});

• whileElementsMounted を使用する場合は、フローティング要素に v-if を使います。v-show を使う場合は、whileElementsMounted を省略して autoUpdate を手動で管理してください。そうしないと、非表示要素のリスナーがリークします（https://floating-ui.com/docs/vue）。
• open の参照値を渡し、副作用の実行を isPositioned で制御します。位置指定はマイクロタスクで解決されるため、それまでは要素が (0, 0) に配置されます。open が false の間、isPositioned は false のままです（dist/floating-ui.vue.mjs:137、dist/floating-ui.vue.mjs:157-161）：

const {isPositioned} = useFloating(reference, floating, {open});
watch(isPositioned, (positioned) => {
  if (positioned) inputRef.value?.focus();
});

• open、placement、strategy、middleware、transform オプションには、リアクティビティを保つために参照値またはゲッター（() => props.placement）を渡します。これらは flush: 'sync' で監視されます（dist/floating-ui.vue.mjs:162-164）。
• コンポーネントのテンプレート参照を直接渡します。コンポーネントは $el 経由で展開されます。コメントノードを描画するコンポーネントは null に解決され、位置指定は安全に何もしません（dist/floating-ui.vue.mjs:6-15）。
• デフォルトの transform: true を維持し、CSS の transform アニメーションが必要な場合は内側のラッパー要素をアニメーションさせます。外側の位置指定ノードは translate() による位置指定を維持します（https://floating-ui.com/docs/vue）。
• テンプレート参照を使って arrow({element: arrowRef}) を指定します。矢印要素がマウントされるまでは何もせず（{} を返し）、配置には middlewareData.arrow?.x/.y を参照します（dist/floating-ui.vue.mjs:27-34）。

よくあるタスク

• 矢印の位置指定の例とすべてのオプションのデフォルト値：API リファレンス。
• 1.x からのアップグレード、または Vue 2 向けのバージョン固定：移行ガイド。

パッケージのエクスポート

useFloating、arrow に加えて、@floating-ui/dom から再エクスポートされるもの：autoPlacement、autoUpdate、computePosition、detectOverflow、flip、getOverflowAncestors、hide、inline、limitShift、offset、platform、shift、size（dist/floating-ui.vue.mjs:2）。Vue 対応の arrow の動作を維持するため、ミドルウェアは @floating-ui/dom ではなく @floating-ui/vue からインポートしてください。