示例工程【免费下载链接】chrome-extensions-samplesChrome Extensions Samples项目地址https://gitcode.com/gh_mirrors/ch/chrome-extensions-samples点击查看免费下载本篇技术指南基于 chrome-extensions-samples 仓库中的 webNavigation/basic 示例讲解如何使用 Manifest V3 的chrome.webNavigation.onCompleted事件监听页面导航完成并通过chrome.notificationsAPI 弹出系统通知。读完本文后你将掌握 webNavigation API 的事件模型、details回调对象的字段含义、MV3 下 service worker 的注册方式以及如何在本地加载运行该示例并能基于仓库源码进一步理解如何把导航事件扩展成完整的导航采集与统计能力。示例概览在每次页面加载完成时弹出通知该示例的核心逻辑非常清晰扩展在后台service worker中注册chrome.webNavigation.onCompleted.addListener()事件监听器每当用户导航到一个新网页且加载完成后就调用chrome.notifications.create()创建一条系统通知告知用户页面已加载完成。这一模式是 webNavigation API 最基础、也最具代表性的用法——它证明了扩展可以在不注入任何内容脚本的情况下仅仅通过在后台监听浏览器导航生命周期事件就能感知并响应用户访问了新页面这一行为。通知内容中会带上被加载页面的 URL 与事件发生的时间戳方便用户直接看到是哪一次导航触发了通知。源码走读service-worker.js 中的完整实现MV3 示例的完整后台逻辑只有数十行全部位于 api-samples/webNavigation/basic/service-worker.jschrome.webNavigation.onCompleted.addListener((details) { chrome.notifications.create({ type: basic, iconUrl: icon.png, title: page loaded, message: Completed loading: details.url at details.timeStamp milliseconds since the epoch. }); });逐行拆解这段实现chrome.webNavigation.onCompleted.addListener(callback)注册onCompleted事件监听。该事件在文档及其所有子资源加载完成后触发是整个导航生命周期中页面真正可用的信号。回调参数details事件对象包含本次导航的上下文信息。本示例使用了其中的两个字段details.url本次导航加载完成的 URLdetails.timeStamp事件发生的时间单位为自 epoch1970-01-01以来的毫秒数这也是通知消息中milliseconds since the epoch的含义来源。chrome.notifications.create(options)创建一条type: basic的基础通知iconUrl指向扩展内的图标 api-samples/webNavigation/basic/icon.pngtitle固定为 page loadedmessage拼接 URL 与时间戳。值得注意的是该示例在通知文案中拼接了details.url。在实际的浏览器环境里这意味着浏览任何页面都会触发通知如果你不想收到来自所有站点的通知可以结合后续小节介绍的details过滤逻辑如检查 URL 的 host 或使用filter来缩小触发范围。manifest.json 配置解析权限与 service worker 声明示例的 api-samples/webNavigation/basic/manifest.json 是 MV3 清单的极简范本{ name: webNavigation API Sample, version: 2, description: Uses the webNavigation API to send notifications., background: { service_worker: service-worker.js }, permissions: [webNavigation, notifications], manifest_version: 3 }配置要点manifest_version: 3声明使用 Manifest V3MV3 下扩展的长期后台逻辑只能运行在 service worker 中因此不再有 MV2 时代常驻的 background page。background.service_worker指定后台脚本为 api-samples/webNavigation/basic/service-worker.js。它是事件驱动型脚本平时不占资源只有事件触发时才被唤醒执行。permissions本示例申请了两个权限——webNavigation访问导航事件与notifications创建系统通知。两者缺一不可少了webNavigationchrome.webNavigation对象不可用少了notificationschrome.notifications.create()会调用失败。这是本示例能跑通的最小权限集可作为后续开发同类扩展的参考基线。运行步骤在 Chrome 中加载并验证按以下三步即可运行该示例获取仓库代码git clone本仓库到本地仓库地址为 https://gitcode.com/gh_mirrors/ch/chrome-extensions-samples进入api-samples/webNavigation/basic目录。以未打包扩展方式加载打开 Chrome 的扩展程序管理页面chrome://extensions开启右上角的开发者模式点击加载已解压的扩展程序选择api-samples/webNavigation/basic目录。加载成功后工具栏会看到扩展图标且清单中声明的权限会自动生效。开启通知后正常浏览网页确保系统允许 Chrome 发送通知然后在任意标签页打开一个新网页。页面加载完成后桌面/系统托盘即会出现标题为 page loaded、内容包含该 URL 与时间戳的通知。多次导航即可反复验证事件触发。如果在第 2 步加载时报错优先检查manifest.json的 JSON 语法与service-worker.js路径是否与目录结构一致若加载成功但通知不出现请确认chrome://extensions页面中该扩展的权限一栏是否包含webNavigation与notifications以及系统通知权限是否开启。纵深扩展一webNavigation 的完整事件体系当前示例只监听了onCompleted一个事件但它背后是 webNavigation API 一整套导航生命周期事件。仓库归档的 MV2 版示例 _archive/mv2/api/webNavigation/basic/background.js 给出了完整事件清单var eventList [onBeforeNavigate, onCreatedNavigationTarget, onCommitted, onCompleted, onDOMContentLoaded, onErrorOccurred, onReferenceFragmentUpdated, onTabReplaced, onHistoryStateUpdated];这 9 个事件覆盖了一次导航从将要发生到最终完成或失败的完整过程按顺序大致为事件触发时机onCreatedNavigationTarget新窗口/新标签页被创建来承载导航目标时onBeforeNavigate导航即将发起、尚未发出任何请求时onCommitted导航已提交收到服务器首个响应、文档开始加载时onDOMContentLoaded文档的 DOM 解析完成时onCompleted文档及其所有子资源加载完成时onErrorOccurred导航过程中发生错误时onReferenceFragmentUpdated页面 URL 的 fragment锚点变化时onHistoryStateUpdated页面通过history.pushState/replaceState改变地址栏 URL 时onTabReplaced标签页被其他标签页替换如预渲染激活时上述表格中事件含义的先后关系可以从归档版源码的事件注册顺序与其配套的NavigationCollector状态机得到印证例如onBeforeNavigate负责记录请求开始时间this.pending_[id].start ...onCommitted负责补充transitionType与transitionQualifiersonCompleted则把挂起请求转移到完成列表并计算耗时data.timeStamp - this.pending_[id].start详见 navigation_collector.js。纵深扩展二details 对象与导航统计能力onCompleted的回调参数details远比示例中展示的两个字段丰富。从归档版示例的NavigationCollector.Request类型定义与各事件处理器中可以看到以下字段被实际使用tabId/frameId导航发生的标签页与框架 ID。归档版parseId_用tabId - frameId作为请求唯一键见 navigation_collector.js说明同一标签页内的主框架与 iframe 子框架导航会各自独立触发事件——这也是 webNavigation 与chrome.tabs.onUpdated的重要区别之一。timeStamp事件时间戳用于计算页面加载耗时。transitionType导航的发起方式如link点击链接、typed地址栏输入、reload刷新、form_submit表单提交、auto_bookmark等完整枚举见归档版NavigationCollector.NavigationTypenavigation_collector.js。transitionQualifiers导航附加限定信息如client_redirectJS/refresh 引起的客户端重定向、server_redirect301/302 服务端重定向、forward_back前进/后退按钮完整枚举见NavigationCollector.NavigationQualifiernavigation_collector.js。归档版示例利用这些字段构建了一个完整的导航采集器以tabId-frameId为键维护挂起请求在onCompleted/onErrorOccurred时把请求归类到完成/失败列表计算加载耗时并通过chrome.storage.local持久化navigation_collector.js最后在弹出窗口中按访问频率排序展示最常访问的 URL对应 popup.html 与getMostRequestedUrls方法。如果你需要在当前 MV3 示例基础上做更复杂的导航分析——例如统计高频站点、检测重定向链、监控页面加载性能——完全可以把这套挂起表 完成/失败表 storage 持久化的模式迁移到 service worker 中。注意事项与进一步实践事件会对所有框架触发从上述frameId字段可以看出页面内嵌的 iframe 也会产生独立的 webNavigation 事件。示例未做过滤因此浏览含多个 iframe 的页面时可能连续弹出多条通知。需要精确控制时可先判断details.frameId 0主框架再处理或利用details.url按域名过滤。MV2 与 MV3 的差异归档版示例运行于 Manifest V2 的 event page 之上声明了persistent: false并使用chrome.storage持久化见 归档版 manifest.json当前示例则完全基于 MV3 service worker语法上保持chrome.webNavigationAPI 的一致性迁移成本很低。最小化权限实践本示例仅申请webNavigation与notifications两个权限即可工作这与按需申请最小权限的扩展安全最佳实践一致若只是想在特定站点触发可以考虑把webNavigation的监听范围与 URL 过滤filter中的url匹配规则结合进一步降低对全部站点数据的感知面。以上内容基于仓库中的当前示例与归档版实现整理全部源码均可从 api-samples/webNavigation/basic 与 _archive/mv2/api/webNavigation/basic 两个目录直接查阅与对照。赞分享示例工程【免费下载链接】chrome-extensions-samplesChrome Extensions Samples项目地址https://gitcode.com/gh_mirrors/ch/chrome-extensions-samples点击查看免费下载相关推荐NPU推理只要15msmoment-1-small-npu时序预测性能测量与npu-smi监控完整指南NPU推理只要15msmoment 1 small npu时序预测性能测量与npu smi监控完整指南 moment 1 small npu 让 MOMENT示例工程DeerFlow 如何为 Docker AIO 沙箱配置 isolated 或 allowlist 出站网络策略DeerFlow 如何为 Docker AIO 沙箱配置 isolated 或 allowlist 出站网络策略 DeerFlow 的 AIO 沙箱默认保持正常示例工程Tianshou模型持久化架构深度解析构建可复现的深度强化学习实验系统Tianshou模型持久化架构深度解析构建可复现的深度强化学习实验系统 在深度强化学习的研究与实践中模型持久化是确保实验可复现性、训练过程可恢复性的核心技术示例工程上一篇AI Cover安全防护策略用户认证、支付安全与数据保护下一篇SectionedRecyclerViewAdapter 项目常见问题解决方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考