JavaScript Range.createContextualFragment 怎样按上下文解析 HTML 片段

在前端代码里，如果只是把一小段普通元素插入容器，innerHTML 往往够用；但当片段要匹配表格、列表或自定义容器的解析语义时，Range.createContextualFragment() 更值得理解。它不会直接修改页面，而是把输入解析成一个 DocumentFragment，解析时使用 Range 的 start node 作为上下文。真正插入 DOM 之前，你仍然可以先检查这棵临时节点树。

最容易记住的用法是：先把 Range 的起点放到目标元素，再调用 createContextualFragment(input)；返回值是临时的 DocumentFragment，解析完成不等于已经插入页面。对于来源不可信的 HTML，必须先经过可信的清洗或 Trusted Types 策略，不能把这个 API 当作安全过滤器。

先区分“解析片段”和“直接改页面”

这个方法的价值不是少写几行字符串拼接，而是把“解析”和“挂载”拆开。createContextualFragment() 接收字符串或 TrustedHTML，返回 DocumentFragment；它本身只是一个可移动的临时节点容器。只有调用 append()、insertBefore() 等 DOM 操作后，节点才会进入页面树。

我在处理表格行、模板化列表项时，最常遇到的误区就是把“字符串已经是 HTML”误认为“浏览器会按目标位置理解它”。上下文解析的关键，恰恰是给解析器一个明确的起点。

Range 到底把谁当上下文

规范层面的核心是 Range 的 start node。如果要让某个元素提供解析上下文，可以用 selectNodeContents()，使 Range 的起点落在这个元素上。下面的示例把一行表格放进已有的 tbody，重点是 tbody 参与解析，而不是先把字符串拼到页面上。

const tableBody = document.querySelector("#orders tbody");

if (!tableBody) {
  throw new Error("找不到表格主体");
}

const range = document.createRange();
// 让 Range 的 start node 成为 tbody，给 tr 片段提供正确上下文。
range.selectNodeContents(tableBody);

const rowFragment = range.createContextualFragment(
  "A-1001待处理"
);

// 解析结果仍在临时片段中，此处才把节点移动到页面树。
tableBody.append(rowFragment);

这里不要把 selectNode() 和 selectNodeContents() 混为一谈。前者选择元素节点本身及其边界，后者把起点放在元素内容所在的容器上；当你的目标是让某个元素承担片段上下文时，直接把 start node 对准该元素更容易读懂，也更不容易在表格标签上出现意外结构。

先检查 DocumentFragment 再插入

返回的片段可以先读取节点数量、元素类型和关键属性。检查阶段的意义是把“解析成功”与“符合业务预期”分开：输入可能是空字符串，也可能包含多个顶层节点，不能默认 firstElementChild 一定存在。

function appendCard(container, htmlText) {
  const range = document.createRange();
  // 让卡片片段以容器作为解析上下文。
  range.selectNodeContents(container);

  const fragment = range.createContextualFragment(htmlText);
  // 先检查临时树，避免空片段直接进入页面。
  const firstElement = fragment.firstElementChild;
  if (!firstElement) {
    return false;
  }

  // 只读取业务需要的节点信息，再一次性插入片段。
  firstElement.setAttribute("data-ready", "true");
  container.append(fragment);
  return true;
}

注意 DocumentFragment 是一次性的搬运容器：节点插入容器后，原来的 fragment 不再拥有那些子节点。也正因为如此，应该在插入前完成检查、补充属性或绑定必要的业务信息，而不是插入后继续假设片段里还保留着节点。

表格、列表等特殊标签要匹配上下文

普通的 div、p 片段通常不容易暴露上下文问题，但 tr、td、option 这类标签有明确的父级语义。把它们当成普通字符串交给错误的上下文，解析器可能调整节点层级，后续查询就会和预期不一样。

实践中可以采用一个简单判断：片段的根标签如果依赖父级语义，就先选中对应的父元素内容；片段如果只是独立卡片，则用卡片容器作为 start node。不要用“先拼接到一个临时 div，再猜浏览器会怎样修正”的方式替代明确的上下文。

function createOption(select, value, label) {
  const range = document.createRange();
  // option 必须放在 select 的解析语境里，而不是普通 div 里。
  range.selectNodeContents(select);

  const fragment = range.createContextualFragment(
    `${label}`
  );
  // 这里仍应保证 value 和 label 已来自可信、已编码的业务数据。
  select.append(fragment);
}

如果数据来自用户输入，先做内容清洗和编码，再进入这一步。上下文解析解决的是节点结构问题，不会替你完成业务数据的安全处理。

安全边界：解析 API 不是清洗器

MDN 和 HTML Standard 都明确提醒，这个方法默认不会移除危险元素或事件处理属性。字符串来自用户、接口或第三方内容时，即使你只打算先放进 DocumentFragment，也不能因此认为它已经安全；后续插入 DOM 时仍然要按不可信输入处理。

在启用了 Trusted Types 的应用里，可以让策略负责把业务允许的 HTML 转成 TrustedHTML，再交给 Range 解析。策略函数应调用经过审查的清洗器，不能用“原样返回输入”的空策略掩盖风险。

function fragmentFromTrustedHTML(container, trustedHTML) {
  const range = document.createRange();
  // 上下文只负责结构解析，可信输入由调用方先行保证。
  range.selectNodeContents(container);

  // trustedHTML 应由应用自己的 Trusted Types 策略或清洗器产生。
  return range.createContextualFragment(trustedHTML);
}

如果应用暂时没有 Trusted Types，也至少要把清洗、解析、插入拆成三个可追踪的边界，并限制允许的标签和属性。不要把“能解析”写成“已过滤”，也不要把静态结构图当作安全证明。

采用时可以记住这五个判断

1. 需要独立检查临时节点时，优先考虑 DocumentFragment 返回值。
2. 片段依赖父级语义时，先用 selectNodeContents() 让 Range 的 start node 对准目标元素。
3. 表格行、单元格、选项等特殊标签，必须放进匹配的上下文中解析。
4. 插入前检查 childNodes、firstElementChild 和业务属性，插入后不要继续复用同一个片段。
5. 任何外部 HTML 都要经过可信的清洗或 Trusted Types 策略；解析 API 不等于安全过滤器。

这样使用时，Range.createContextualFragment() 的定位就很清楚：它是一个带上下文的 HTML/XML 片段解析入口，负责把输入变成可检查、可移动的临时节点树；什么时候把这棵树放进页面，仍由你的插入逻辑负责。

相关问题

createContextualFragment 会自动插入页面吗？

不会。它只返回 DocumentFragment，需要显式调用 append()、insertBefore() 等方法才会进入 DOM。

为什么表格行不能按普通 div 片段处理？

因为 tr、td 依赖表格父级语义。让 Range 的 start node 对准 tbody 或对应上下文，解析结果更符合目标结构。

这个 API 会自动过滤不可信 HTML 吗？

不会。它解决的是上下文解析，不负责清洗危险元素和属性；外部内容应先经过应用的清洗策略或 Trusted Types。