JavaScript在指定位置插入HTML片段的四种方式

作者:窗边听雨

时间:2026-11-17

浏览:550

详细讲解JavaScript在指定位置插入HTML片段的四种常见方式:insertAdjacentHTML、innerHTML/outerHTML、template元素与Range.createContextualFragment,涵盖完整代码示例、底层差异、常见陷阱与选型依据。

文章目录

在页面交互中,遇到要在列表中间插一条新消息、在某行表格前补一条记录,或者在按钮后面追加一段提示时,手头拿到的往往是一段 HTML 字符串。很多人顺手写出 list.innerHTML += itemHtml,页面看似多出了内容,但旧列表项上的点击事件、输入框里已经敲入的文字却会一并消失。要在不误伤已有节点的前提下把 HTML 片段准确放进指定位置,JavaScript 中常用的是以下四种方式:insertAdjacentHTML()、innerHTML 与 outerHTML、<template> 标签配合节点插入方法,以及 Range.createContextualFragment()。

一、insertAdjacentHTML():围绕目标元素精确插入

如果已经拿到了一个目标元素(例如某条置顶公告或某个容器节点),最直接的做法就是调用它的 insertAdjacentHTML(position, html) 方法。它不需要先创建一个临时容器,也不会序列化或重建容器内原有的节点,而是直接把 HTML 字符串解析后挂到四个固定边界之一。

position 参数只接受以下四个字符串(不区分大小写,但建议统一使用小写):

  • 'beforebegin':插入到目标元素自身之前,成为它的前一个兄弟节点。
  • 'afterbegin':插入到目标元素内部的最前面,成为它的第一个子节点。
  • 'beforeend':插入到目标元素内部的最后面,成为它的最后一个子节点。
  • 'afterend':插入到目标元素自身之后,成为它的下一个兄弟节点。
JavaScript在指定位置插入HTML片段的四种方式
图 1:insertAdjacentHTML() 的四个位置参数分别对应目标元素外部前后与内部首尾。

下面是一个在普通浏览器页面脚本中可运行的完整示例:在目标节点后面插入一条新通知,同时往列表顶部补一条置顶提醒。

<ul id="notice-list">
  <li class="pinned">系统公告:今晚 23:00 例行维护</li>
  <li>普通消息:账户资料已更新</li>
</ul>

<script>
  const list = document.getElementById('notice-list');
  const pinnedItem = list.querySelector('.pinned');

  // 1. 插在置顶项的外部后面(紧跟在 pinnedItem 之后)
  pinnedItem.insertAdjacentHTML('afterend', '<li class="new">新消息:工单状态已变更为已受理</li>');

  // 2. 插在列表内部的开头(成为 list 的第一个子节点)
  list.insertAdjacentHTML('afterbegin', '<li class="urgent">紧急提示:请核对联系方式</li>');
</script>

使用 'beforebegin' 和 'afterend' 时有一个前提:目标元素必须已经挂载在拥有父节点的 DOM 树中;如果目标节点是个刚创建出来、尚未插入页面的孤立节点(parentNode 为 null),浏览器无法在它“前面”或“后面”放置兄弟节点,此时调用外部位置插入会抛出 DOMException。另外,insertAdjacentHTML() 不会返回新插入节点的引用;如果插入后马上要操作这个新元素,需要结合 previousElementSibling、nextElementSibling 或 firstElementChild、lastElementChild 去取。

二、innerHTML 与 outerHTML:适合整体替换,局部追加有隐患

innerHTML 读写目标元素内部的所有 HTML,outerHTML 则连同目标元素自身标签一起读写。在“向空容器首次渲染一段结构”或“整体清空并替换为新内容”的场景下,直接给 innerHTML 赋值是最省事的写法;而如果目标是把页面上某个占位元素整体替换成另一段 HTML,可以给它的 outerHTML 赋值。

<div id="status-box">加载中...</div>
<span id="legacy-badge">旧版标签</span>

<script>
  // 整体替换容器内部内容
  const statusBox = document.getElementById('status-box');
  statusBox.innerHTML = '<p>数据已就绪,共 <strong>12</strong> 条记录。</p>';

  // 将占位节点连同自身一起替换(要求该节点存在父节点)
  const badge = document.getElementById('legacy-badge');
  badge.outerHTML = '<button type="button" class="tag">新版标签</button>';
  // 注意:此时变量 badge 仍指向已被移出 DOM 的旧 <span>,不再指向新的 <button>
</script>

需要明确区分的是“直接赋值”和“用 += 追加”。把 innerHTML 当成位置插入手段、写出 container.innerHTML += newHtml 时,浏览器并不是只在末尾挂一个新节点,而是先读取并序列化容器内现有的全部节点成字符串,把新字符串拼上去,清空原容器里的全部子节点,再把整段长字符串从头解析成全新节点。原有的事件监听器(通过 addEventListener 绑定)、表单控件里尚未提交的输入值、滚动位置和焦点都会跟着旧节点一起销毁。

JavaScript在指定位置插入HTML片段的四种方式
图 2:innerHTML += 会序列化并销毁全部已有子节点,而增量插入只处理新增片段。

三、<template> 元素配合节点插入方法:安全解析特殊标签

有时需要把 HTML 字符串先转成真正的 DOM 节点,在插进页面之前顺手绑定事件、填好用户输入的文本(用 textContent 避免拼接字符串带来 XSS 风险),然后再放到指定位置。不少人会先建一个临时 <div>,把字符串塞进 div.innerHTML,再把子节点搬出来。

这个习惯在普通列表项上能跑通,但一遇到表格行 <tr>、单元格 <td> 或下拉选项 <option> 就会出问题:按 HTML 解析规则,<div> 内部不允许直接出现 <tr> 或 <td>,解析器会直接丢掉这些标签,最后只剩下一段孤零零的纯文本。改用 <template> 元素就能避开这个坑。<template> 在解析 innerHTML 时采用更宽松的文档片段上下文,能够完整保留 <tr>、<td>、<option> 等受限标签,并且它的 content 属性本身就是一个 DocumentFragment,里面的图片和资源在挂载前也不会提前发起网络请求。

拿到 template.content 后,既可以用现代 DOM 的 before()、after()、prepend()、append(),也可以用传统的 parent.insertBefore(fragment, referenceNode) 把片段放到任意指定位置:

<table>
  <tbody id="order-body">
    <tr id="summary-row">
      <td>合计</td>
      <td>¥200</td>
    </tr>
  </tbody>
</table>

<script>
  function insertRowBeforeSummary(itemName, priceText) {
    const template = document.createElement('template');
    template.innerHTML = '<tr><td class="name"></td><td class="price"></td></tr>';

    // 插入前先在 DocumentFragment 中安全填充文本与绑定事件
    const fragment = template.content;
    const row = fragment.querySelector('tr');
    row.querySelector('.name').textContent = itemName;
    row.querySelector('.price').textContent = priceText;
    row.addEventListener('click', () => row.classList.toggle('selected'));

    // 精准插在“合计”这一行的前面
    const summaryRow = document.getElementById('summary-row');
    summaryRow.before(fragment);
  }

  insertRowBeforeSummary('机械键盘', '¥200');
</script>
细节提醒:无论调用 before(fragment) 还是 insertBefore(fragment, ref),DocumentFragment 里的子节点都会被一次性“移动”到页面 DOM 中,插入完成后 template.content 会变为空片段。如果要反复用同一段模板插入多份内容,应该在每次填充前重新设置 template.innerHTML,或者把模板写在页面 HTML 中并通过 template.content.cloneNode(true) 克隆一份再修改。

四、Range.createContextualFragment():按目标上下文直接生成片段

如果不想额外创建 <template> 节点,还可以借助 DOM Range API 的 createContextualFragment(html) 方法。它会根据当前 Range 所选中的节点作为解析上下文,直接把 HTML 字符串转换成一个 DocumentFragment,随后再交给 before()、after() 或 insertBefore() 放到目标位置。

这一步的关键在于先用 range.selectNodeContents(target)(或 setStartBefore 等方法)把上下文指向目标容器或参考节点。例如,当目标位置位于 <tbody> 内部时,以 tbody 为上下文创建的片段同样可以正确解析 <tr> 标签。

<ul id="task-list">
  <li data-id="1">需求评审</li>
  <li data-id="3">上线发布</li>
</ul>

<script>
  const taskList = document.getElementById('task-list');
  const deployItem = taskList.querySelector('[data-id="3"]');

  const range = document.createRange();
  // 指定解析上下文,确保片段按父容器的语法规则解析
  range.selectNodeContents(taskList);

  const fragment = range.createContextualFragment(
    '<li data-id="2">接口联调</li>'
  );

  // 使用 insertBefore 插入到“上线发布”之前
  taskList.insertBefore(fragment, deployItem);
</script>

第三种与第四种方式的共同点在于,它们都把“字符串解析”和“定位挂载”拆成了两步,中间留出了拿到节点引用的窗口。下图展示了这两种方案共用的四步操作流程。

JavaScript在指定位置插入HTML片段的四种方式
图 3:通过 <template> 或 Range.createContextualFragment() 离线生成片段后再定位插入的流程。

需要注意 createContextualFragment() 与 innerHTML、insertAdjacentHTML() 的一个行为差异:当 HTML 字符串里包含 <script> 标签时,innerHTML 和 insertAdjacentHTML() 插入后不会执行其中的脚本,而 createContextualFragment() 解析生成的 <script> 节点在插进文档后会触发执行。因此只要来源中包含不可信的外部输入,用它之前一样要做严格转义或过滤。

五、四种方式的对比、选型与常见排查

把这四种方法放在一起看,它们并不是互相替代的关系,而是分别对应“是否需要保留已有节点”“是否要在插入前拿到节点引用”“是否涉及表格等上下文受限标签”这几个实际约束。

方式 可控制的位置 保留已有节点与事件 插入前预处理节点 典型适用场景
insertAdjacentHTML() 目标元素前后、内部首尾(4 个位置) 是 否(插入后需再查找) 相对某元素直接插入静态或已转义的 HTML 片段
innerHTML / outerHTML 容器内部全部 / 替换元素自身 否(覆盖重建) 否 空容器初始化、整体清空并重绘内容
<template> + 节点插入方法 任意参考节点前后或容器内任意位置 是 是(可直接查节点、绑事件) 插入 <tr>/<td> 等标签,或需安全填充动态数据
Range.createContextualFragment() 任意参考节点前后或容器内任意位置 是 是(可直接查节点、绑事件) 希望按目标节点上下文直接解析并立即插入
JavaScript在指定位置插入HTML片段的四种方式
图 4:四种 HTML 片段插入方式的选型决策流程与安全原则。

实际编码时,如果遇到以下三类常见异常,可以按对应原因快速定位:

  • 插入表格行 <tr> 后结构错乱、只剩纯文本:通常是用临时 <div> 的 innerHTML 解析了 <tr>。改用 <template>,或者直接对已有 <tbody> / <tr> 调用 insertAdjacentHTML()。
  • 插入新节点后,原先列表里的按钮点不动了:多半是某处使用了 innerHTML +=。换成 insertAdjacentHTML('beforeend', ...) 或先转成 DocumentFragment 再用 append() / insertBefore(),即可保住旧节点的事件监听器。
  • HTML 片段里带有用户输入内容时的安全处理:以上四种方法本质上都会把字符串当作 HTML 解析,只要存在用户输入,就不要直接把用户输入拼进模板字符串里。最稳妥的配合方式是模板字符串只写固定骨架,把用户输入通过 <template> 解析后的 element.textContent = userInput 填进去,再将片段插入目标位置。

实用工具推荐

电子包浆

绿化、压缩、噪点和虚拟水印,自由调节做旧程度。

使用 ›
图片压缩

选择画质和输出格式,预览压缩前后的大小。

使用 ›
相关文章