content-script-developer

内容脚本开发者

适用场景

• 构建或更新内容脚本
• 向第三方页面注入 UI
• 在浏览器扩展中抓取或读取页面状态
• 处理 SPA 导航变化或动态 DOM 更新

核心约束

• 内容脚本运行在隔离环境中；不会与页面 JS 共享作用域。
• 避免污染宿主页面（全局样式、冲突的 ID/类名）。
• 确保操作幂等：重复运行时不应重复注入。
• 优先使用稳健的选择器，避免脆弱的类名链。
• 切勿阻塞主线程；对观察器和事件处理程序进行节流。

工作流

1) 了解目标页面

• 找出稳定的锚点（数据属性、ID、地标角色）。
• 记录 SPA 导航模式（URL 变化、DOM 根节点替换）。
• 确定需求：只读抓取还是注入 UI。

2) 安全地规划注入

• 为 UI 创建一个根容器。
• 如果可能出现 CSS 冲突，请使用 shadow root。
• 使用唯一前缀或将样式限定在根容器内。
• 如果页面替换根节点，请确保有清理钩子。

3) 处理动态页面

• 使用 MutationObserver 监听 DOM 变化。
• 使用 requestAnimationFrame 或防抖机制对工作进行节流。
• 在导航事件发生时重新检查锚点。

4) 发送消息和存储数据

• 使用 chrome.runtime.sendMessage 调用后台程序或服务工作线程。
• 使用 chrome.storage 存储持久状态。
• 将令牌或敏感数据保存在扩展存储中，而非 DOM 中。

5) 无障碍与用户体验

• UI 元素可通过键盘聚焦。
• 显示焦点样式。
• 为控件添加 ARIA 标签。

模式与代码片段

幂等 UI 注入

const ROOT_ID = 'ext-root';

export function ensureRoot() {
  let root = document.getElementById(ROOT_ID);
  if (root) return root;

  root = document.createElement('div');
  root.id = ROOT_ID;
  root.setAttribute('data-ext-root', 'true');
  document.body.appendChild(root);
  return root;
}

安全设置样式（限定作用域）

const styleId = 'ext-style';

function injectStyles(css: string) {
  if (document.getElementById(styleId)) return;
  const style = document.createElement('style');
  style.id = styleId;
  style.textContent = css;
  document.head.appendChild(style);
}

使用节流的 MutationObserver

let scheduled = false;
const observer = new MutationObserver(() => {
  if (scheduled) return;
  scheduled = true;
  requestAnimationFrame(() => {
    scheduled = false;
    // re-check anchors or update UI
  });
});

observer.observe(document.body, { childList: true, subtree: true });

向后台发送消息

async function fetchData(payload: Record<string, unknown>) {
  return await chrome.runtime.sendMessage({ type: 'FETCH_DATA', payload });
}

可靠性检查清单

• UI 注入具有幂等性
• 样式已限定作用域或置于 shadow root 中
• 观察器已进行节流并在使用后清理
• 消息传递使用明确的消息类型
• 宿主页面性能保持稳定

常见问题

• 在 SPA 导航时多次注入相同 UI
• 使用脆弱的选择器，导致页面稍有 DOM 变化就失效
• 全局 CSS 覆盖宿主页面样式
• 未进行节流的 MutationObserver 处理程序负载过重

备注

• 优先使用小型、可组合的辅助函数，而非大型的一次性脚本。
• 为扩展日志添加统一前缀，并确保便于在生产环境中禁用。