Chrome扩展Content Script使用Range.insertNode无法加载自定义元素

问题场景 #

开发Chrome扩展时，将Vue构建的自定义元素（打包为custom-elements.js）通过Content Script注入网页，使用Range API提取跨元素文本并包裹到自定义元素中，执行后页面显示为空——DevTools中可见原文本存在，但Shadow DOM未渲染。

相关配置与代码：

• manifest.json

  "content_scripts": [
    {
      "matches": ["*"],
      "js": ["custom-elements.js", "content.js"]
    }
  ]
  

• Range插入代码（失效）

  const originalContents = range.extractContents();
  const indicator = document.createElement('overlay-indicator');
  indicator.appendChild(originalContents);
  range.insertNode(indicator);
  

但以下场景自定义元素可正常工作：

• 使用insertBefore等方式直接插入DOM
• 在普通HTML网页中引入custom-elements.js

可能原因 #

1. connectedCallback未触发：Range.insertNode插入节点时，在Content Script的隔离环境中，自定义元素的connectedCallback（Vue自定义元素的初始化逻辑依赖此回调）可能未被正确触发。
2. 文档片段上下文异常：extractContents()返回的DocumentFragment，在Content Script环境中直接append到自定义元素时，节点的文档上下文未被正确关联，导致Shadow DOM无法渲染内容。
3. DOM状态不稳定：脚本注入时机过早，Range操作时页面DOM未完全就绪。

解决方案 #

1. 手动触发自定义元素初始化 #

在insertNode后手动调用connectedCallback，确保Vue自定义元素完成Shadow DOM挂载：

const originalContents = range.extractContents();
const indicator = document.createElement('overlay-indicator');
indicator.appendChild(originalContents);
range.insertNode(indicator);

// 手动触发初始化（避免重复触发）
if (!indicator.shadowRoot) {
  indicator.connectedCallback?.();
}

2. 逐个添加文档片段节点 #

避免直接append整个DocumentFragment，逐个添加节点确保上下文正确：

const originalContents = range.extractContents();
const indicator = document.createElement('overlay-indicator');

// 逐个转移节点到自定义元素
while (originalContents.firstChild) {
  indicator.appendChild(originalContents.firstChild);
}

range.insertNode(indicator);

3. 调整脚本注入时机 #

在manifest.json中设置脚本在文档空闲时注入，确保DOM完全加载：

"content_scripts": [
  {
    "matches": ["*"],
    "js": ["custom-elements.js", "content.js"],
    "run_at": "document_idle"
  }
]

4. 确认Vue自定义元素的Shadow DOM配置 #

打包Vue自定义元素时，确保启用Shadow DOM并设置为开放模式（方便调试）：

import { defineCustomElement } from 'vue';
import OverlayIndicator from './OverlayIndicator.ce.vue';

const OverlayIndicatorElement = defineCustomElement(OverlayIndicator, {
  shadowRootOptions: { mode: 'open' }
});

customElements.define('overlay-indicator', OverlayIndicatorElement);

总结 #

核心问题集中在Content Script隔离环境下，Range操作后的节点未触发自定义元素的初始化逻辑。通过手动触发回调、调整节点添加方式或延迟脚本注入，即可解决Shadow DOM无法渲染的问题。

内容的提问来源于stack exchange，提问作者baruchiro