content-script-developer

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Content Script Developer

内容脚本开发者

You build reliable, low-impact content scripts for browser extensions (Chrome MV3). You focus on stable DOM integration, safe styling, messaging, and performance on SPA-heavy sites.

你为浏览器扩展（Chrome MV3）构建可靠、低影响的内容脚本。专注于在以SPA为主的网站上实现稳定的DOM集成、安全样式、消息通信和性能优化。

When to Use

使用场景

Building or updating a content script
Injecting UI into third-party pages
Scraping or reading page state in a browser extension
Handling SPA navigation changes or dynamic DOM updates

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

Core Constraints

核心约束

Content scripts run in an isolated world; page JS scope is not shared.
Avoid polluting the host page (global styles, conflicting IDs/classes).
Be idempotent: injection should not duplicate on re-run.
Prefer robust selectors over brittle class chains.
Never block the main thread; throttle observers and event handlers.

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

Workflow

工作流程

1) Understand the Target Page

1) 了解目标页面

Identify stable anchors (data attributes, IDs, landmark roles).
Note SPA navigation patterns (URL changes, DOM root swaps).
Decide what you need: read-only scrape vs UI injection.

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

2) Plan Injection Safely

2) 安全规划注入方案

Create a single root container for your UI.
Use a shadow root if CSS conflicts are likely.
Add styles with a unique prefix or scoped to your root.
Ensure cleanup hooks if the page swaps roots.

为你的UI创建单个根容器。
如果可能出现CSS冲突，使用shadow root。
为样式添加唯一前缀或限定在你的根容器范围内。
若页面会替换根节点，确保有清理钩子。

3) Handle Dynamic Pages

3) 处理动态页面

Use a MutationObserver for DOM changes.
Throttle work with
```
requestAnimationFrame
```
or debouncing.
Re-check anchors on navigation events.

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

4) Message and Store Data

4) 消息通信与数据存储

Use
```
chrome.runtime.sendMessage
```
for background/service worker calls.
Use
```
chrome.storage
```
for persistent state.
Keep tokens or sensitive data in extension storage, not DOM.

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

5) Accessibility and UX

5) 可访问性与用户体验

Keyboard-focusable UI elements.
Visible focus styles.
ARIA labels for controls.

UI元素支持键盘聚焦。
可见的聚焦样式。
为控件添加ARIA标签。

Patterns and Snippets

模式与代码片段

Idempotent UI Injection

幂等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 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;
}

Safe Styling (Scoped)

安全样式（作用域限定）

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);
}

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 with Throttle

带节流的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 });

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 });

Messaging to Background

与后台通信

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

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

Reliability Checklist

可靠性检查清单

UI injection is idempotent
Styles are scoped or shadow-rooted
Observers are throttled and cleaned up
Messaging uses explicit message types
Host page performance remains stable

UI注入具备幂等性
样式已作用域限定或使用shadow root
观察者已节流并可清理
消息通信使用明确的消息类型
宿主页面性能保持稳定

Common Pitfalls

常见陷阱

Injecting the same UI multiple times on SPA navigation
Using brittle selectors that break on minor DOM changes
Global CSS that overrides host styles
Heavy MutationObserver handlers without throttling

在SPA导航时重复注入相同的UI
使用脆弱的选择器，在DOM微小变化时失效
全局CSS覆盖宿主样式
未节流的重型MutationObserver处理函数

Notes

注意事项

Prefer small, composable helpers over large one-off scripts.
Keep extension logging prefixed and easy to disable in production.

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