Tiptap FloatingMenu 扩展详解tiptap/extension-floating-menu 的选项、定位原理与显隐控制机制【免费下载链接】tiptapThe headless rich text editor framework for web artisans.项目地址: https://gitcode.com/GitHub_Trending/ti/tiptapTiptap 是基于 ProseMirror 的 headless 富文本编辑器框架tiptap/extension-floating-menu是它提供的浮动菜单扩展当编辑器处于特定状态默认是聚焦在空段落上时一个由你自定义的 DOM 菜单会自动出现在光标附近典型场景如 Medium 式编辑器的行内快捷工具条。本文基于当前仓库中该扩展的源码、配置与测试完整讲解它的全部可配置项、Floating UI 集成方式、默认显隐逻辑、命令与事务控制协议以及如何定位和排查常见问题。包概况与安装前提tiptap/extension-floating-menu的包描述为 floating-menu extension for tiptap见 package.json当前仓库中版本为 3.30.3以 MIT 协议开源协议文件见 LICENSE.md官方文档发布在 Tiptap 官网。该包是一个标准 npm 包同时提供 ESMdist/index.js与 CJSdist/index.cjs入口并标记sideEffects: false以利于 tree-shaking。它的对等依赖peerDependencies有三项这意味着安装时需要自行准备依赖版本要求作用tiptap/coreworkspace 对应版本扩展基类Extension、Editor实例tiptap/pmworkspace 对应版本提供 ProseMirror 的Plugin、PluginKey等模型floating-ui/dom^1.0.0菜单的定位引擎computePosition 及各类中间件框架适配层Vue/React封装的菜单组件最终都构建在这个扩展之上demos 中 Vue 版从tiptap/vue-3/menus引入FloatingMenu组件见 demos/src/Extensions/FloatingMenu/Vue/index.vueReact 版从tiptap/react/menus引入见 demos/src/Extensions/FloatingMenu/React/index.jsx二者只是帮你把菜单 DOM 元素绑定到扩展的element选项上。基本用法扩展入口导出FloatingMenu默认导出与命名导出并存见 src/index.ts。核心用法是传入一个包含菜单的 DOM 元素import { Editor } from tiptap/core import { StarterKit } from tiptap/starter-kit import { FloatingMenu } from tiptap/extension-floating-menu new Editor({ extensions: [ StarterKit, FloatingMenu.configure({ element: document.querySelector(#floating-menu), // 你的菜单 DOM 元素 options: { placement: bottom-start, // 传给 Floating UI 的定位选项 offset: 10, }, }), ], })仓库 demos 给出的Medium 式完整示例React 版编辑器聚焦且当前行是空段落时右侧浮出 H1 / H2 / 无序列表按钮点击按钮调用editor.chain().focus().toggleHeading({ level: 1 }).run()等命令并依据isActive状态高亮{editor ( FloatingMenu editor{editor} div classNamefloating-menu button onClick{() editor.chain().focus().toggleHeading({ level: 1 }).run()}H1/button button onClick{() editor.chain().focus().toggleBulletList().run()}Bullet list/button /div /FloatingMenu )} EditorContent editor{editor} /Vue 版本结构相同floating-menu :editoreditor包裹菜单内容见 demos/src/Extensions/FloatingMenu/Vue/index.vue。全部配置项扩展选项类型定义在 src/floating-menu.ts默认值在addOptions()中声明src/floating-menu.ts底层参数接口FloatingMenuPluginProps定义在 src/floating-menu-plugin.ts。完整选项表如下选项类型默认值说明elementHTMLElement \| nullnull包含菜单的 DOM 元素。不传时扩展直接不创建 ProseMirror 插件addProseMirrorPlugins返回空数组这是扩展能否生效的开关options对象Floating UI 选项{}透传给 Floating UI 的定位选项与回调详见下文pluginKeyPluginKey \| stringfloatingMenu插件键用于多实例隔离与事务 meta 协议updateDelaynumber250菜单更新前的延迟毫秒文档注释说明其用途是防止性能问题resizeDelaynumber60窗口 resize / 滚动时更新位置前的防抖延迟毫秒appendToHTMLElement \| (() HTMLElement)undefined菜单挂载的容器元素默认挂载到编辑器的父元素。源码注释说明其存在原因是无障碍、裁剪clipping或 z-index 问题可能需要把菜单挂到其他 DOM 上下文shouldShow(props) boolean内置逻辑见下节决定是否显示菜单的函数入参包含editor、view、state、oldState、from、to选区范围的最小/最大位置其中updateDelay/resizeDelay的默认值 250 与 60 在FloatingMenuView构造函数参数解构中确认src/floating-menu-plugin.tsresizeDelay在resizeHandler中作为防抖定时器使用window.resize与滚动目标的scroll事件共用这一防抖逻辑src/floating-menu-plugin.ts。透传给 Floating UI 的options子选项options字段的类型在 src/floating-menu-plugin.ts 中声明其默认值组合在FloatingMenuView的floatingUIOptions属性中src/floating-menu-plugin.ts子选项类型默认值说明strategyabsolute \| fixedabsolute菜单的 CSS 定位策略placementtop \| right \| bottom \| left及其-start/-end变体共 12 种right菜单相对光标的位置方向offsetFloating UIoffset参数或boolean8与光标的偏移距离flipflip参数或boolean{}空间不足时翻转方向shiftshift参数或boolean{}超出视口时平移避让arrowarrow参数或falsefalse箭头指向sizesize参数或booleanfalse尺寸约束中间件autoPlacementautoPlacement参数或booleanfalse自动选择最优方位hidehide参数或booleanfalse参考元素被隐藏/逃逸时标记菜单inlineinline参数或booleanfalse行内定位中间件onShow/onHide/onUpdate/onDestroy() void无生命周期回调scrollTargetHTMLElement \| Windowwindow监听滚动以触发位置更新的元素一个值得注意的实现细节middlewaresgetter 会把每个非false的中间件选项按序装配进Middleware[]数组flip → shift → offset → arrow → size → autoPlacement → hide → inline布尔值true表示启用该中间件且不带参数对象则原样传入src/floating-menu-plugin.ts。因此把某项设为false即彻底关闭对应中间件设为true或以对象传入则是启用——这与 Floating UI 的 API 语义保持一致。默认显隐逻辑何时出现、何时消失如果你不提供shouldShow扩展使用FloatingMenuView上定义的内置判断src/floating-menu-plugin.ts同时满足以下五个条件才显示菜单编辑器视图持有焦点view.hasFocus()当前选区为空selection.empty即光标而非划选光标所在块位于根层$anchor.depth 1即顶层段落不在嵌套块内部该块是空文本块——isTextblock且非 code 块、无子节点、textContent与通过getText计算的文本内容均为空编辑器处于可编辑状态editor.isEditable。这套默认逻辑正好支撑了 demos 中Medium 式编辑器的体验回车产生空段落按钮组浮现在旁边。仓库的 Playwright 演示测试对此做了双向验证非空节点上菜单不渲染空节点上菜单可见见 demos/src/Extensions/FloatingMenu/index.spec.ts。显隐的事件流在构造函数中建立src/floating-menu-plugin.ts菜单元素自身的mousedown捕获阶段会置位preventHide防止点击菜单按钮导致编辑器失焦而隐藏菜单focus事件通过setTimeout延迟一帧再update确保selection已更新blur事件下若焦点目标仍在菜单内部、或回到编辑器 DOM 本身则保留菜单否则hide()window.resize与scrollTarget的scroll事件都走防抖后的updatePosition编辑器的每次transaction都会被transactionHandler检查是否携带控制该菜单的 meta 消息见下节。显示时show()会把菜单元素追加到appendTo支持延迟求值函数或编辑器父节点设置visibility: visible与opacity: 1并触发onShow隐藏时hide()反向处理并将元素从 DOM 中移除src/floating-menu-plugin.ts。构造函数还会给菜单元素设置tabIndex 0使其可被键盘聚焦这是可访问性上的一个内建细节。命令与事务控制协议扩展对外暴露的命令只有一个updateFloatingMenuPosition它向当前事务写入tr.setMeta(this.options.pluginKey, updatePosition)src/floating-menu.tseditor.commands.updateFloatingMenuPosition()底层更完整的控制通道是事务 meta 协议。transactionHandler会读取tr.getMeta(this.pluginKey)并分派四种消息src/floating-menu-plugin.tsmeta 值效果updatePosition重新计算并应用菜单位置{ type: updateOptions, options }运行时更新updateDelay、resizeDelay、appendTo、shouldShow、options含scrollTarget变化时自动解绑旧监听、绑定新监听hide隐藏菜单show更新位置并显示菜单等价的手动触发写法pluginKey默认floatingMenueditor.view.dispatch(editor.state.tr.setMeta(floatingMenu, updatePosition)) editor.view.dispatch(editor.state.tr.setMeta(floatingMenu, show)) editor.view.dispatch( editor.state.tr.setMeta(floatingMenu, { type: updateOptions, options: { resizeDelay: 120 } }), )updateOptions的实现src/floating-menu-plugin.ts值得注意scrollTarget变更时会先把resizeHandler从旧目标上移除、再绑定到新目标避免了滚动监听泄漏到错误的元素上。多实例隔离依赖pluginKey。单元测试专门验证了交叉污染防护同一编辑器挂两个不同pluginKey的菜单视图时向floatingMenu1发 meta 只会触发视图 1 的updateOptions/updatePosition/show/hide视图 2 不受影响字符串键与PluginKey实例键均被覆盖且命令updateFloatingMenuPosition会写入自定义键而非默认的floatingMenu见tests/floating-menu-plugin.spec.ts。如果你的页面同时存在两个浮动菜单例如主菜单加辅助工具条务必为每个实例配置不同的pluginKey。位置计算与销毁安全updatePosition()的定位流程src/floating-menu-plugin.ts先检查this.view.dom.parentNode是否存在编辑器视图已脱离 DOM 时直接返回——这是一条针对销毁竞态的防护若编辑器在被防抖的 resize/scroll 回调触发前销毁ProseMirror 会置空docView无防护时posToDOMRect - coordsAtPos会抛出 Cannot read properties of null 错误。专门的测试用例验证了该防护tests/floating-menu-plugin.spec.ts 中 FloatingMenuView destroy safety 组用posToDOMRect(view, selection.from, selection.to)从 ProseMirror 位置换算出光标的 DOM 矩形包装成一个虚拟参考元素提供getBoundingClientRect/getClientRects调用 Floating UI 的computePosition计算坐标异步结果中若hide中间件报告参考元素隐藏或逃逸referenceHidden/escaped则把菜单设为visibility: hidden否则写入left/top/position/width: max-content并在可见状态下触发onUpdate回调。清理方面destroy()会先hide()再逐一移除菜单元素的mousedown监听、window的resize监听、scrollTarget的scroll监听以及编辑器上的focus/blur/transaction订阅最后触发onDestroy回调src/floating-menu-plugin.ts。框架组件React/Vue 的FloatingMenu在编辑器销毁时依赖这条路径完成回收。插件本体由FloatingMenuPlugin工厂函数构造把字符串pluginKey包装为PluginKey实例并在view钩子里实例化FloatingMenuViewsrc/floating-menu-plugin.ts。FloatingMenuView同时导出可供测试或高级场景直接构造单元测试中即直接new FloatingMenuView({...})。测试与行为验证入口该扩展有两层可查证的行为依据单元测试tests/floating-menu-plugin.spec.ts覆盖多pluginKey实例的命令隔离、updateOptions跨实例污染防护、默认键的向后兼容以及销毁后updatePosition不再触碰已拆除的编辑器视图演示层 E2Edemos/src/Extensions/FloatingMenu/index.spec.ts基于 Playwright 断言非空段落不显示菜单、空段落显示菜单的默认shouldShow行为。小结与适用前提tiptap/extension-floating-menu的设计边界很清晰它只管一个你提供的 DOM 元素在光标附近按规则显隐与定位菜单内容、按钮行为完全由你自己实现定位能力全部委托给floating-ui/dompeer 依赖^1.0.0因此 placement、flip、shift 等能力等同于 Floating UI 的中间件能力。使用时需要记住三点element为必填开关多实例必须区分pluginKeyappendTo与scrollTarget分别解决菜单挂载上下文和滚动跟随两类容器化场景。以上内容均以当前仓库包版本 3.30.3的源码与测试为准若仓库升级请以对应版本源码复核默认值与 meta 协议。【免费下载链接】tiptapThe headless rich text editor framework for web artisans.项目地址: https://gitcode.com/GitHub_Trending/ti/tiptap创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考