JavaScript Document.importNode 怎样复制其他文档的节点树

我第一次需要把 DOMParser 生成的片段塞进当前页面时，真正容易混淆的不是选择器，而是“这个节点到底属于哪个文档”。这时应该让目标文档调用 document.importNode(externalNode, true)：它会复制外部节点，返回一个处在当前文档上下文中的副本；来源节点仍然保留，副本也不会自动出现在页面里，最后还要用 appendChild() 或 insertBefore() 插入。

如果只记一个结论，可以把 importNode() 理解成“由目标 Document 接管复制动作”。deep=true 复制整棵节点树，deep=false 只复制根节点；需要移动原对象时，才应该把注意力转向 adoptNode()。

先把外部节点复制到当前文档

下面用 DOMParser 构造一个独立的文档。真实项目里，externalNode 也可以来自同源 iframe 的 contentDocument，关键点不变：调用者是目标文档，也就是当前页面的 document。

// 先创建一个不属于当前页面的独立 Document。
const sourceDoc = new DOMParser().parseFromString(
  '
外部标题
外部内容
',
  'text/html'
);

// 只从来源文档中取节点，不直接把它当作当前文档的节点使用。
const externalNode = sourceDoc.querySelector('.card');
const importedNode = document.importNode(externalNode, true);

// importNode 只产生副本；显式插入后它才进入当前文档树。
document.querySelector('#target').appendChild(importedNode);

这里的 true 很关键。卡片的 h3 和 p 会随根节点一起复制。importNode() 返回的是复制后的节点，并不会改变 sourceDoc 中的原节点；在调用 appendChild() 之前，副本的 parentNode 仍然是 null。

deep=true 和 deep=false 只差一个布尔值，结果却不同

MDN 对第二个参数的定义很直接：deep=true 会复制外部节点和全部后代；deep=false 只复制外部节点本身，新节点没有子节点。遇到“导入一整块模板”时通常使用深复制，若只是需要一个空壳元素再自行填充，浅复制才更合适。

// deep=true：复制根节点和后代节点，适合完整导入一段结构。
const deepCopy = document.importNode(externalNode, true);
console.log(deepCopy.children.length); // 副本保留后代元素

// deep=false：只复制根节点，不带原来的子节点。
const shallowCopy = document.importNode(externalNode, false);
console.log(shallowCopy.children.length); // 新节点没有子元素

// 先清空目标容器，再按需要插入其中一种副本。
const target = document.querySelector('#target');
target.replaceChildren(deepCopy);

不要把“已经拿到返回值”误认为“已经完成插入”。返回的副本仍是游离节点，只有把它放入当前文档树，页面结构才会发生变化。对 DocumentFragment 也遵循同样思路：先由目标文档导入，再插入到目标容器。

为什么不直接用 cloneNode

在同一个文档里复制节点，cloneNode() 往往已经够用；跨文档时，区别就不只是方法名。importNode() 按调用它的目标文档上下文创建副本，cloneNode() 使用被复制节点原来的文档上下文。这个文档上下文会影响自定义元素使用哪个 CustomElementRegistry，所以跨文档复制时优先使用目标文档的 importNode()。

adoptNode() 则是另一种意图：它把原节点转移给目标文档，而不是留下一个来源副本。可以用下面这张表快速做决定：

因此，问题不是“哪个 API 更高级”，而是你希望来源文档继续拥有原节点，还是希望原对象改换文档归属。复制和移动混在一起，是跨文档 DOM 代码最容易出现的误判。

把插入时机和文档边界写清楚

有两个小检查很值得固定在代码习惯里。第一，调用 importNode() 后先确认你拿到的是副本，再把它插入目标容器；第二，来源节点如果来自 iframe，只有在脚本允许访问其文档时才能读取节点，不能把“拿到 iframe 元素”当成“已经拿到可读的外部 Document”。

// 复制完成但尚未插入时，parentNode 为空是正常状态。
const copy = document.importNode(externalNode, true);
if (copy.parentNode !== null) {
  throw new Error('副本尚未插入前不应有父节点');
}

// 把插入动作限制在当前文档中的明确容器内。
const container = document.querySelector('#target');
if (!container) {
  throw new Error('找不到目标容器');
}
container.appendChild(copy);

这段检查不是为了给 importNode() 增加额外限制，而是帮助定位“复制成功但页面没有变化”的问题：大多数时候，缺的只是最后一步插入，或者目标容器选择错误。

最后用一张清单收尾

• 节点来自另一个 Document 时，让目标文档调用 importNode()。
• 需要整棵节点树就传 true，只需要根节点就传 false。
• 导入完成不等于页面已更新，必须继续调用 appendChild() 或 insertBefore()。
• 想保留来源节点就选复制；想移动原对象才考虑 adoptNode()。
• 跨文档复制涉及自定义元素时，优先考虑目标文档上下文带来的 CustomElementRegistry 影响。

官方资料：https://developer.mozilla.org/en-US/docs/Web/API/Document/importNode

常见追问

importNode() 会自动把节点放进页面吗？

不会。它只返回复制后的节点，仍需要 appendChild()、insertBefore() 或其他插入方法。

deep=false 为什么看不到子节点？

因为浅复制只复制传入的根节点，不复制它的 DOM 子树。要导入完整结构，应使用 deep=true。

什么时候用 adoptNode()？

当你的目标是把原节点转移给另一个文档，并且不需要在来源文档保留原对象时，可以考虑 adoptNode()；如果来源内容仍要保留，则使用 importNode()。