Web Components adoptedCallback 什么时候触发

Web Components 里的 adoptedCallback() 只在自定义元素被采用到新的 Document时触发，例如把元素从主页面移动到 iframe 的文档，或显式调用目标文档的 adoptNode()。同一个页面里把元素从一个父节点换到另一个父节点，只改变 DOM 位置，不会触发它。

判断这个回调最简单的办法是看 element.ownerDocument 是否跨了文档边界：文档变了，才有 adoptedCallback；位置变了但文档没变，关注的是 connectedCallback、disconnectedCallback 或 state-preserving move。

adoptedCallback 只关注文档归属变化

规范把 custom element 的生命周期反应分成多个边界：元素升级时运行构造函数，进入文档时运行 connectedCallback()，离开文档时运行 disconnectedCallback()，被采用到新文档时运行 adoptedCallback()。因此，adoptedCallback() 不是“元素被移动了”的泛化通知，而是“元素的 node document 换了”的专用通知。

回调可以接收旧文档和新文档两个参数。实际项目中最有价值的用途，是把依赖文档的资源重新绑定，例如新窗口里的样式表、与 ownerDocument.defaultView 相关的对象，或者用于诊断的文档标识。组件自己的业务状态不应该因为换文档就无条件清空。

adoptNode、appendChild 与 importNode 怎么区分

跨文档操作最容易混淆的是“移动”和“复制”。adoptNode() 返回原节点，并把它的文档归属改成目标文档；把一个来自其他文档的节点直接交给目标文档的 appendChild()，浏览器也会先完成采用再插入。importNode() 则返回一个新克隆，原元素仍留在原文档。

下面的示例故意把三种动作放在一起。代码中的注释只标出边界，不依赖某个框架，也不把日志顺序当成业务契约：

class PortalCard extends HTMLElement {
  constructor() {
    super();
    // 构造函数只建立一次性的基础状态，不读取尚未稳定的子节点。
    this._resourceDocument = null;
  }

  connectedCallback() {
    // 连接到文档后再做需要 ownerDocument 的渲染或资源准备。
    this._resourceDocument = this.ownerDocument;
  }

  adoptedCallback(oldDocument, newDocument) {
    // 文档归属改变时，只更新依赖文档的资源边界。
    this._resourceDocument = newDocument;
    console.log("document changed", oldDocument, newDocument);
  }
}

customElements.define("portal-card", PortalCard);

const card = document.querySelector("portal-card");
const targetDocument = iframe.contentDocument;

// 移动同一个节点：它会进入 targetDocument。
targetDocument.body.appendChild(card);

// 显式采用同一个节点，之后再决定插入位置。
const adoptedCard = targetDocument.adoptNode(card);
targetDocument.body.appendChild(adoptedCard);

// 复制节点：原 card 不会因为这次 importNode 变更归属。
const clonedCard = targetDocument.importNode(card, true);
targetDocument.body.appendChild(clonedCard);

示例里连续操作同一个变量只是为了展示 API 语义，真实代码应当根据业务选择一种路径；如果先把 card 移走，再对它做复制，复制的来源文档和连接状态就已经不同了。

回调里该做什么，哪些事情不要重复做

connectedCallback() 适合处理“进入某个文档后才成立”的连接工作，disconnectedCallback() 适合释放监听和观察器，adoptedCallback() 适合处理“仍是这个组件，但所属文档换了”的迁移工作。三者可能在一次跨文档移动中相邻出现，所以初始化代码应有幂等保护，不能把每次连接都当成首次创建。

尤其要注意样式资源。Shadow DOM 仍然跟随元素移动，但依赖文档的对象可能有自己的归属限制。组件如果保存了构造样式表、窗口级事件目标或文档级缓存，应在 adoptedCallback() 中按新文档重新取得；如果只是普通字符串状态、属性值或组件内部数据，不必因为回调触发就清空。

排查 adoptedCallback 是否应该触发

1. 打印移动前后的 node.ownerDocument，确认两者不是同一个对象。
2. 确认动作是 adoptNode()、跨文档插入，还是仅在同一个文档内换父节点。
3. 若使用 importNode()，分别记录原节点和克隆节点，别把两个对象的回调混在一起。
4. 检查回调参数中的 oldDocument 与 newDocument，把资源重绑限定在文档相关部分。

如果只是同一文档里调整位置，并且不想让连接/断开逻辑反复执行，可以考虑支持 state-preserving move 的 connectedMoveCallback() 与 Element.moveBefore()；这解决的是“同文档换位”的状态问题，不会替代跨文档采用回调。

常见问题

同一个页面里 appendChild 两次会触发 adoptedCallback 吗？

不会，只要两个父节点属于同一个 Document。这属于 DOM 位置变化，重点检查连接回调和组件自身的状态保护。

importNode() 会让原自定义元素触发 adoptedCallback 吗？

不会。importNode() 返回的是新节点，原元素仍在原文档；如果把克隆插入目标文档，应单独观察克隆节点的升级、连接和资源初始化。

adoptedCallback() 里应该重新渲染整个组件吗？

通常不需要。先列出真正依赖 Document 或 Window 的资源，只重绑这些对象；完整渲染应放在有明确状态变化的路径中，并做好重复连接保护。