3行代码给Tiptap装上手柄拖拽排序还能这样玩【免费下载链接】tiptapThe headless rich text editor framework for web artisans.项目地址: https://gitcode.com/GitHub_Trending/ti/tiptapTiptap 的 DragHandle 扩展把编辑器里每一个块级元素都变成可抓取的对象光标扫到哪个段落或列表它就在旁边浮出一个拖拽手柄按住一甩就能改变顺序。这篇指南按装好就能看 → 调行为 → 排嵌套 → 查故障四段展开装完即用的部分只需要三行代码。三十秒看到手柄出现 结论装一个基座包加一个框架包把手柄组件挂进模板全程不到一分钟。npm install tiptap/extension-drag-handle tiptap/extension-drag-handle-vue-3Vue 3 项目里这样接入React 把最后一行换成tiptap/extension-drag-handle-react的同名组件即可template drag-handle :editoreditor div classmy-handle / /drag-handle editor-content :editoreditor / /template script setup import { Editor, EditorContent } from tiptap/vue-3 import StarterKit from tiptap/starter-kit import { DragHandle } from tiptap/extension-drag-handle-vue-3 const doc h1第一章/h1p拖我试试/pp第二块内容/p const editor new Editor({ content: doc, extensions: [StarterKit], }) /script光标移进任意一行左侧就会浮出一个小圆点按住往上拖段落就跟着换位置了。手柄的 DOM 由render()产出、位置由 floating-ui 计算这段逻辑全部封装在 drag-handle.ts 里平时你不用碰它。手柄长什么样、停在哪三个旋钮结论外观、位置、锁死开关分别对应render、computePositionConfig、locked三个选项各管一摊。想换图标或加背景色重写render()返回自己的元素就行——官方 demo 里用 CSS::after画了一个 ⠿ 点阵代码可参考 DragHandle 的 Vue 演示手柄默认贴在元素左侧顶部placement: left-start。做从右往左读RTL的编辑器时把它改成right-start不然手柄会挤到文字上临时冻结整个拖拽功能把locked设成true或者走命令式下一节细说。顺手埋两个钩子方便埋点和保存onNodeChange在光标掠过不同块时告诉你当前悬停的节点onElementDragStart/onElementDragEnd在甩动开始和落定时各回调一次。所有选项的完整签名见 options.ts。列表、引用里的嵌套块怎么抓 结论嵌套拖拽由nested开关控制抓哪一层由一套打分规则决定你只需要在冲突时补一条规则。DragHandle.configure({ nested: { allowedContainers: [bulletList, orderedList, blockquote], edgeDetection: left, }, })默认只抓顶层块nested打开后任何深度的块都能拖。规则系统的工作方式是每个候选节点先拿 1000 分底分再依次被列表包装层降权、表格结构排除这类内置规则扣分最后分数最高者胜出想排除某些节点就写一条返回 1000 的自定义rules。一个很实用的细节是edgeDetection光标贴近块左边缘时深层子节点会被多扣strength × 深度的分于是外层列表更容易被抓到——贴近边缘抓父级居中抓子级。这套打分的完整参数阈值、强度、可用边缘都注释在 options.ts直接读注释就能配。手柄不见了四个高频问题对号入座 结论九成故障出在装了基座包却忘了装框架包或扩展没进extensions数组。手柄完全不出现→ 先确认框架组件已安装且editor实例非空纯 JS 场景则检查DragHandle是否真的加进了extensions。入口文件是 index.ts导出即基座包本身拖完位置错乱、手柄漂移→ 手柄定位走 floating-ui调整computePositionConfig的placementRTL 布局记得换成右侧React 里组件报 undefined→ 你多半import了基座包换成tiptap/extension-drag-handle-react的同名组件拖长文档时拖影卡顿→ 拖拽图片默认会复制全部计算样式用dragImageProperties只保留color、background-color等少数属性即可提速。进阶两招命令式锁与性能微调结论lockDragHandle三兄弟适合做编辑/预览切换dragImageProperties适合大文档降负载。editor.commands.toggleDragHandle() // 锁定与解锁来回切这三个命令lockDragHandle、unlockDragHandle、toggleDragHandle内部就是翻转locked选项并广播 meta 事件挂在只读预览按钮上最顺手。再往后的探索方向给协作场景叠加extension-collaboration或阅读 drag-handle-plugin.ts 看拖拽状态机如何与 ProseMirror 事务对接。上线前过一遍这份清单tiptap/extension-drag-handle与对应框架包-vue-3/-vue-2/-react版本一致手柄组件与EditorContent在同一个组件模板里且editor已就绪RTL 页面已把placement翻到右侧需要嵌套拖拽时显式配置了allowedContainers避免乱抓onElementDragEnd里接了保存逻辑拖完的位置不会丢。【免费下载链接】tiptapThe headless rich text editor framework for web artisans.项目地址: https://gitcode.com/GitHub_Trending/ti/tiptap创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考