document.adoptNode 与 importNode 在跨文档移动时有什么区别

跨文档处理 DOM 节点时，document.adoptNode() 是“把原节点搬过来”，document.importNode() 是“在目标文档上下文中复制一份”。前者会让原节点离开源文档，后者保留源节点；两者返回的节点都还没有自动进入目标文档树，最后仍要用 appendChild() 或 insertBefore() 插入。

官方参考：https://developer.mozilla.org/en-US/docs/Web/API/Document/adoptNode

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

先看节点身份：adoptNode 是移动，importNode 是复制

可以先把问题拆成两个判断：源文档里的节点还要不要保留？目标文档是否应该拥有这一个节点对象？如果答案是“不要保留、转移所有权”，使用 adoptNode；如果答案是“源文档继续使用、目标文档得到副本”，使用 importNode。

adoptNode 会把节点及其子树从原文档移出，并把 ownerDocument 改成调用该方法的文档。调用结束后，返回节点与传入节点是同一对象，只是它暂时还没有父节点。importNode 则返回一个新对象，原节点与原树保持不变。

需要把节点真正搬走时，用 adoptNode 再插入

典型场景是从 iframe 文档或另一个 DOM 文档中取出一个节点，目标文档要接管它，源文档不再使用这个对象。关键顺序是：先在目标文档上调用 adoptNode，再把返回值插入目标容器。不要把“调用 adoptNode”误解成“已经插入页面”。

const sourceDocument = iframe.contentDocument;
const targetDocument = document;
const sourceItem = sourceDocument.querySelector(".card");

// adoptNode 会移走原对象，返回值仍是 sourceItem 本身。
const movedItem = targetDocument.adoptNode(sourceItem);

// adoptNode 只完成文档归属转移，这里才把节点放进目标树。
targetDocument.querySelector("#result").appendChild(movedItem);

// 下面两个判断用于表达对象身份和归属文档已经改变。
console.log(movedItem === sourceItem); // true
console.log(movedItem.ownerDocument === targetDocument); // true

这里的 movedItem === sourceItem 为真，说明它不是克隆品。若业务代码还保留着源文档中的父节点引用，需要把“节点已离开源树”纳入后续处理；若目标容器不存在，也要先处理插入失败，而不是把它当作复制操作重试。

需要保留源节点时，用 importNode 控制复制范围

当源文档还要继续显示或重复使用原节点时，应在目标文档上调用 importNode。第二个参数 deep 控制复制范围：true 会复制节点及其所有后代，false 只复制节点本身，新节点不会带有子节点。

const sourceDocument = iframe.contentDocument;
const targetDocument = document;
const sourceCard = sourceDocument.querySelector(".card");

// deep=true 复制卡片和它的完整后代，源卡片仍留在源文档。
const copiedCard = targetDocument.importNode(sourceCard, true);
targetDocument.querySelector("#preview").appendChild(copiedCard);

// deep=false 只复制外层节点，适合先创建壳再按目标文档规则填充内容。
const emptyShell = targetDocument.importNode(sourceCard, false);
console.log(emptyShell.childNodes.length); // 0

如果复制的是 DocumentFragment 或包含嵌套内容的元素，通常要明确写出 true，避免得到一个只有标签外壳的节点。复制完成后，返回值的 parentNode 仍然是 null，因为它还没有进入目标文档树。

模板和自定义元素场景，要关注目标文档上下文

importNode 与普通的 cloneNode 都能产生副本，但跨文档时两者的语义重点不同：importNode 按调用它的目标文档建立副本。文档上下文会影响自定义元素构造时使用的 CustomElementRegistry，所以要把节点交给另一个文档时，应在目标文档上导入。

const template = document.querySelector("template");
const host = document.querySelector("#app");

// template.content 属于独立的文档上下文，按目标文档导入其后代。
const fragment = document.importNode(template.content, true);

// 导入只是准备副本；插入后模板内容才进入当前文档树。
host.appendChild(fragment);

这个选择的重点不是“哪个方法更快”，而是节点所有权和构造上下文是否符合目标。能接受源节点消失时选 adoptNode；需要保留源节点、复制模板或让副本在目标文档注册表下构造时选 importNode。

用四个问题快速做选择

• 源文档还要这个节点吗？要保留就用 importNode，不保留且要转移对象才用 adoptNode。
• 后代节点要不要一起带过去？使用 importNode 时检查 deep；复杂组件通常需要 true。
• 节点是否已经进入目标树？两种 API 都只准备节点，完成后仍需 appendChild 或 insertBefore。
• 是否依赖目标文档的自定义元素定义？把目标文档作为调用者，避免只用源文档上下文生成副本。

常见问题

adoptNode 会不会复制一份新节点？

不会。它转移原节点及其子树，返回值与传入节点是同一个对象，只是节点的归属文档发生了变化。

importNode 不写第二个参数会复制子节点吗？

不会。deep 默认是 false，只导入外层节点；要复制完整后代需要显式传入 true。

调用 adoptNode 后节点会自动显示在页面上吗？

不会。调用后节点还没有父节点，必须把返回值插入目标文档树。

跨文档复制为什么不直接用 cloneNode？

importNode 明确按调用它的目标文档创建副本；当节点要在另一个文档中使用，使用目标文档的 importNode 更符合跨文档语义，尤其是涉及自定义元素注册上下文时。