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）。
• 支持 TypeScript 的 exactOptionalPropertyTypes：自 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 变更

• BREAKING（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]）。
• FIX（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 起，选项支持 refs 和 getter（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 ref，并通过 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 选项传入 refs 或 getter（() => props.placement），以实现响应式；这些选项会以 flush: 'sync' 方式监听（dist/floating-ui.vue.mjs:162-164）。
• 直接传入组件模板 refs。组件会通过 $el 解包；渲染注释节点的组件会解析为 null，定位操作会安全地跳过（dist/floating-ui.vue.mjs:6-15）。
• 保留默认的 transform: true；如果需要 CSS transform 动画，请为内层包装元素添加动画，这样外层定位节点会继续使用 translate() 定位（https://floating-ui.com/docs/vue）。
• 使用模板 ref 调用 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）。请从 @floating-ui/vue 而非 @floating-ui/dom 导入中间件，以保留适配 Vue 的 arrow 行为。