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