JavaScript Document.adoptNode 怎样把节点移入另一个文档

在 DOMParser 或同源 iframe 中拿到节点后，想把它放进当前页面，关键不是直接调用 appendChild()，而是先处理节点的文档归属。Document.adoptNode(externalNode) 会把节点及其子树从原文档移出，并把它们的 ownerDocument 改成目标文档；返回值和传入的节点是同一个对象。

需要“搬走原节点”时使用 adoptNode()，需要“保留来源节点并创建副本”时使用 importNode()。采用完成后，节点还没有自动进入目标文档树，仍要显式调用 appendChild() 或其他插入方法。

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

adoptNode 改变的是节点归属

adoptNode() 的调用主体是目标文档，例如当前页面的 document。它接收另一个文档中的节点，完成三件事：从原文档树中移除节点及子树、把 ownerDocument 切换到目标文档、返回原来的节点对象。它不是深拷贝，也不会自动把节点插入目标容器。

可以把这件事理解成“转移所有权”，而不是“复制一份 HTML”。因此，下面两个比较结果都为 true：

const adopted = document.adoptNode(externalNode);

// 采用操作返回原对象，不会创建一个新的 Node。
console.log(adopted === externalNode); // true

// 目标文档成为节点新的 ownerDocument。
console.log(adopted.ownerDocument === document); // true

用 DOMParser 生成外部节点再插入当前页面

下面的例子用 DOMParser 得到一个独立的 HTML 文档，再采用其中的 section 节点，最后插入当前页面的 #target 容器。示例中没有伪造运行输出，读者可以把它放在已有页面中使用。

const parser = new DOMParser();
const sourceDoc = parser.parseFromString(
  '
来自外部文档
这段内容准备被移动。
',
  'text/html'
);

const externalCard = sourceDoc.querySelector('#card');
const target = document.querySelector('#target');

if (!externalCard || !target) {
  // 节点或目标容器不存在时提前结束，避免对 null 调用 DOM 方法。
  throw new Error('找不到待采用节点或目标容器');
}

const adoptedCard = document.adoptNode(externalCard);

// adoptNode 只完成文档归属转移，仍需明确插入目标树。
target.appendChild(adoptedCard);

console.log(adoptedCard.ownerDocument === document); // true
console.log(adoptedCard.parentNode === target); // true

这里的顺序很重要：先得到外部节点，再由目标文档调用 adoptNode()，最后插入目标容器。如果只调用采用而不调用插入，节点虽然已经属于当前文档，但仍然是一个脱离树的节点。

采用后 parentNode 为什么会变成 null

MDN 对返回值的说明里特别提到，采用后的节点还没有插入新的文档树，因此 parentNode 为 null。如果外部节点原本在一个树中，调用 adoptNode() 后，它会从原树断开；只有执行 appendChild()、prepend() 或其他插入操作后，才会重新拥有父节点。

const adoptedItem = document.adoptNode(externalItem);

// 采用完成但尚未插入，所以此时没有父节点。
console.log(adoptedItem.parentNode); // null

target.replaceChildren(adoptedItem);

// 显式插入后，父节点才是目标容器。
console.log(adoptedItem.parentNode === target); // true

如果你的代码需要继续访问原文档中的同一个节点，就不要在这里使用 adoptNode()。它的语义就是移动，原文档不再保留这棵节点子树。

adoptNode 和 importNode 的选择差异

两者都能解决“外部文档的节点不能直接插入当前文档”的问题，但意图不同：

选择时可以只问一个问题：来源节点以后还要不要继续使用？如果答案是“不要”，采用更贴合移动语义；如果答案是“要”，复制后插入更稳妥。使用 importNode() 时要注意第二个参数 deep：传入 true 才会复制元素的后代节点。

iframe 场景先看同源边界

从 iframe 取节点时，代码通常会访问 iframe.contentDocument。只有 iframe 与当前页面满足同源条件，脚本才可以读取其中的 DOM 节点；跨源 iframe 不是换成 adoptNode() 就能绕开的，读取节点本身会受到浏览器同源策略限制。

const iframe = document.querySelector('#previewFrame');
const target = document.querySelector('#target');

if (!iframe || !target || !iframe.contentDocument) {
  // contentDocument 不可读取时，先报告边界条件，不继续操作节点。
  throw new Error('iframe 文档不可访问，先检查同源条件');
}

const sourceImage = iframe.contentDocument.querySelector('img');
if (!sourceImage) {
  throw new Error('iframe 中没有找到图片节点');
}

// 这是移动原节点；如果还要保留 iframe 中的图片，应改用 importNode。
target.appendChild(document.adoptNode(sourceImage));

最后用四个问题判断是否用对了

• 调用者是不是目标文档？应由要接收节点的 document 调用 adoptNode()。
• 是否接受原节点被移走？不能接受时改用 importNode()。
• 是否记得显式插入？采用后 parentNode 仍可能为 null。
• 外部文档是否可读取？同源 iframe 可以继续处理，跨源 iframe 需要先改变通信或资源设计，不能直接拿 DOM。

相关问题

adoptNode 会复制节点吗？

不会。返回值和传入的节点是同一个对象；需要副本时使用 importNode()。

调用 adoptNode 后节点会自动显示吗？

不会。它只改变文档归属并从原文档树移出，仍要把返回节点插入目标容器。

为什么 adoptNode 后 parentNode 是 null？

因为节点已经脱离原文档树，但尚未进入目标文档树。完成一次显式插入后才会拥有新的父节点。