示例工程【免费下载链接】chrome-extensions-samplesChrome Extensions Samples项目地址https://gitcode.com/gh_mirrors/ch/chrome-extensions-samples点击查看免费下载导读functional-samples/cookbook.offscreen-dom是 chrome-extensions-samples 仓库中一个典型的「食谱recipe」型示例它演示了Manifest V3 扩展的 Service Worker 中如何使用 Offscreen Document离屏文档 DOMParser 解析并修改 HTML 字符串。读完本文你将掌握为什么 MV3 的 Service Worker 无法直接操作 DOM、如何用chrome.offscreen.createDocument()创建离屏文档、如何在离屏文档与 Service Worker 之间用消息传递交换数据以及如何编写hasDocument()这样的幂等防护逻辑让整个方案可安全落地到真实扩展中。背景Extension Service Worker 的 DOM 能力边界Manifest V3 将扩展的后台逻辑迁移到Extension Service Worker中运行。Service Worker 是独立的 worker 线程没有window、document等 DOM 对象也无法直接访问页面 DOM。这意味着很多在 MV2 时代看似平凡的能力如DOMParser、剪贴板、getUserMedia、音频播放在 MV3 后台脚本中都不再可用。原文档给出的解决思路非常直接把需要 DOM 的工作转移到一个离屏文档Offscreen Document中执行。离屏文档是一个由扩展创建、对用户不可见的 HTML 页面它拥有完整的 DOM 环境扩展 Service Worker 与离屏文档之间通过chrome.runtime消息传递交换数据。提示原文档引用的 offscreen API 文档https://developer.chrome.com/docs/extensions/reference/offscreen/与加载未打包扩展的步骤说明https://developer.chrome.com/docs/extensions/mv3/getstarted/development-basics/#load-unpacked可帮助你了解 API 全貌本文则聚焦仓库内可运行的实现。运行这个示例按照原文档的步骤三步即可在本地跑通克隆本仓库得到functional-samples/cookbook.offscreen-dom目录。以未打包扩展方式加载打开chrome://extensions开启右上角「开发者模式」点击「加载已解压的扩展程序」选择functional-samples/cookbook.offscreen-dom目录。触发演示点击浏览器工具栏上的扩展图标即扩展的 action该扩展名为Offscreen API - DOM Parsing见 manifest.json 中的name字段。触发后打开扩展 Service Worker 的 DevTools 控制台在chrome://extensions中点击该扩展卡片上的「服务工作进程」链接即可看到 DOM 变换的结果日志Received dom ...其中包含被添加了!!!后缀的h1标题。清单配置最小化的权限声明这个示例的 manifest.json 非常精简完整内容如下{ name: Offscreen API - DOM Parsing, version: 1.0, description: Shows how to use DOMParser in an extension service worker using the offscreen document., manifest_version: 3, background: { service_worker: background.js }, action: {}, permissions: [offscreen] }关键点manifest_version: 3与background: { service_worker: background.js }声明 MV3 后台 Service Worker 入口。action: {}注册浏览器工具栏按钮使chrome.action.onClicked事件可用空对象即使用默认图标与行为。permissions: [offscreen]使用 Offscreen Document 必须先声明offscreen权限这是整个方案的前提。核心流程Service Worker 侧的两段式实现扩展的入口逻辑位于 background.js核心是「确保离屏文档存在 → 发消息 → 收结果 → 关闭离屏文档」四个阶段。1. 点击 action发起 DOM 解析任务const OFFSCREEN_DOCUMENT_PATH /offscreen.html; chrome.action.onClicked.addListener(async () { sendMessageToOffscreenDocument( add-exclamationmarks-to-headings, htmlhead/headbodyh1Hello World/h1/body/html ); });每次点击工具栏图标Service Worker 都会向离屏文档发送一条类型为add-exclamationmarks-to-headings的消息携带一段待解析的 HTML 字符串h1Hello World/h1。sendMessageToOffscreenDocument未使用await但内部是异步流程靠消息驱动完成后续处理。2. 按需创建离屏文档async function sendMessageToOffscreenDocument(type, data) { // Create an offscreen document if one doesnt exist yet if (!(await hasDocument())) { await chrome.offscreen.createDocument({ url: OFFSCREEN_DOCUMENT_PATH, reasons: [chrome.offscreen.Reason.DOM_PARSER], justification: Parse DOM }); } // Now that we have an offscreen document, we can dispatch the message. chrome.runtime.sendMessage({ type, target: offscreen, data }); }这里体现了离屏文档 API 的核心参数url离屏文档的 HTML 页面路径此处为扩展包内相对路径/offscreen.html该文件仅 2 行见 offscreen.html只负责加载offscreen.js。reasons声明创建离屏文档的业务原因。chrome.offscreen.Reason.DOM_PARSER明确说明该文档用于 DOM 解析这是 API 校验的一部分。justification给审核者或开发者看的理由字符串本例为Parse DOM。hasDocument()用于幂等保护避免重复创建离屏文档同一扩展同时只允许存在有限数量的离屏文档重复创建会抛错async function hasDocument() { // Check all windows controlled by the service worker if one of them is the offscreen document const matchedClients await clients.matchAll(); for (const client of matchedClients) { if (client.url.endsWith(OFFSCREEN_DOCUMENT_PATH)) { return true; } } return false; }它通过clients.matchAll()遍历 Service Worker 控制的全部客户端凡 URL 以/offscreen.html结尾者即判定为离屏文档已存在。3. 接收并派发来自离屏文档的返回消息chrome.runtime.onMessage.addListener(handleMessages); async function handleMessages(message) { // Return early if this message isnt meant for the background script if (message.target ! background) { return; } switch (message.type) { case add-exclamationmarks-result: handleAddExclamationMarkResult(message.data); closeOffscreenDocument(); break; default: console.warn(Unexpected message type received: ${message.type}.); } } async function handleAddExclamationMarkResult(dom) { console.log(Received dom, dom); }消息处理函数先检查message.target background做目标过滤再用switch按message.type派发。收到add-exclamationmarks-result后把结果修改后的 HTML 字符串打印到控制台并调用closeOffscreenDocument()回收离屏文档async function closeOffscreenDocument() { if (!(await hasDocument())) { return; } await chrome.offscreen.closeDocument(); }同样先做存在性检查再调用chrome.offscreen.closeDocument()。用完即关是离屏文档的重要实践离屏文档会持续占用资源不应长期保留。离屏文档侧DOMParser 解析与结果回传离屏文档的实际逻辑在 offscreen.js它同样在脚本加载时立即注册消息监听// Registering this listener when the script is first executed ensures that the // offscreen document will be able to receive messages when the promise returned // by offscreen.createDocument() resolves. chrome.runtime.onMessage.addListener(handleMessages);注意这一设计细节监听器必须在脚本首次执行时就注册而不是等到某个异步回调之后这样offscreen.createDocument()返回的 Promise 一旦 resolve离屏文档就能立即接收消息不会出现「文档建好了却收不到消息」的时序问题。离屏文档侧的handleMessages与后台镜像对称先校验message.target ! offscreen则提前返回再按类型派发async function handleMessages(message) { // Return early if this message isnt meant for the offscreen document. if (message.target ! offscreen) { return false; } switch (message.type) { case add-exclamationmarks-to-headings: addExclamationMarksToHeadings(message.data); break; default: console.warn(Unexpected message type received: ${message.type}.); return false; } }核心的 DOM 变换逻辑function addExclamationMarksToHeadings(htmlString) { const parser new DOMParser(); const document parser.parseFromString(htmlString, text/html); document .querySelectorAll(h1) .forEach((heading) (heading.textContent heading.textContent !!!)); sendToBackground( add-exclamationmarks-result, document.documentElement.outerHTML ); } function sendToBackground(type, data) { chrome.runtime.sendMessage({ type, target: background, data }); }完整链路是DOMParser.parseFromString(htmlString, text/html)把原始 HTML 字符串解析为内存中的documentdocument.querySelectorAll(h1)选中全部一级标题逐一在textContent末尾追加!!!用document.documentElement.outerHTML把修改后的整棵文档树序列化回 HTML 字符串通过chrome.runtime.sendMessage({ type, target: background, data })回传后台由后台打印结果。由于离屏文档拥有完整 DOM 能力这里使用的DOMParser、querySelectorAll、textContent、outerHTML都是标准 Web API无需任何扩展专用封装。消息协议设计target type 双字段约定纵观 background.js 与 offscreen.js可以发现这套示例在消息设计上的两个约定值得在真实扩展中复用字段含义本示例取值target消息接收方避免后台/离屏文档两个监听器互相抢消息offscreen去离屏文档、background回后台type具体业务指令由接收方switch派发add-exclamationmarks-to-headings、add-exclamationmarks-result两个脚本都注册了chrome.runtime.onMessage且扩展内所有消息都会广播到所有上下文因此target过滤是防止消息串扰的关键离屏文档只处理target offscreen的消息后台只处理target background的消息其余一律提前返回。同类模式在仓库中的延伸印证「离屏文档解决 Service Worker 能力缺口」是 chrome-extensions-samples 仓库中的常见套路与本示例形成互补可相互印证 API 的通用性cookbook.offscreen-clipboard-write用chrome.offscreen.Reason.CLIPBOARD创建离屏文档写入系统剪贴板并在注释中说明「截至 2023 年 1 月Service Worker 无法用navigator.clipboard或document.execCommand()直接操作剪贴板」同时预留了 Service Worker 支持 Clipboard API 后的替代实现addToClipboardV2()。该示例的 background.js 展示了与本示例几乎相同的「创建文档 →sendMessage」模式。cookbook.offscreen-user-media在离屏文档中使用navigator.mediaDevices.getUserMedia录制麦克风Reasons: [USER_MEDIA]。它额外展示了另一种离屏文档存在性检查方式——用chrome.runtime.getContexts({ contextTypes: [OFFSCREEN_DOCUMENT] })替代clients.matchAll()以及用creatingPromise 引用防止并发创建见 background.js还涉及离屏文档内无法弹出权限提示、需先在普通扩展页授权等细节。cookbook.offscreen-clipboard-write的权限声明是[offscreen, clipboardWrite]与本示例的[offscreen]形成对照不同使用场景需要声明不同的附加权限。这些示例共同证明chrome.offscreen.createDocument() 消息传递是 MV3 时代在 Service Worker 之外「补齐 DOM 能力」的标准架构范式DOM 解析只是其中一个典型应用场景。总结与最佳实践清单cookbook.offscreen-dom用约 80 行核心代码完整演示了「Service Worker 中做 DOM 解析」的可行方案。将其落地到自己的扩展时建议遵循以下实践先声明权限manifest.json中必须包含permissions: [offscreen]。创建前做存在性检查用clients.matchAll()本示例或chrome.runtime.getContexts()cookbook.offscreen-user-media 的写法判断离屏文档是否已存在避免重复创建。在脚本加载时立即注册消息监听确保创建 Promise resolve 后消息不会丢失。用targettype双字段设计消息协议防止后台与离屏文档互相误收消息。reasons与justification要如实填写Reason.DOM_PARSER对应 DOM 解析场景其他场景如CLIPBOARD、USER_MEDIA各有专属取值。任务结束即关闭离屏文档chrome.offscreen.closeDocument()避免资源长期占用如果文档需要长期复用也可以选择不关闭以换取后续更快的响应。参照 offscreen.html 与 offscreen.js 的极简结构你可以把任意「需要 DOM 但 Service Worker 做不了」的逻辑搬进离屏文档并用消息传递把结果带回后台——这正是 MV3 扩展架构中值得熟练掌握的核心技能。赞分享示例工程【免费下载链接】chrome-extensions-samplesChrome Extensions Samples项目地址https://gitcode.com/gh_mirrors/ch/chrome-extensions-samples点击查看免费下载相关推荐Linux 设计师用 WinApps 在应用菜单里运行 90 余款 Adobe 等 Windows 应用Linux 设计师用 WinApps 在应用菜单里运行 90 余款 Adobe 等 Windows 应用 需要用 Photoshop 处理素材时你得先重启进示例工程深度解析React Hot Loader的reconciler模块如何实现组件热更新协调深度解析React Hot Loader的reconciler模块如何实现组件热更新协调 React Hot Loader是一个让开发者能够在React应用运示例工程WebToApp 中的 Chrome MV3 扩展运行时:manifest 解析、chrome.* polyfill 与 declarativeNetRequest 拦截实现详解WebToApp 中的 Chrome MV3 扩展运行时:manifest 解析、chrome. polyfill 与 declarativeNetReques移动开发开发工具上一篇Graphlib核心功能解析从创建图到执行最短路径算法下一篇GenAIScript 开源项目教程用 JavaScript 编排大语言模型的革命性框架创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考