WHATWG HTML 新增 appendHTML、beforeHTML 等定位插入方法
WHATWG HTML Standard commit e88f8aa · 2026-10-12
想把一段 HTML 字串插到某個節點的前後或尾端，過去只能用 insertAdjacentHTML() 或 innerHTML +=，兩者都不經過 Sanitizer API。這個 commit 把 setHTML() 的「先解析、再過濾」流程擴充成一整組定位插入方法：appendHTML、prependHTML、beforeHTML、afterHTML、replaceWithHTML。
作者為 Noam Rosenthal，2026-10-12 合入 whatwg/html，commit 訊息標明關閉 issue #10122。
原本的問題
規格裡原本只有 setHTML() 與 setHTMLUnsafe()，而且只能整段取代子節點。要在尾端追加內容的人，通常退回 innerHTML +=，這會把既有子樹整個序列化再重新解析，還繞過 sanitizer；改用 insertAdjacentHTML() 則同樣沒有 sanitizer 參數。
結果是：想安全地「只追加」的程式碼沒有對應的 API，只能自己先建 template、呼叫 setHTML()、再搬節點。
// 以前：追加內容，無過濾
list.insertAdjacentHTML('beforeend', userHtml);
// 現在：追加內容，預設走 sanitizer
list.appendHTML(userHtml);核心改動
commit 在 Element 與 ShadowRoot 上加入 appendHTML、prependHTML；在 NonDocumentTypeChildNode mixin 上加入 beforeHTML、afterHTML、replaceWithHTML。CharacterData 也會一併獲得後三者。
每個方法都有對應的 *Unsafe 版本。安全版簽名為 (DOMString html, optional SetHTMLOptions options)，options.sanitizer 預設是 "default" 預設集合，並且移除不安全內容；Unsafe 版接受 TrustedHTML 或字串，與 setHTMLUnsafe() 一致，因此可被 Trusted Types 管制。
| 需求 | 舊寫法 | 新方法 |
|---|---|---|
| 尾端追加 | insertAdjacentHTML('beforeend', s) | appendHTML(s) |
| 開頭插入 | insertAdjacentHTML('afterbegin', s) | prependHTML(s) |
| 節點之前 | insertAdjacentHTML('beforebegin', s) | beforeHTML(s) |
| 節點之後 | insertAdjacentHTML('afterend', s) | afterHTML(s) |
| 整個節點換掉 | outerHTML = s | replaceWithHTML(s) |
規格細節與邊界行為
commit 訊息與 patch 內的說明明確列出幾個容易踩到的行為：
beforeHTML、afterHTML、replaceWithHTML在節點沒有父節點時靜默不做事，與 DOM 的before()等方法一致；父節點不合法則丟HierarchyRequestError。template元素不能當作 before/after/replace 的父節點，因為對template設定 HTML 影響的是 template contents，不是它的子節點。appendHTML與prependHTML對template則是操作 template contents。html元素不能當作插入或取代的父節點或目標，因為以html為 context 解析一定會產生head與body，丟HierarchyRequestError。- 目標是 HTML 或 SVG 的
script元素時，setHTML與appendHTML等方法什麼都不做。
同一個 commit 也把內部演算法名稱「set and filter HTML」改為「filter and set HTML」，與實際執行順序對齊，並新增「parse HTML for insertion」等共用步驟，讓新舊方法共用同一套 sanitizer 流程。
影響範圍
用 insertAdjacentHTML 或 innerHTML += 渲染使用者內容的前端程式：這是第一批可以改寫的地方。改寫後內容會自動經過預設 sanitizer，不必再自己包 DOMPurify 類函式庫；若需要保留特定標籤，就傳入 sanitizer 選項。
啟用 Trusted Types 的站台：Unsafe 版吃 TrustedHTML，政策檢查點與 setHTMLUnsafe() 相同，lint 規則可以把裸字串的 insertAdjacentHTML 一併列為待改項目。
框架與函式庫作者：做 partial render 或 list append 的程式碼，可以用 replaceWithHTML 取代 outerHTML 賦值，並處理 HierarchyRequestError 與「無父節點則無動作」兩種新情境。
這個 commit 只是規格變更；各瀏覽器何時實作、是否已出貨，commit 內未說明，上線前需要另外查相容性。