簡介這是一份面向前端開發(fā)者的頁面文字批注功能示例包演示了通過jQuery實現(xiàn)選中文本后添加背景色、實時編輯與刪除批注的完整交互機(jī)制適合需要為網(wǎng)頁引入輕量級批注或評論功能的項目參考。包內(nèi)含10個文件以JavaScript、CSS和HTML為主輔以圖片與數(shù)據(jù)庫文件整體僅80KB結(jié)構(gòu)精簡便于直接閱讀與復(fù)用。其中JavaScript文件承擔(dān)DOM操作、選區(qū)監(jiān)聽、批注邏輯與事件綁定CSS負(fù)責(zé)高亮樣式與界面外觀HTML為可直接運行的演示頁面數(shù)據(jù)庫文件則可用于存儲批注數(shù)據(jù)。通過學(xué)習(xí)示例可以掌握選區(qū)監(jiān)聽、動態(tài)創(chuàng)建批注節(jié)點、自定義高亮顏色、刪除及持久化保存等關(guān)鍵技術(shù)點也可進(jìn)一步擴(kuò)展為富文本編輯或多人協(xié)作批注方案。已有1220人學(xué)習(xí)下載適合進(jìn)階前端開發(fā)者快速上手。 拿到“前端頁面添加文字批注.rar”這個壓縮包時我第一反應(yīng)不是急著解壓找源碼而是先把這個需求在腦子里過了一遍網(wǎng)頁上的文字批注說白了就是讓用戶能像在 PDF 或紙質(zhì)文檔上一樣選中一段文字、貼上一條便利貼。這個功能在在線文檔、內(nèi)容審閱、知識庫、AI 閱讀工具里幾乎成了標(biāo)配但真正自己動手實現(xiàn)過的人并不多。前端文字批注這件事難點不在“彈個輸入框?qū)懢湓挕倍凇坝脩暨x中的那一段文字怎么在頁面里被穩(wěn)定地記住、精確地標(biāo)出來、可靠地存下來”。這篇文章我打算把整個實現(xiàn)鏈路拆開講清楚覆蓋瀏覽器選區(qū) API、錨點序列化、高亮渲染、持久化協(xié)同這幾個核心環(huán)節(jié)適合正在做文檔類產(chǎn)品、知識庫、或者想往富文本領(lǐng)域深入的前端同學(xué)參考。1. 批注功能拆解先想清楚要做哪幾件事1.1 一個批注從產(chǎn)生到消失的完整生命周期很多人一上來就寫代碼結(jié)果做到一半發(fā)現(xiàn)邊界情況根本收不住。我習(xí)慣先把功能鏈路畫出來用戶用鼠標(biāo)劃選一段文字瀏覽器彈出一個小工具條點“添加批注”輸入內(nèi)容后保存。此時頁面上這段文字出現(xiàn)高亮背景頁面右側(cè)或底部出現(xiàn)一條批注記錄。之后用戶可以點擊高亮區(qū)域查看批注詳情、在側(cè)邊欄刪除或回復(fù)批注最后整個批注列表要能持久化到后端下次打開頁面還能原樣恢復(fù)。這條鏈路拆開就是五件事選區(qū)獲取、錨點記錄、高亮渲染、交互管理、數(shù)據(jù)存儲。每一件事都有各自的坑。選區(qū)獲取要用 Selection API錨點記錄要想辦法把“用戶選中了哪幾個字符”轉(zhuǎn)成可序列化的數(shù)據(jù)高亮渲染要保證標(biāo)記不破壞原文結(jié)構(gòu)交互管理要處理滾動定位、懸浮卡片、側(cè)邊欄聯(lián)動存儲則要設(shè)計一個經(jīng)得起文本變更和多人編輯考驗的數(shù)據(jù)模型。1.2 技術(shù)難點其實集中在兩個核心問題上整條鏈路里真正的難點不是 UI而是“文字定位”這件事。第一個問題是用戶選中的文字怎么變成一份可靠的、可長期保存的數(shù)據(jù)瀏覽器里 Range 對象本身不能直接 JSON.stringify它記錄的是 DOM 節(jié)點的引用和偏移量頁面一刷新就沒了。第二問題是數(shù)據(jù)存下來之后下次頁面渲染時怎么準(zhǔn)確找回那一段文字并重新標(biāo)亮文檔內(nèi)容不是靜態(tài)的可能用戶自己改了標(biāo)題、后臺更新了正文、折疊面板展開了新內(nèi)容原先的偏移量早就錯位了。這兩個問題不解決其他功能做得再花哨也是空中樓閣。所以我做這個項目時先把百分之六十的精力砸在了“錨點”上UI 反而是后面順手補(bǔ)的。1.3 為什么建議自己實現(xiàn)而不是直接引第三方庫市面上確實有 annotator.js、hypothesis 這類開源方案但實際集成過你就會發(fā)現(xiàn)它們要么年久失修、對現(xiàn)代框架支持差要么太重、連后端存儲方案都給你規(guī)定死了。對于“產(chǎn)品里需要一個輕量批注能力”這種需求自己實現(xiàn)一個兩百行左右的核心模塊反而是維護(hù)成本最低的選擇。自己實現(xiàn)也方便后續(xù)擴(kuò)展——比如批注狀態(tài)流轉(zhuǎn)、多人顏色區(qū)分、回復(fù)線程這些業(yè)務(wù)需求第三方庫很難百分之百貼合。當(dāng)然自研的前提是先把 Range 和錨點這兩個基礎(chǔ)概念吃透下面我按順序講。2. 瀏覽器選區(qū)文字批注的起點2.1 Selection 和 Range 到底怎么用用戶劃選文字時瀏覽器會維護(hù)一個 Selection 對象通過window.getSelection()可以拿到。它內(nèi)部包含若干個 Range一般我們只取第一個selection.getRangeAt(0)。Range 記錄了選區(qū)的起點和終點每個端點由兩部分組成container和offset。container 可能是元素節(jié)點也可能是文本節(jié)點offset 表示在該節(jié)點內(nèi)的偏移位置。比如你選中了“今天天氣不錯”這句話里的“天氣”兩個字如果這句話整體在一個文本節(jié)點里那 startContainer 就是這個文本節(jié)點startOffset 為 2endOffset 為 4。但 DOM 不會永遠(yuǎn)這么規(guī)整。網(wǎng)頁里一段文字往往被span、a、strong等標(biāo)簽拆成多個文本節(jié)點用戶可能從p里的第二個 span 劃到另一個p里的第一個 span這時 startContainer 和 endContainer 就不是同一個節(jié)點了。Range 能夠正確表達(dá)這種跨節(jié)點選區(qū)這給我們的定位方案提供了基礎(chǔ)。2.2 把 Range 轉(zhuǎn)成可以長期存儲的數(shù)據(jù)結(jié)構(gòu)獲取到 Range 之后再處理就簡單了目標(biāo)是把“活的 DOM 引用”變成“死的 JSON 數(shù)據(jù)”。我的做法是給每個端點記錄一條從根節(jié)點到目標(biāo)節(jié)點的完整路徑路徑用childNodes的下標(biāo)數(shù)組表示再加上節(jié)點內(nèi)的 offset。直接看代碼更直觀function serializePoint(container, offset, root) { const path []; let node container; while (node node ! root) { const parent node.parentNode; if (!parent) break; const index Array.prototype.indexOf.call(parent.childNodes, node); path.unshift(index); node parent; } return { path, offset }; } function serializeRange(range, root) { return { start: serializePoint(range.startContainer, range.startOffset, root), end: serializePoint(range.endContainer, range.endOffset, root), quote: range.toString().slice(0, 200), // 截取原文作為校驗依據(jù) }; }這里存quote選中的原文片段是很多人會忽略的關(guān)鍵一步。路徑加偏移只能解決“定位到節(jié)點”但無法驗證定位結(jié)果是不是用戶原本選中的內(nèi)容。有了 quote恢復(fù)錨點之后可以把實際取到的文本和 quote 對比能對上就說明定位準(zhǔn)確對不上說明文檔變了需要走修正或兜底邏輯。這個思路后面會展開。2.3 第一個坑為什么不能直接存 startOffset 和 endOffset我見過不少初版實現(xiàn)直接把range.startOffset和range.endOffset作為 JSON 存到后端刷新頁面后用全局搜索文本再定位。這在靜態(tài)頁面上勉強(qiáng)能跑但只要文檔內(nèi)容有任何變化就全線崩潰。舉個例子原文是“今天天氣不錯”用戶選中“天氣”存下來的信息是 startOffset2、endOffset4。第二天編輯在“今天”后面加了一個“的”字文本變成“今天的天氣不錯”。此時再用偏移量去切切出來的就不是“天氣”而是“的天”了。更麻煩的是如果目標(biāo)文本節(jié)點被改寫了整個定位索引直接失效批注就丟了。所以偏移量只能作為“節(jié)點內(nèi)部的定位”不能作為“全文范圍的定位”。真正要解決的是在文本增刪后怎么讓批注依然指向用戶原本想指的那段話。這就是錨點穩(wěn)定化要做的事。3. 錨點穩(wěn)定化解決“批注漂移”和“定位失敗”3.1 主流的錨點方案橫向?qū)Ρ任以谡{(diào)研階段對比過四種主流方案各自優(yōu)缺點很明顯方案原理優(yōu)點缺點字符串索引記錄原文中的絕對字符位置實現(xiàn)最簡單文本一改動全部失效文本片段匹配記錄 quote恢復(fù)時全文搜索無需路徑實現(xiàn)直觀相同文本多處出現(xiàn)時無法精確匹配性能差DOM path offset記錄節(jié)點路徑和偏移量定位精確不受同名文本干擾路徑依賴 DOM 結(jié)構(gòu)結(jié)構(gòu)變化時失效包裹節(jié)點標(biāo)記選中時直接包一個 mark 標(biāo)簽恢復(fù)容易天然高亮污染 DOM 結(jié)構(gòu)影響復(fù)制、編輯和重構(gòu)實際項目里我推薦用DOM path offset 為主quote 校驗為輔的組合方案。單個方案都有明顯短板但組合起來可以互相兜底。path 負(fù)責(zé)精確找到節(jié)點offset 負(fù)責(zé)定位節(jié)點內(nèi)位置quote 負(fù)責(zé)校驗結(jié)果并觸發(fā)修正。3.2 DOM path 文本校驗的實踐細(xì)節(jié)恢復(fù)錨點的代碼邏輯是這樣的function resolveNodeByPath(path, root) { let node root; for (const index of path) { if (!node || !node.childNodes) return null; node node.childNodes[index]; } return node; } function restoreRange(annotation, root) { const startNode resolveNodeByPath(annotation.start.path, root); const endNode resolveNodeByPath(annotation.end.path, root); if (!startNode || !endNode) return null; let startText startNode.textContent || ; let endText endNode.textContent || ; let startOffset annotation.start.offset; let endOffset annotation.end.offset; // 用 quote 校驗發(fā)現(xiàn)偏移漂移時自動修正 const actual (startNode endNode ? startText.slice(startOffset, endOffset) : startText.slice(startOffset) endText.slice(0, endOffset)); if (actual ! annotation.quote) { const newStart startText.indexOf(annotation.quote); if (newStart ! -1) { startOffset newStart; endOffset newStart annotation.quote.length; } else { return null; // 實在找不到走兜底邏輯 } } const range document.createRange(); range.setStart(startNode, startOffset); range.setEnd(endNode, endOffset); return range; }這里有個經(jīng)驗校驗時優(yōu)先用indexOf在當(dāng)前節(jié)點內(nèi)搜索 quote搜不到再考慮跨節(jié)點情況。因為大多數(shù)批注都是選中一小段連續(xù)文本改動后節(jié)點可能沒變、只是偏移變了indexOf一次就能修正過來。如果indexOf也找不到說明文檔改動較大最穩(wěn)妥的做法是把批注標(biāo)記為“位置已失效”而不是靜默丟失或亂定位。用戶看到“這條批注引用的內(nèi)容已不存在”比看到批注掛在毫不相關(guān)的句子上好接受得多。3.3 MutationObserver 監(jiān)聽動態(tài)內(nèi)容重新掛載標(biāo)記文檔型頁面經(jīng)常有異步內(nèi)容評論加載、折疊面板展開、標(biāo)簽頁切換都會改變 DOM 結(jié)構(gòu)。批注的高亮標(biāo)記是運行時包上去的 span一旦內(nèi)容重新渲染標(biāo)記就丟了。解決方案是監(jiān)聽容器內(nèi)的 DOM 變化let reapplyTimer null; const observer new MutationObserver((mutations) { const relevant mutations.some((m) m.target.isConnected m.target.closest(.doc-content) ); if (!relevant) return; clearTimeout(reapplyTimer); reapplyTimer setTimeout(() reapplyAnnotations(), 200); }); observer.observe(document.querySelector(.doc-content), { childList: true, subtree: true, });注意兩個細(xì)節(jié)。第一必須做防抖否則連續(xù)渲染會被觸發(fā)幾十次第二reapplyAnnotations內(nèi)部要先清除舊標(biāo)記再重新解析錨點并且要在解析期間臨時斷開 observer否則“清除舊標(biāo)記”這個動作本身又會觸發(fā)一次監(jiān)聽形成死循環(huán)。我在第一版就踩過這個坑直接在 observer 回調(diào)里同步執(zhí)行清理結(jié)果瀏覽器直接提醒我“Maximum call stack size exceeded”。3.4 實在找不到錨點的兜底策略最后說兜底。錨點解析失敗時我建議做三件事把批注標(biāo)記為orphaned狀態(tài)、保留原始 quote 文本、在側(cè)邊欄顯示“原文已變更”的提示。不要讓用戶覺得批注神秘消失了也不要直接把批注刪掉。如果產(chǎn)品允許還可以提供一個“重新定位”按鈕讓用戶手動選中新的文本片段來替換舊錨點。這個功能實現(xiàn)成本不高但對用戶信任度提升非常明顯文檔協(xié)作類產(chǎn)品基本都需要。4. 高亮渲染與交互從數(shù)據(jù)回到頁面4.1 用包裹標(biāo)簽生成高亮標(biāo)記而不是 CSS 偽類錨點數(shù)據(jù)解析出 Range 之后下一步就是在頁面上呈現(xiàn)高亮。我的做法是調(diào)用range.surroundContents或手動在 Range 外層插入一個mark標(biāo)簽并帶上>const mark document.createElement(mark); mark.dataset.annotationId annotation.id; mark.className annotation-marker; try { range.surroundContents(mark); } catch (e) { // surroundContents 在跨節(jié)點選區(qū)時會拋錯需要先用 extractContents 處理 const fragment range.extractContents(); mark.appendChild(fragment); range.insertNode(mark); }這里有個很重要的坑surroundContents要求 Range 的邊界必須在同一個節(jié)點內(nèi)跨節(jié)點時直接拋異常。你需要先把內(nèi)容extractContents取出來、塞進(jìn) mark、再插回去。代價是這段文字的 DOM 結(jié)構(gòu)會被改寫原文里的子標(biāo)簽會變成 mark 的嵌套節(jié)點但這屬于可接受范圍因為我們已經(jīng)用錨點數(shù)據(jù)持久化了原始位置不需要依賴被破壞的 DOM 結(jié)構(gòu)。4.2 浮動工具條的定位細(xì)節(jié)用戶選中文字后工具條要出現(xiàn)在選區(qū)上方。實現(xiàn)的關(guān)鍵是拿到選區(qū)在視口中的位置function showToolbar(range) { const rect range.getBoundingClientRect(); if (!rect || (rect.width 0 rect.height 0)) { hideToolbar(); return; } toolbar.style.left rect.left rect.width / 2 - toolbar.offsetWidth / 2 px; toolbar.style.top rect.top - toolbar.offsetHeight - 8 px; toolbar.style.display block; }注意getBoundingClientRect返回的是視口坐標(biāo)直接賦值給position: fixed的元素沒問題但如果工具條是position: absolute還要加上window.scrollY或container.scrollTop的偏移。另外滾動頁面時工具條位置會錯位需要在scroll事件里重新計算或直接隱藏我選擇在滾動時隱藏交互更干凈。4.3 側(cè)邊欄和標(biāo)記的雙向聯(lián)動批注列表我放在右側(cè)固定欄每條記錄顯示頭像、用戶名、批注內(nèi)容、原文引用和創(chuàng)建時間。點擊側(cè)邊欄條目時頁面滾動到對應(yīng)的高亮位置并加一個閃爍動畫點擊高亮標(biāo)記時側(cè)邊欄對應(yīng)條目高亮。滾動定位的核心是mark.getBoundingClientRect().top window.scrollY再用window.scrollTo加上平滑行為。閃爍動畫用 CSSkeyframes改背景色即可幾行代碼的事但對用戶理解“哪里被批注了”非常有幫助。另外有一個交互細(xì)節(jié)點擊高亮標(biāo)記時最好在標(biāo)記附近彈出一個氣泡卡片顯示批注內(nèi)容而不是直接把用戶帶到側(cè)邊欄。因為用戶看到高亮的第一反應(yīng)是“這條批注說了啥”而不是“讓我去右邊翻一翻”。氣泡卡片的定位邏輯和工具條完全一樣復(fù)用同一個定位函數(shù)就行。4.4 重疊批注的處理策略用戶可能在完全相同的文本上添加多條批注也可能在前一條批注的范圍內(nèi)再劃選取一塊更小的文本。重疊處理不好mark 標(biāo)簽嵌套混亂刪除一條時另一條也被誤刪。我的策略很簡單保證每個批注的 mark 是獨立標(biāo)簽允許嵌套但不允許同層交叉。渲染時按批注的起始位置排序位置靠前的先插入 mark后面插入時如果range.intersectsNode檢測到與已有 mark 重疊就把新 mark 插到已有 mark 的子層。刪除批注時只移除自己 id 的 mark 標(biāo)簽并做一次unwrap把原文結(jié)構(gòu)還原。這套邏輯可以覆蓋絕大多數(shù)場景實現(xiàn)成本也不高。5. 持久化與協(xié)同批注不止是本地功能5.1 批注的數(shù)據(jù)模型與接口設(shè)計錨點方案確定后數(shù)據(jù)模型就水到渠成了。我的批注對象長這樣interface Annotation { id: string; anchor: { start: { path: number[]; offset: number }; end: { path: number[]; offset: number }; quote: string; }; comment: string; authorId: string; authorName: string; createdAt: number; updatedAt: number; status: open | resolved; replyTo?: string; // 回復(fù)某個批注時使用 }接口層面只需要三個POST /annotations創(chuàng)建、PUT /annotations/:id修改內(nèi)容或狀態(tài)、DELETE /annotations/:id刪除。后端存儲直接用 JSON 字段很多數(shù)據(jù)庫都支持不需要單獨建表結(jié)構(gòu)。真正要動腦的是接口的冪等性和版本控制。5.2 多人協(xié)同時的同步策略如果同一篇文檔多人同時批注最怕的是 A 添加的批注被 B 的整篇覆蓋式保存弄丟。我建議采用操作日志operation log模式服務(wù)端保存的不只是一份批注列表而是一系列操作記錄每條記錄形如{ op: add | update | delete, data: Annotation }。新客戶端加入時按順序重放日志即可得到最新狀態(tài)。多人同時編輯同一條批注時以updatedAt時間戳為準(zhǔn)后寫的覆蓋先寫的并給被覆蓋的一方推送一個提示。對于大多數(shù)內(nèi)容協(xié)作場景這個策略夠用了不需要引入 CRDT 之類的高成本方案。同步通道用 WebSocket 比較合適批注本身不是高頻操作每秒鐘幾十條消息頂天了WebSocket 完全扛得住。連接斷開期間產(chǎn)生的操作客戶端要有重放機(jī)制重新連上后把自己斷線期間積累的操作日志批量補(bǔ)發(fā)服務(wù)端按createdAt排序后重放。5.3 性能優(yōu)化和上線前必測的邊界場景批注數(shù)量到一千條以上時頁面初始化階段逐個解析錨點、逐個插 mark 會明顯卡頓。我的優(yōu)化思路是分兩塊解析錨點時用requestIdleCallback分包處理每幀只解析一部分不阻塞首屏渲染渲染高亮標(biāo)記時只渲染視口附近的批注其他批注等滾動到附近再補(bǔ)渲染。側(cè)邊欄列表如果條目太多用虛擬滾動即可。上線前我建議固定跑一遍這幾類用例文檔內(nèi)容局部編輯后批注還能不能正確落在原文上整個段落被刪除后批注是不是正常進(jìn)入失效狀態(tài)批注重疊、嵌套、跨多個塊級元素時刪除一個會不會誤傷其他批注快速滾動頁面時工具條和氣泡卡片有沒有錯位多人同時操作時操作日志重放后狀態(tài)是否一致。這五類用例幾乎覆蓋了我實際踩過的所有坑提前測完能省下很多線上事故處理時間。做這個功能給我最大的體會是前端文字批注不是一個“加個高亮背景”的活而是一次對瀏覽器 DOM 機(jī)制和數(shù)據(jù)結(jié)構(gòu)設(shè)計的綜合考驗。把錨點想清楚后面每一步都順錨點圖省事后面每個環(huán)節(jié)都在還債。如果你正在做類似的功能建議先從選區(qū)序列化開始寫跑通“存下來再恢復(fù)”這個閉環(huán)再去補(bǔ) UI 和協(xié)同會順暢很多。最后再分享一個小技巧調(diào)試錨點問題時可以在控制臺打印range.toString()和 quote 的對比結(jié)果用文本內(nèi)容對不對來判斷定位邏輯比盯著 DOM 樹看高效得多。本文還有配套的精品資源點擊獲取