介绍扩展 Service Worker 概念的教程
概览
本教程介绍了 Chrome 扩展程序 Service Worker。在本教程中,您将构建一个扩展程序,让用户能够使用多功能框快速导航到 Chrome API 参考文档页面。您将了解如何:
- 注册 Service Worker 并导入模块。
- 调试扩展程序 Service Worker。
- 管理状态和处理事件。
- 触发定期事件。
- 与内容脚本进行通信。
前期准备
本指南假定您具备基本的 Web 开发经验。建议您查看扩展程序 101 和 Hello World 扩展程序,了解如何开发扩展程序。
构建扩展程序
首先创建一个名为 quick-api-reference
的新目录来保存扩展程序文件,或者从我们的 GitHub 示例代码库下载源代码。
第 1 步:注册 Service Worker
在项目的根目录中创建清单文件,并添加以下代码:
manifest.json:
{
"manifest_version": 3,
"name": "Open extension API reference",
"version": "1.0.0",
"icons": {
"16": "images/icon-16.png",
"128": "images/icon-128.png"
},
"background": {
"service_worker": "service-worker.js"
}
}
扩展程序在清单中注册其 Service Worker,这只需要一个 JavaScript 文件。无需像在网页中那样调用 navigator.serviceWorker.register()
。
创建一个 images
文件夹,然后将图标下载到该文件夹中。
查看阅读时间教程的前几步,详细了解该扩展程序在清单中的元数据和图标。
第 2 步:导入多个 Service Worker 模块
我们的 Service Worker 实现了两项功能。为了提高可维护性,我们将在单独的模块中实现每项功能。首先,我们需要在清单中将 Service Worker 声明为一个 ES 模块,从而允许我们将模块导入到 Service Worker 中:
manifest.json:
{
"background": {
"service_worker": "service-worker.js",
"type": "module"
},
}
创建 service-worker.js
文件并导入两个模块:
import './sw-omnibox.js';
import './sw-tips.js';
请创建这些文件,并为每个文件添加控制台日志。
sw-omnibox.js:
console.log("sw-omnibox.js");
sw-tips.js:
console.log("sw-tips.js");
请参阅导入脚本,了解在 Service Worker 中导入多个文件的其他方法。
可选:调试 Service Worker
我将介绍如何查找 Service Worker 日志并了解其终止时间。首先,按照说明加载解压的扩展程序。
30 秒后,您将看到“Service Worker(非活跃)”状态,这表示 Service Worker 已终止。点击“Service Worker(非活跃)”链接进行检查。下面的动画展示了这种情况。
您是否注意到检查 Service Worker 将它唤醒?在开发者工具中打开 Service Worker 可使其保持活动状态。为了确保您的扩展程序在 Service Worker 终止后能够正常运行,请记得关闭 DevTools。
现在,中断该扩展程序,以了解在何处找到错误。一种方法是从 service-worker.js
文件的 './sw-omnibox.js'
导入中删除“.js”。Chrome 将无法注册 Service Worker。
返回 chrome://extensions,然后刷新扩展程序。您会看到两个错误:
Service worker registration failed. Status code: 3.
An unknown error occurred when fetching the script.
如需了解调试扩展程序 Service Worker 的更多方法,请参阅调试扩展程序。
第 4 步:初始化状态
Chrome 会关闭不需要的 Service Worker。我们使用 chrome.storage
API 跨 Service Worker 会话保留状态。如需访问存储空间,我们需要在清单中请求权限:
manifest.json:
{
...
"permissions": ["storage"],
}
首先,将默认建议保存到存储空间。我们可以在首次安装扩展程序时,通过监听 runtime.onInstalled()
事件来初始化状态:
sw-omnibox.js:
...
// Save default API suggestions
chrome.runtime.onInstalled.addListener(({ reason }) => {
if (reason === 'install') {
chrome.storage.local.set({
apiSuggestions: ['tabs', 'storage', 'scripting']
});
}
});
Service Worker 无法直接访问窗口对象,因此无法使用 window.localStorage
存储值。此外,Service Worker 也是短期执行环境;它们会在用户的浏览器会话中反复终止,这使得它们与全局变量不兼容。请改用 chrome.storage.local
,将数据存储在本地机器上。
如需了解扩展 Service Worker 的其他存储选项,请参阅保留数据而不是使用全局变量。
第 5 步:注册事件
所有事件监听器都需要在 Service Worker 的全局范围内静态注册。换言之,事件监听器不应嵌套在异步函数中。这样,Chrome 就可以确保在 Service Worker 重新启动时恢复所有事件处理脚本。
在本示例中,我们将使用 chrome.omnibox
API,但首先我们必须在清单中声明多功能框关键字触发器:
manifest.json:
{
...
"minimum_chrome_version": "102",
"omnibox": {
"keyword": "api"
},
}
现在,在脚本的顶层注册多功能框事件监听器。如果用户在地址栏中输入多功能框关键字 (api
),然后依次输入标签页或空格键,Chrome 会根据存储空间中的关键字显示建议列表。onInputChanged()
事件负责填充这些建议,该事件接受当前用户输入和 suggestResult
对象。
sw-omnibox.js:
...
const URL_CHROME_EXTENSIONS_DOC =
'https://developer.chrome.com/docs/extensions/reference/';
const NUMBER_OF_PREVIOUS_SEARCHES = 4;
// Display the suggestions after user starts typing
chrome.omnibox.onInputChanged.addListener(async (input, suggest) => {
await chrome.omnibox.setDefaultSuggestion({
description: 'Enter a Chrome API or choose from past searches'
});
const { apiSuggestions } = await chrome.storage.local.get('apiSuggestions');
const suggestions = apiSuggestions.map((api) => {
return { content: api, description: `Open chrome.${api} API` };
});
suggest(suggestions);
});
用户选择某条建议后,onInputEntered()
会打开相应的 Chrome API 参考文档页面。
sw-omnibox.js:
...
// Open the reference page of the chosen API
chrome.omnibox.onInputEntered.addListener((input) => {
chrome.tabs.create({ url: URL_CHROME_EXTENSIONS_DOC + input });
// Save the latest keyword
updateHistory(input);
});
updateHistory()
函数会接受多功能框输入内容,并将其保存到 storage.local
。这样,Google 便可在日后将最近的搜索字词用作多功能框建议。
sw-omnibox.js:
...
async function updateHistory(input) {
const { apiSuggestions } = await chrome.storage.local.get('apiSuggestions');
apiSuggestions.unshift(input);
apiSuggestions.splice(NUMBER_OF_PREVIOUS_SEARCHES);
return chrome.storage.local.set({ apiSuggestions });
}
第 6 步:设置周期性活动
setTimeout()
或 setInterval()
方法通常用于执行延迟或定期任务。但是,这些 API 可能会失败,因为调度程序将在 Service Worker 终止时取消计时器。扩展程序可以使用 chrome.alarms
API。
首先在清单中请求 "alarms"
权限。此外,如需从远程托管位置提取扩展程序提示,您需要请求主机权限:
manifest.json:
{
...
"permissions": ["storage"],
"permissions": ["storage", "alarms"],
"host_permissions": ["https://extension-tips.glitch.me/*"],
}
该扩展程序会提取所有提示,随机挑选一个并将其保存到存储空间。我们将创建一个每天触发一次的闹钟来更新小费。关闭 Chrome 时不会保存闹钟。因此,我们需要检查闹钟是否存在,如果不存在,则需要创建一个。
sw-tips.js:
// Fetch tip & save in storage
const updateTip = async () => {
const response = await fetch('https://extension-tips.glitch.me/tips.json');
const tips = await response.json();
const randomIndex = Math.floor(Math.random() * tips.length);
return chrome.storage.local.set({ tip: tips[randomIndex] });
};
const ALARM_NAME = 'tip';
// Check if alarm exists to avoid resetting the timer.
// The alarm might be removed when the browser session restarts.
async function createAlarm() {
const alarm = await chrome.alarms.get(ALARM_NAME);
if (typeof alarm === 'undefined') {
chrome.alarms.create(ALARM_NAME, {
delayInMinutes: 1,
periodInMinutes: 1440
});
updateTip();
}
}
createAlarm();
// Update tip once a day
chrome.alarms.onAlarm.addListener(updateTip);
第 7 步:与其他上下文通信
扩展程序使用内容脚本读取和修改网页内容。当用户访问某个 Chrome API 参考页面时,该扩展程序的内容脚本将更新该页面,并提供当天提示。它会发送消息,以请求 Service Worker 提供当天小费。
首先,在清单中声明内容脚本,并添加与 Chrome API 参考文档对应的匹配模式。
manifest.json:
{
...
"content_scripts": [
{
"matches": ["https://developer.chrome.com/docs/extensions/reference/*"],
"js": ["content.js"]
}
]
}
创建新的内容文件。以下代码向 Service Worker 发送一条请求小费的消息。然后,添加一个按钮,点击该按钮即可打开包含扩展程序提示的弹出式窗口。此代码使用新的网络平台 Popover API。
content.js:
(async () => {
// Sends a message to the service worker and receives a tip in response
const { tip } = await chrome.runtime.sendMessage({ greeting: 'tip' });
const nav = document.querySelector('.upper-tabs > nav');
const tipWidget = createDomElement(`
<button type="button" popovertarget="tip-popover" popovertargetaction="show" style="padding: 0 12px; height: 36px;">
<span style="display: block; font: var(--devsite-link-font,500 14px/20px var(--devsite-primary-font-family));">Tip</span>
</button>
`);
const popover = createDomElement(
`<div id='tip-popover' popover style="margin: auto;">${tip}</div>`
);
document.body.append(popover);
nav.append(tipWidget);
})();
function createDomElement(html) {
const dom = new DOMParser().parseFromString(html, 'text/html');
return dom.body.firstElementChild;
}
最后一步是向我们的 Service Worker 添加一个消息处理程序,用来向内容脚本发送包含每日小费的回复。
sw-tips.js:
...
// Send tip to content script via messaging
chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
if (message.greeting === 'tip') {
chrome.storage.local.get('tip').then(sendResponse);
return true;
}
});
测试它是否正常运行
验证项目的文件结构是否如下所示:
在本地加载扩展程序
如需在开发者模式下加载已解压的扩展程序,请按照 Hello world 中的步骤操作。
打开参考页面
- 在浏览器地址栏中输入关键字“api”。
- 按“Tab”键或“空格键”。
- 输入 API 的完整名称。
- 或者从过往搜索记录列表中进行选择
- 系统会打开一个新的页面,显示 Chrome API 参考页面。
代码应如下所示:
![打开运行时 API 参考文档的快速 API 参考文档](https://developer.chrome.google.cn/static/docs/extensions/get-started/tutorial/service-worker-events/image/quick-api-reference-openi-5041b3b640769.gif?authuser=5&hl=sv)
打开今日提示
点击导航栏上的“提示”按钮,打开扩展程序提示。
![在以下时段打开每日提示:](https://developer.chrome.google.cn/static/docs/extensions/get-started/tutorial/service-worker-events/image/open-daily-tip-676249a78de8e.gif?authuser=5&hl=sv)
🎯? 潜在的增强功能
根据今天学到的知识,请尝试完成以下任何一项操作:
- 了解实现多功能框建议的其他方法。
- 创建您自己的自定义模态窗口,用于显示附加信息提示。
- 再打开一个指向 MDN 的 Web 扩展程序参考 API 页面的页面。
继续努力!
恭喜您学完了本教程 🎉?。通过完成其他初级教程继续提升您的技能:
扩展程序 | 学习内容 |
---|---|
阅读时间 | 在一组特定网页上自动插入元素。 |
标签页管理器 | 创建一个用于管理浏览器标签页的弹出式窗口。 |
专注模式 | 点击扩展程序操作后在当前页面上运行代码。 |
继续探索
若要继续学习扩展程序 Service Worker,建议您浏览以下文章: