用途:@floating-ui/vue 是 Vue 3 组合式函数,用于锚点定位。useFloating() 计算 x/y 坐标,把浮动元素(tooltip、popover、菜单)放到参考元素旁边。
版本限制:仅支持 Vue >=3.3.0(peer 依赖)。2.0.0 移除了 vue-demi,不再支持 Vue 2 与 Vue <3.3;这些项目需使用 npm install @floating-ui/vue@1。运行时依赖 @floating-ui/dom@^1.8.0 与 @floating-ui/utils@^0.2.12。自 2.0.1 起支持 exactOptionalPropertyTypes 的 TypeScript。
主要能力:默认 placement 为 bottom,默认使用 transform 定位。floatingStyles 返回可直接绑定的定位样式;x/y 默认 0(非 null)。open、placement、strategy、middleware、transform 等选项可传 ref 或 getter 以保持响应式(以 flush: 'sync' 监听)。arrow({element: arrowRef}) 配合模板 ref 使用,箭头元素挂载前返回 {},通过 middlewareData.arrow?.x/.y 读取位置。
使用方式:从 @floating-ui/vue 导入 useFloating、offset、flip、shift、autoUpdate 等;中间件应从 @floating-ui/vue 导入而非 @floating-ui/dom,以保留 Vue 感知的 arrow 行为。建议传 whileElementsMounted: autoUpdate 以在滚动、缩放和布局变化时保持锚定;包装 autoUpdate 传选项时必须返回清理函数。使用 whileElementsMounted 时浮动元素用 v-if;若用 v-show 则跳过 whileElementsMounted 并手动管理 autoUpdate,否则隐藏元素上监听器会泄漏。传 open ref 并以 isPositioned 控制副作用,定位在微任务中完成,此前元素位于 (0,0)。组件模板 ref 可直接传入,组件经 $el 解包,渲染注释节点的组件解析为 null 并安全空操作。
限制:2.0.0 除移除 vue-demi 外无其他破坏性 API 变更,useFloating、arrow 及所有再导出保持 1.1.x 签名。需 CSS transform 动画时保留默认 transform: true,改为动画内层包裹元素。其余细节暂未提供。