tiptap/extensions 深度解讀Tiptap 統(tǒng)一工具擴展包的組成、遷移方式與演進脈絡【免費下載鏈接】tiptapThe headless rich text editor framework for web artisans.項目地址: https://gitcode.com/GitHub_Trending/ti/tiptap導讀tiptap/extensions是 Tiptap 倉庫在 v3 時代推出的“聚合型”擴展包它把History撤銷/重做、Placeholder、CharacterCount、DropCursor、GapCursor、TrailingNode、Focus、Selection等八個常用工具擴展收斂到單一包名下幫助開發(fā)者用一次安裝、統(tǒng)一版本號完成以往需要依賴多個獨立包才能實現(xiàn)的能力。本文以該包的 CHANGELOG 為骨架結合 包內源碼 與 舊版獨立包目錄梳理包的組成、逐項遷移路徑、每類擴展的可用選項以及版本演進中值得關注的 bug 修復與性能改造讀者讀完后能直接完成從舊包到新聚合包的遷移并理解各選項在底層 ProseMirror 插件中的真實作用。一、包定位為什么需要tiptap/extensions從 CHANGELOG 的 3.0.1 版本major change提交bfec9b2可以看到這個包的來源說明Adds the newtiptap/extensionspackage which packages multiple utility extensions likeHistory,Placeholder,CharacterCount,DropCursor,GapCursor,TrailingNode,Focus, andSelection.也就是說它是一個聚合包aggregate package既不重復實現(xiàn) Node/Mark 擴展也不引入新的 UI 依賴只是把分散在tiptap/extension-character-count、tiptap/extension-dropcursor、tiptap/extension-gapcursor、tiptap/extension-history、tiptap/extension-placeholder、tiptap/extension-focus等舊獨立包中的能力統(tǒng)一收納。這一點在源碼層面可以直接驗證package.json 中包名為tiptap/extensions倉庫內當前版本為3.30.3與tiptap/core、tiptap/pm的版本嚴格對齊聲明了對tiptap/core、tiptap/pm的 peerDependencies工作區(qū)版本同時提供子路徑導出subpath exports允許按需引入tiptap/extensions/character-count、/drop-cursor、/focus、/gap-cursor、/undo-redo、/placeholder、/selection、/trailing-node便于 tree-shaking 與按需打包。入口文件 的導出完全與包名一一對應export * from ./character-count/index.js export * from ./drop-cursor/index.js export * from ./focus/index.js export * from ./gap-cursor/index.js export * from ./placeholder/index.js export * from ./selection/index.js export * from ./trailing-node/index.js export * from ./undo-redo/index.js說明CHANGELOG 的早期 release3.0.0-next.6將該包描述為 which holds utility extensions隨后的穩(wěn)定版本統(tǒng)一為上述八類擴展。此外同一版本還提到pnpm package aliases用于 monorepo 版本鎖定、以及強制 type imports便于 bundler 在生成 dist/index.js 時剔除純類型導入等工程化改動這些不會影響業(yè)務側 API。從倉庫結構看被替代的舊獨立包被移入 packages-deprecated 目錄extension-character-count、extension-dropcursor、extension-focus、extension-gapcursor、extension-history、extension-placeholder等可以從實現(xiàn)層面印證“遷移到tiptap/extensions”確實是倉庫推薦的演進方向。二、八個聚合擴展逐個拆解2.1 CharacterCount字數(shù)/詞數(shù)統(tǒng)計與硬性限制Changelog 中 CharacterCount 的官方描述為“添加一個光標用于指示拖放時新節(jié)點將插入的位置”但結合 源碼 可以看出該描述明顯是從 DropCursor 條目復制而來changelog 中的筆誤其真實職責是統(tǒng)計文檔字符數(shù)/詞數(shù)并在超出限制時攔截或裁剪輸入同時把計數(shù)能力暴露在storage.characterCount中供 UI 讀取。遷移方式CHANGELOG 原始 diff- import CharacterCount from tiptap/extension-character-count import { CharacterCount } from tiptap/extensions類型導入import { CharacterCount, CharacterCountOptions } from tiptap/extensions;可選配置項來自 character-count.ts 的類型定義與addOptions默認值選項類型默認值作用limitnumber \| nullnull允許的最大字符數(shù)0/null/undefined均表示不限制modetextSize \| nodeSizetextSizetextSize使用node.textBetween(...)的文本內容計算nodeSize使用 ProseMirror 節(jié)點大小計算autoTrimbooleantrue當程序化設置的內容超過限制時是否自動裁剪3.23.4 新增詳見下文textCounter(text: string) number(text) text.length自定義字符計數(shù)函數(shù)如基于Intl.Segmenter統(tǒng)計wordCounter(text: string) number按空格分詞計數(shù)自定義詞數(shù)統(tǒng)計函數(shù)它的核心機制并非簡單“算個數(shù)”而是通過一個 ProseMirror 插件同時控制兩類行為見 filterTransaction 與 appendTransactionfilterTransaction在每次輸入事務到達前校驗新舊字符數(shù)。超過上限的非粘貼事務會被直接攔截返回false對粘貼內容則嘗試刪除超出部分transaction.deleteRange若裁剪后仍超限則整體拒絕appendTransaction在編輯器創(chuàng)建初期檢測初始內容是否已經超限例如setContent注入超長內容超限時發(fā)出console.warn并從文檔開頭刪除多出的字符。開發(fā)者可通過storage.characterCount.characters()/.words()在 UI 上實時展示計數(shù)也可傳入自定義 node 與 mode 按指定范圍計算。2.2 DropCursor拖放時的插入位置指示線官方能力為拖放操作添加一條可視光標指示新節(jié)點將被插入的位置CHANGELOG 原文adds a cursor that indicates where a new node will be inserted when dragging and dropping。該能力底層直接來源于 ProseMirror 的 dropcursor 插件在本聚合包內被包裝成 Tiptap 擴展。遷移原始 diff- import DropCursor from tiptap/extension-dropcursor import { DropCursor } from tiptap/extensionsimport { DropCursor, DropCursorOptions } from tiptap/extensions;2.3 GapCursor空白區(qū)域的占位光標官方能力當點擊文檔中沒有內容的區(qū)域例如兩個塊級節(jié)點之間時出現(xiàn)一個光標讓用戶可以在“縫隙”中定位并開始輸入CHANGELOG 原文a cursor that appears when you click on a place where no content is present, for example in-between nodes。遷移原始 diff- import GapCursor from tiptap/extension-gapcursor import { GapCursor } from tiptap/extensionsimport { GapCursor } from tiptap/extensions;GapCursor 是諸多塊級交互點擊表格/圖片之間的空隙后回車換行的基礎設施通常建議與 DropCursor 一起加入編輯器的extensions數(shù)組。2.4 History / UndoRedo撤銷與重做CHANGELOG 將該條目命名為Historyadds undo and redo functionality to the editor但遷移后的新包入口實際暴露的擴展名是UndoRedo見 undo-redo/index.ts 與 undo-redo.ts其內部包裝的正是 ProseMirror 官方的history插件。在 3.0.0-next.6 的早期描述中還出現(xiàn)過HistoryOptions命名最終穩(wěn)定版統(tǒng)一為UndoRedoOptions引用源碼時建議以UndoRedo為準。遷移原始 diff- import History from tiptap/extension-history import { History } from tiptap/extensionsimport { UndoRedo, UndoRedoOptions } from tiptap/extensions;配置項來自 undo-redo.ts選項類型默認值作用depthnumber100保留的歷史事件數(shù)量超出后丟棄最舊記錄newGroupDelaynumber500兩次變更之間間隔超過該毫秒數(shù)后開啟新的撤銷分組UndoRedo還自動注冊了undo/redo命令與快捷鍵Mod-z撤銷、Shift-Mod-z與Mod-y重做并且額外處理了Mod-я等俄語鍵盤布局見 addKeyboardShortcuts。需要特別留意的是源碼中的兼容性警告undo-redo.ts 注釋如果項目同時使用tiptap/extension-collaboration必須移除undo-redo因為協(xié)作擴展自帶獨立的 Yjs 歷史實現(xiàn)兩者疊加會互相干擾。2.5 Placeholder空狀態(tài)占位提示官方能力當編輯器或某個節(jié)點為空時展示一段占位文本CHANGELOG 原文adds a placeholder text to the editor, which is displayed when the editor is empty。遷移原始 diff- import Placeholder from tiptap/extension-placeholder import { Placeholder } from tiptap/extensionsimport { Placeholder, PlaceholderOptions } from tiptap/extensions;默認選項見 placeholder.ts選項類型默認值作用emptyEditorClassstringis-editor-empty整個編輯器為空時附加到根節(jié)點的 classemptyNodeClassstringis-empty單個空節(jié)點上附加的 class3.25.0 起可傳函數(shù)按節(jié)點返回動態(tài) classdataAttributestring見DEFAULT_DATA_ATTRIBUTE用于承載占位文案的 data 屬性名3.18.0 新增placeholderstring \| ((node) string)Write something …占位文本或按節(jié)點動態(tài)生成的函數(shù)showOnlyWhenEditablebooleantrue編輯器處于只讀/不可編輯時不展示占位符showOnlyCurrentbooleantrue僅當光標位于該空節(jié)點時才展示includeChildrenbooleanfalse是否覆蓋嵌套的空子節(jié)點與早期獨立版本相比穩(wěn)定版的 placeholder 是 CHANGELOG 中修復最密集的模塊其演進詳見第 4 節(jié)建議基于視口增量掃描而非全文檔遍歷的機制在性能上對超大文檔尤其關鍵。2.6 TrailingNode文檔末尾的兜底節(jié)點官方能力始終在文檔結尾保留一個節(jié)點如段落保證用戶把內容刪光后依然有可輸入的位置CHANGELOG 原文adds a node at the end of the editor, which can be used to add a trailing node like a paragraph。import { TrailingNode, TrailingNodeOptions } from tiptap/extensions;配置項見 trailing-node.ts選項類型默認值作用nodestringundefined期望插入的節(jié)點類型名省略時從 schema 頂部節(jié)點類型的defaultType推導最后兜底paragraph3.7.0 起可選notAfterstring \| string[][paragraph]這些節(jié)點之后不再強制插入尾節(jié)點防止無限循環(huán)實現(xiàn)細節(jié)值得注意appendTransaction 與 state.apply通過appendTransaction在每次事務后檢查doc.lastChild類型不符合預期時在doc.content.size位置插入新節(jié)點插件 state 會忽略帶__uniqueIDTransactionmeta 的事務避免與 UniqueID 擴展互相觸發(fā)形成死循環(huán)對應 3.10.5 的修復支持通過事務 metaskipTrailingNode跳過本次插入3.20.5 新增見 skipTrailingNodeMeta 導出例如編程式內容替換時不想自動補尾節(jié)點。2.7 Focus光標所在節(jié)點的聚焦高亮官方能力當編輯器獲得焦點時為光標所在的節(jié)點附加 class便于圍繞“當前編輯位置”做視覺高亮如大綱編輯器中的當前段落描邊。import { Focus, FocusOptions } from tiptap/extensions;配置項見 focus.ts選項類型默認值作用classNamestringhas-focus附加到聚焦節(jié)點的 classmodeall \| deepest \| shallowestallall高亮光標路徑上的所有節(jié)點deepest只高亮最內層節(jié)點shallowest只高亮最外層包含節(jié)點實現(xiàn)上它利用props.decorations當!isEditable || !isFocused時返回空DecorationSet因此只讀狀態(tài)與失焦狀態(tài)下不會產生任何高亮裝飾見 focus.ts。2.8 Selection失焦后的自定義選區(qū)樣式官方能力當編輯器失去焦點時用可自定義 class 的 decoration 代替瀏覽器原生選區(qū)讓“內容被選中”的狀態(tài)在失焦后依然可見CHANGELOG 原文adds a selection state to the editor, which can be used to style the editor when theres a selection。import { Selection, SelectionOptions } from tiptap/extensions;配置項見 selection.tsclassName默認selection作用于選區(qū)內聯(lián)文本的 decoration class。該擴展的行為約束在源碼中有非常清晰的定義selection.ts僅在非空文本選區(qū)、非 node selection、且編輯器可編輯時同步原生選區(qū)shouldSyncDomSelection僅當編輯器失焦且當前沒有拖拽時才渲染.selectiondecorationshouldPreserveSelection避免原生::selection樣式與 decoration 重疊失焦時調用window.getSelection()?.removeAllRanges()清除原生高亮重新聚焦后通過view.focus()恢復——這正是 3.26.0 與 3.27.4 兩次針對“多行選區(qū)高亮溢出、失焦后原生選區(qū)與 decoration 重疊”問題的修復落地方式處于拖拽editor.view.dragging時不保留裝飾對應 CHANGELOG 中ce47182Remove selection decoration when editor is on dragging mode與 minor change52b6644skip decorations for node selection and non editable editor。三、遷移實操從舊獨立包切到聚合包3.1 替換 import 語句官方 diff 匯總以下 diff 均完整摘自 CHANGELOG 3.0.1 的發(fā)布說明可直接套用# CharacterCount - import CharacterCount from tiptap/extension-character-count import { CharacterCount } from tiptap/extensions # DropCursor - import DropCursor from tiptap/extension-dropcursor import { DropCursor } from tiptap/extensions # GapCursor - import GapCursor from tiptap/extension-gapcursor import { GapCursor } from tiptap/extensions # History - import History from tiptap/extension-history import { History } from tiptap/extensions # Placeholder - import Placeholder from tiptap/extension-placeholder import { Placeholder } from tiptap/extensions # Focus - import Focus from tiptap/extension-focus import { Focus } from tiptap/extensionsTrailingNode與Selection在舊獨立生態(tài)中并不存在對應的穩(wěn)定獨立包屬于隨聚合包一起提供的擴展直接引入即可。3.2 安裝與整體示例假設項目使用 pnpm 與 Tiptap v3安裝后即可在Editor中組合使用import { Editor } from tiptap/core import StarterKit from tiptap/starter-kit import { CharacterCount, DropCursor, Focus, GapCursor, Placeholder, Selection, TrailingNode, UndoRedo, } from tiptap/extensions const editor new Editor({ element: document.querySelector(#editor)!, extensions: [ StarterKit, // 依賴 tiptap/pm 的 ProseMirror 官方實現(xiàn) UndoRedo.configure({ depth: 100, newGroupDelay: 500 }), Placeholder.configure({ placeholder: Write something … }), CharacterCount.configure({ limit: 280 }), TrailingNode, Focus.configure({ className: has-focus, mode: all }), Selection.configure({ className: selection }), DropCursor, GapCursor, ], content: pHello Tiptap/p, }) // 讀取實時計數(shù) const count editor.storage.characterCount.characters()對應示例可在 demos/src/Examples/Extensions 目錄下找到獨立可運行的 demo如UndoRedo、Placeholder、CharacterCount、Focus、Selection、TrailingNode等子目錄每個 demo 目錄內包含對應框架的組件源碼與樣式。舊包源碼仍保留在 packages-deprecated便于需要對照實現(xiàn)的場景查閱。四、CHANGELOG 中的關鍵演進從“能用”到“穩(wěn)定”CHANGELOG 的價值不只在于版本號下面這些帶提交號的條目直接反映了聚合包在真實業(yè)務場景下踩過的坑與解法可幫助開發(fā)者理解何時需要升級、升級后行為有何變化。4.1 CharacterCount 的能力補充3.23.457e53c1新增autoTrim選項。默認true會在程序化設置超限內容時自動裁剪設為false后允許內容臨時超過limit由開發(fā)者調用裁剪或僅做校驗告警給“字數(shù)僅提示不攔截”的場景留出余地。4.2 Placeholder 的持續(xù)性能與穩(wěn)定性改造這是 CHANGELOG 中投入最集中的區(qū)域按時間線看是一條清晰的“優(yōu)化-修復-重構”鏈路版本內容解決的核心問題3.23.6937ff2e將全文檔doc.descendants()遍歷替換為“光標快速路徑默認配置 視口受限掃描非默認配置”大文檔 decoration 計算開銷過高3.24.02d05614把視口重算推遲到 rAF、加入 overscan 邊距、節(jié)流滾動更新協(xié)作編輯下的占位符閃爍與滾動時 CPU 占用3.27.12be3fb9當編輯器被遮擋如模態(tài)框打開無法可靠測量時“凍結”視口窗口被遮擋時反復切換data-placeholder導致的閃爍3.27.376a76da用增量StateFieldDecorationSet替換基于視口的 decoration 掃描只對每個事務涉及的頂層節(jié)點重算徹底移除對 DOM 測量posAtCoords、rAF 調度和滾動監(jiān)聽器的依賴協(xié)作/遮擋/高頻編輯多重場景下的閃爍與卡頓此外兩項配置級增強3.18.0a65e55d新增dataAttribute可自定義承載占位文案的 data 屬性名默認值定義于 constants.ts3.25.0MinoremptyNodeClass允許傳入函數(shù)按節(jié)點類型/狀態(tài)返回不同的動態(tài) class。4.3 TrailingNode 的兼容性修復3.7.07cf3ab6node選項變?yōu)榭蛇x解析優(yōu)先級調整為“schema 頂層節(jié)點默認類型 配置的nodeparagraph兜底”修復了自定義頂層默認節(jié)點項目的尾節(jié)點類型錯誤3.11.1eea7190修復 TrailingNode 未按node選項推斷默認節(jié)點類型的問題3.10.59d5aeb1修復 UniqueID 與 TrailingNode 同時啟用時產生的無限事務循環(huán)導致瀏覽器標簽頁凍結的問題源碼中對應忽略__uniqueIDTransactionmeta 事務的判斷3.20.50c2bbfe支持設置skipTrailingNode事務 meta 跳過本次尾部節(jié)點插入。4.4 Selection 的視覺一致性打磨3.6.37024d69改用正確的SelectionOptions類型使配置項獲得準確類型提示3.26.075e8404/3.27.4d2983cd失焦時隱藏原生瀏覽器選區(qū)、聚焦時恢復讓.selectiondecoration 與原生::selection不再重疊多行選區(qū)的顯示更干凈。4.5 工程化與版本同步3.30.x~3.0.x 之間的大量條目為“Updated dependencies [hash] - tiptap/core / tiptap/pm”說明聚合包嚴格跟隨 core/pm 發(fā)布節(jié)奏跨擴展之間沒有隱性版本漂移這正是聚合包相對“各裝各的舊包”的最大工程收益3.0.1 同時收錄了 pnpm 版本別名鎖定、強制 type-only import、beta 與穩(wěn)定版特性同步等倉庫級工程改動。五、總結與升級建議若你正在維護一個同時安裝了tiptap/extension-placeholder、tiptap/extension-character-count等獨立擴展的 Tiptap v3 項目可以直接把 import 替換為tiptap/extensions聚合導出diff 見第 3.1 節(jié)并刪除多余依賴收獲統(tǒng)一版本號與子路徑按需引入的便利如果你曾在大文檔或協(xié)作場景下遇到 placeholder 閃爍建議至少升級到3.27.3增量 StateField 重構需要“字數(shù)提示但不強制”的需求請在3.23.4使用autoTrim: false若同時使用 TrailingNode 與 UniqueID務必使用包含 3.10.5 修復的版本避免無限事務循環(huán)使用協(xié)作功能時請按源碼注釋移除undo-redo。以上全部結論均可在此倉庫內直接核對聚合包入口、各擴展源碼、完整變更記錄 以及 被替代的獨立包源碼。【免費下載鏈接】tiptapThe headless rich text editor framework for web artisans.項目地址: https://gitcode.com/GitHub_Trending/ti/tiptap創(chuàng)作聲明：本文部分內容由AI輔助生成（AIGC），僅供參考