浏览器与 Web API / 系统课时
before、after 与 insertAdjacentHTML
before、after 与 insertAdjacentHTML
相邻插入不只是“放到末尾”:内容可能位于目标元素之前、之后,或目标元素内部的首尾位置。本课用位置图和可运行示例统一这些 API,并说明何时绝不能直接解析外部字符串。
学习目标
- 区分
before、after与四种insertAdjacentHTML位置 - 使用相邻插入 API 构造可验证的 DOM 结构
- 判断纯文本插入与 HTML 字符串解析的安全边界
两类相邻插入方式
before 和 after 由目标节点调用,分别把节点或字符串插到目标节点的同级前方、同级后方。它们支持多个参数;字符串只会转换为文本节点,返回值均为 undefined。
insertAdjacentHTML(position, html) 由元素调用,会把第二个参数解析成 HTML 片段。它支持四个位置:beforebegin、afterbegin、beforeend、afterend。前后两个位置在元素外部,中间两个位置在元素内部。

四个位置名称必须完整匹配,大小写错误或传入其他字符串会触发 SyntaxError。使用 beforebegin 或 afterend 时,目标元素还必须拥有可修改的父元素,因为内容要插到它的同级位置。
主示例:构造目标元素的内外内容
下面代码可直接在浏览器控制台运行。示例先创建课程卡片,再分别向卡片外部和内部插入内容。
const card = document.createElement("article");
card.id = "course-card";
card.textContent = "课程正文";
document.body.replaceChildren(card);
// before 和 after 的字符串按纯文本处理。
card.before("课程开始:");
card.after(":课程结束");
// insertAdjacentHTML 只解析并插入给定片段。
card.insertAdjacentHTML("afterbegin", "<h2>DOM 插入</h2>");
card.insertAdjacentHTML(
"beforeend",
'<button type="button">开始学习</button>'
);
console.log(document.body.innerHTML);预期输出:
课程开始:<article id="course-card"><h2>DOM 插入</h2>课程正文<button type="button">开始学习</button></article>:课程结束页面可见顺序是“课程开始”、课程卡片和“课程结束”。卡片内部的标题位于原正文之前,按钮位于原正文之后。浏览器序列化属性时可能调整空格或引号形式,但节点层级和文本顺序应保持一致。
与 innerHTML 赋值的区别
insertAdjacentHTML 只解析新提供的片段,并把结果插入指定位置;它不会为了追加内容而重新序列化并替换目标元素的全部子节点。因此,相比 element.innerHTML += html,它更能避免已有子节点被重建,以及表单状态或节点引用意外丢失。
不过,它仍然是 HTML 解析入口。性能或位置精确并不代表输入可信,安全判断必须独立完成。
字符串安全边界
可信的固定模板可以使用 insertAdjacentHTML,例如由开发者写死、没有拼接外部数据的按钮或提示结构。来自表单、URL、接口响应或第三方内容的字符串,不应直接传入该方法,否则可能形成跨站脚本攻击入口。
仅显示用户文字时,使用 textContent、before、after、append 或 prepend。确实需要接收富文本时,应在进入 DOM 前使用经过维护、配置明确的 HTML 清洗方案,并限制允许的标签和属性。
还要避免把数据直接拼进属性或事件处理器。例如把用户内容拼进 onclick、href 或 style,即使外层模板看起来固定,也可能突破预期边界。
选择规则
目标同级前后插入节点或纯文本时,使用 before、after。目标内部首尾插入可信 HTML 模板时,使用 insertAdjacentHTML("afterbegin", ...) 或 insertAdjacentHTML("beforeend", ...)。目标外部需要解析可信 HTML 时,才使用 beforebegin 或 afterend。
若不需要 HTML 解析,优先选择节点 API。这样既能保留类型边界,也能减少把不可信字符串误当标记处理的风险。