floating-ui/vue 版本演进解析从 Vue 2 兼容时代到 Vue 3 原生响应式的升级指南【免费下载链接】floating-uiA JavaScript library to position floating elements and create interactions for them.项目地址: https://gitcode.com/GitHub_Trending/fl/floating-ui本文以floating-ui/vueFloating UI 的 Vue 官方封装包的 CHANGELOG.md 为主线梳理该包从 1.0.3 到 2.0.0 的全部版本变更并结合仓库源码逐一解释每个变更背后的实现细节。读完本文你将掌握2.0.0 破坏性变更的影响范围与迁移路径、MaybeReadonlyRefOrGetter响应式 API 的正确用法、isPositioned与open状态的联动机制以及组件实例ComponentPublicInstance作为 ref 时的边界处理逻辑。版本总览一次主版本跃迁与十余次补丁迭代floating-ui/vue是 Vue 生态中用于定位浮动元素tooltip、popover、dropdown 等的核心库底层定位算法由floating-ui/dom提供。其 CHANGELOG 记录了一条清晰的技术演进路线版本类型核心变更2.0.0Major移除vue-demi依赖终止对 Vue 2 及 Vue 3.3.0 的支持1.1.11Patch依赖升级floating-ui/dom1.7.6、floating-ui/utils0.2.111.1.5Patch修复useFloating在open为false时错误地将isPositioned置为true1.1.0MinoruseFloating支持MaybeReadonlyRefOrGetter类型参数1.0.4Patch重写isComponentPublicInstance的实现1.0.3Patch导出.d.mts类型文件组件类型 ref 渲染为空时不再抛错从依赖关系看见 packages/vue/package.json该包始终以floating-ui/dom与floating-ui/utils为运行时依赖并通过workspace:^与仓库内其他包保持同步发布这也是 1.1.x 阶段密集出现Update dependencies补丁的原因——底层 DOM 包每有一次修复Vue 封装层都会跟随发版。2.0.0 破坏性变更告别 vue-demi全面转向 Vue 3 原生响应式变更内容与动机2.0.0 是 CHANGELOG 中唯一的 Major 版本其变更说明非常明确breaking: drop the abandoned and soon-to-be-deprecatedvue-demipackage见 packages/vue/CHANGELOG.mdending support for Vue 2 and Vue 3.3.0vue-demi曾是一个桥接库让同一份代码能同时运行在 Vue 2 与 Vue 3 之上。但由于该包已被原作者弃用CHANGELOG 中注明了来自 vueuse/vue-demi 的 Deprecation Warning继续依赖它意味着长期的兼容性风险。移除vue-demi后floating-ui/vue的代码可以不再为 Vue 2 保留双份 API 分支彻底拥抱 Vue 3 的原生响应式体系。源码层面的印证peerDependencies中vue: 3.3.0的约束见 packages/vue/package.json是这一变更最直接的落地证据。3.3.0 这个版本门槛并非随意选择——Vue 3.3 引入了全局可用的toValueAPI而useFloating的实现正建立在它之上。在 useFloating.ts 中所有选项参数都通过toValue统一解包const openOption computed(() toValue(options.open) ?? true); const middlewareOption computed(() toValue(options.middleware)); const placementOption computed(() toValue(options.placement) ?? bottom); const strategyOption computed(() toValue(options.strategy) ?? absolute); const transformOption computed(() toValue(options.transform) ?? true);toValue是 Vue 3.3 提供的解包函数能同时处理普通值、ref、getter 函数三种形态这正是 1.1.0 引入MaybeReadonlyRefOrGetter类型的基础。vue-demi时代则必须自行判断isRef再手动.value两套逻辑的代码复杂度差别明显。迁移建议从 1.x 升级到 2.0.0 需要满足两个前置条件项目必须运行在Vue 3.3.0之上若项目仍基于 Vue 2 或更早的 Vue 3 版本应停留在 1.1.x 分支并关注 Vue 版本的升级计划。除此之外useFloating的公开 API参数与返回值在 2.0.0 中没有额外变更迁移成本主要集中在运行时环境而非代码改写。响应式 API 进化MaybeReadonlyRefOrGetter1.1.0 / 1.1.1类型定义1.1.0 为useFloating的选项参数引入了一种更灵活的类型。其定义位于 types.tsexport type MaybeReadonlyRefT T | ReadonlyRefT; export type MaybeReadonlyRefOrGetterT MaybeReadonlyRefT | (() T);这意味着placement、strategy、middleware、open、transform等选项现在支持三种传参形态普通值placement: bottom只读 refplacement: toRef(props, placement)getter 函数placement: () props.placement。1.1.1 的补丁fix: ensure MaybeReadonlyRefOrGetter works in earlier versions of Vue则是对该类型在更早 Vue 3 版本下 TypeScript 类型推导兼容性的修正说明这一能力在设计之初就考虑了vue-demi尚未移除时的跨版本可用性。底层解包逻辑MaybeReadonlyRefOrGetter之所以能成立完全依赖toValue的三态解包能力见 useFloating.ts。被解包后的值会被包装成computed并通过watch订阅变化watch([middlewareOption, placementOption, strategyOption, openOption], update, { flush: sync, });flush: sync保证选项变化后立即触发重定位而不是等待下一个 tick——对于 Tooltip 这类对出现时机敏感的场景这一细节直接影响交互手感。实测验证仓库测试packages/vue/test/index.test.ts为 getter 形态提供了完整的验证用例updates floating coords when placement is a getter functionL144-L177placement: () props.placementprops 从bottom改为right后坐标断言从(0, 5)变为(5, 0)updates floating coords when middleware is a getter functionL179-L209middleware: () props.middleware变化后y 坐标从 0 变为 10updates floating position when strategy is a getter functionL211-L238resets isPositioned on open change and open is a getter functionL298-L325。同时也有回退默认值的用例placement变为undefined时回退到bottomL362-L389strategy变为undefined时回退到absoluteL391-L418——这与源码中?? bottom/?? absolute的默认值处理完全一致。行为修复isPositioned与open状态的正确联动1.1.5修复动机1.1.5 的补丁说明为fix(useFloating): avoid settingisPositionedto true whenopenis falseisPositioned用于告知消费者浮动元素是否已经完成定位是入场动画如淡入、位移的常见触发条件。旧实现存在一个场景缺陷浮动元素在关闭状态如退出动画期间仍保持挂载此时若因布局变化触发重算isPositioned会被错误置为true导致下一次打开时入场动画状态异常。修复实现源码 useFloating.ts 的注释完整记录了这一修复的意图/** * The floating elements position may be recomputed while its closed * but still mounted (such as when transitioning out). To ensure * isPositioned will be false initially on the next open, avoid * setting it to true when open false (must be specified). */ isPositioned.value open ! false;同时reset函数保证关闭时主动复位function reset() { if (!openOption.value) { isPositioned.value false; } }并通过watch(openOption, reset, {flush: sync})在open变化时同步执行。测试覆盖测试文件中有三个用例直接验证该行为packages/vue/test/index.test.tsupdates isPositioned on open changeL240-L267open从false切到true时isPositioned从false变为trueresets isPositioned on open changeL269-L296open从true切到false时复位为falsedoes not set isPositioned to true when open is falseL327-L360即使strategy从absolute变为fixed触发了重定位只要open为falseisPositioned始终保持false。组件实例处理isComponentPublicInstance与空渲染保护1.0.3 / 1.0.4为什么需要 unwrapVue 中模板 ref 指向的可能是真实 DOM 元素也可能是组件实例ComponentPublicInstance。floating-ui/dom的computePosition只接受 DOM 元素或虚拟元素因此floating-ui/vue必须先把组件实例解包为真实的$el。这一职责由 unwrapElement.ts 承担function isComponentPublicInstance( target: unknown, ): target is ComponentPublicInstance { return target ! null typeof target object $el in target; } export function unwrapElementT(target: MaybeElementT) { if (isComponentPublicInstance(target)) { const element target.$el as ExcludeMaybeElementT, ComponentPublicInstance; return isNode(element) getNodeName(element) #comment ? null : element; } return target as ExcludeMaybeElementT, ComponentPublicInstance; }1.0.4 的fix: change isComponentPublicInstance implementation正是改进了这里的判断方式。旧实现可能依赖instanceof或框架内部属性新实现使用$el in target的结构化探测对跨包、跨构建场景更稳健。而unwrapElement中对#comment节点的特殊处理则对应 1.0.3 的修复do not throw when component type reference or floating renders nothing——组件render返回null时Vue 会在$el位置插入注释节点若直接把它当作定位元素传给 DOM 层必然出错这里将其规范化为null从而静默跳过定位。测试覆盖packages/vue/test/index.test.ts 用一组用例完整覆盖了组件 ref 的边界场景allows to use with component type referenceL742-L767与allows to use with component type floatingL769-L794组件作为引用元素/浮动元素均可正常定位does not throw when component type reference renders nothingL796-L816与对应 floating 用例L818-L838render() { return null; }时不再抛错does not throw when ... $el is nullL840-L888即使通过expose显式暴露$el: null也保持静默。类型与发布工程改进.d.mts与副作用标记1.0.31.0.3 的另一项变更是chore: exports .d.mts types。从 packages/vue/package.json 可以看到当前完整的 exports 映射exports: { ./package.json: ./package.json, .: { import: { types: ./dist/floating-ui.vue.d.mts, default: ./dist/floating-ui.vue.mjs }, types: ./dist/floating-ui.vue.d.ts, module: ./dist/floating-ui.vue.esm.js, default: ./dist/floating-ui.vue.umd.js } }ESM 导入路径单独提供.d.mts类型声明配合sideEffects: false见 packages/vue/package.json确保在支持 tree-shaking 的打包器中未使用的导出可以被安全摇除。构建产物通过rollup.config.mjs产出 UMD、ESM 与 mjs 三种格式覆盖 CDN 直接引入、打包器 ESM 导入等不同使用场景。依赖升级节奏1.1.2 至 1.1.11 的密集补丁从 1.1.2 到 1.1.11floating-ui/vue连续发布了 10 个 Patch 版本绝大多数变更都是跟随底层依赖发版版本依赖升级1.1.11floating-ui/dom1.7.6、floating-ui/utils0.2.111.1.10floating-ui/dom1.7.51.1.9floating-ui/dom1.7.41.1.8floating-ui/dom1.7.31.1.7floating-ui/utils0.2.10、floating-ui/dom1.7.21.1.6floating-ui/utils0.2.91.1.5floating-ui/utils0.2.8另有 isPositioned 修复1.1.4floating-ui/utils0.2.71.1.3floating-ui/utils0.2.61.1.2floating-ui/utils0.2.51.1.1修复MaybeReadonlyRefOrGetter在更早 Vue 版本的兼容性这种跟随发版模式源于 packages/vue/package.json 中的 workspace 依赖声明floating-ui/dom与floating-ui/utils均以workspace:^引用仓库内任一底层包的修复都会同步到 Vue 封装层。对使用者而言这意味着升级floating-ui/vue的补丁版本即可自动获得 DOM 定位引擎的所有修复无需手动锁定底层包的版本。升级决策速查综合 CHANGELOG 与源码可以给出如下版本决策参考Vue 3.3.0 的新项目直接使用2.0.0享受无vue-demi的纯净 Vue 3 原生实现仍停留在 Vue 2 / Vue 3 3.3.0 的项目锁定1.1.x最新补丁版本此时 1.1.0 的MaybeReadonlyRefOrGetter、1.1.5 的isPositioned修复、1.0.3/1.0.4 的组件实例处理均已可用正在使用1.0.x的项目至少升级到 1.1.x以获得 getter 形态的响应式选项、isPositioned关闭态修复以及更完善的组件 ref 边界处理所有版本useFloating的调用方式保持一致——传入reference、floating两个模板 ref 与选项对象接收x、y、placement、strategy、middlewareData、isPositioned、floatingStyles与update见 types.ts2.0.0 未改变这些公开契约。如需进一步查看实现细节可深入阅读 useFloating.ts定位核心、types.ts全部公开类型、unwrapElement.ts组件实例解包、arrow.ts箭头中间件封装以及 test/index.test.ts全部行为验证用例。【免费下载链接】floating-uiA JavaScript library to position floating elements and create interactions for them.项目地址: https://gitcode.com/GitHub_Trending/fl/floating-ui创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考