使用 Service Worker 处理事件

介绍 Extensions Service Worker 概念的教程

概览

本教程介绍了 Chrome 扩展程序 Service Worker。在此过程中 您将构建一个扩展程序，让用户能够快速转到 Chrome API 参考文档 访问网页。您将学习如何：

• 注册 Service Worker 并导入模块。
• 调试扩展程序 Service Worker。
• 管理状态和处理事件。
• 触发周期性事件。
• 与内容脚本通信。

前期准备

本指南假定您具备基本的 Web 开发经验。我们建议您查看 扩展 101 和 Hello World。 扩展程序开发应用

构建扩展程序

首先创建一个名为 quick-api-reference 的新目录来保存扩展程序文件，或者 请从我们的 GitHub 示例代码库中下载源代码。

第 1 步：注册 Service Worker

在项目的根目录中创建 manifest 文件，并添加以下代码：

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 中导入多个文件的其他方法，请参阅导入脚本。

提示：在使用新式模块打包器框架（例如 CRXjs Vite 插件）时，请务必设置 "type.module"。

可选：调试 Service Worker

我将介绍如何查找 Service Worker 日志并了解其终止时间。首先，按照相关说明加载解压的扩展程序。

30 秒后，您将看到“Service Worker (inactive)”这意味着 Service Worker 已终止。点击“Service Worker (inactive)”链接进行检查。下面的动画展示了这种情况。

您是否注意到检查 Service Worker 将它唤醒了？在 Devtools 中打开 Service Worker 可使其保持活动状态。为确保您的扩展程序在 Service Worker 终止后正常运行，请务必关闭 DevTools。

现在，您需要终止扩展程序，以了解在哪里可以找到错误。一种方法是删除“.js”（从 service-worker.js 文件的 './sw-omnibox.js' 导入中）。Chrome 将无法注册 Service Worker。

返回 chrome://extensions，然后刷新扩展程序。您会看到两个错误：

Service worker registration failed. Status code: 3.

An unknown error occurred when fetching the script.

如需了解调试扩展程序 Service Worker 的更多方法，请参阅调试扩展程序。

注意：请务必先修正文件名，然后再继续操作。

第 4 步：初始化状态

如果不需要 Service Worker，Chrome 会关闭它们。我们使用 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 对象，因此无法使用 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"
  },
}

要点："minimum_chrome_version" 参考文档介绍了当用户尝试安装您的扩展程序但使用的并非兼容的 Chrome 版本时，此密钥的行为方式。

现在，在脚本的顶层注册多功能框事件监听器。如果用户在地址栏中输入多功能框关键字 (api)，然后按 Tab 键或空格，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。这样，系统以后便可将最近的搜索字词用作多功能框建议。

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

要点：扩展程序 Service Worker 可以使用 Web API 和 Chrome API，但有几个例外情况。如需了解详情，请参阅 Service Worker 事件。

第 6 步：设置周期性活动

setTimeout() 或 setInterval() 方法通常用于执行延迟或定期操作 任务。不过，这些 API 可能会失败，因为调度程序会在服务调用时取消计时器， 工作器终止。扩展程序可以改用 chrome.alarms API。

首先，在清单中请求 "alarms" 权限。此外，如需从远程托管位置提取扩展程序提示，您需要请求主机权限：

manifest.json:

{
  ...
  "permissions": ["storage"],
  "permissions": ["storage", "alarms"],
  "host_permissions": ["https://extension-tips.glitch.me/*"],
}

该扩展程序会提取所有提示，随机选择一个提示并将其保存到存储空间。我们将创建一个每天触发一次的闹钟，用于更新小费。关闭 Chrome 后，系统不会保存闹钟。我们需要检查 alarm 是否存在，如果不存在，则创建它。

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

要点：所有 Chrome API 事件监听器和方法都会重启 Service Worker 的 30 秒终止计时器。如需了解详情，请参阅 Extension Service Worker 生命周期。

第 7 步：与其他情境通信

扩展程序使用内容脚本读取和修改网页内容。当用户访问某个 Chrome API 参考页面时，该扩展程序的内容脚本会根据当天的提示更新该页面。它发送消息以向 Service Worker 请求当天的小费。

首先在清单中声明内容脚本，并添加与 Chrome API 参考文档对应的匹配模式。

manifest.json:

{
  ...
  "content_scripts": [
    {
      "matches": ["https://developer.chrome.com/docs/extensions/reference/*"],
      "js": ["content.js"]
    }
  ]
}

创建新的内容文件。以下代码会向 Service Worker 发送一条请求小费的消息。然后，添加一个按钮，用于打开包含扩展程序提示的弹出式窗口。此代码使用新的 Web 平台 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 中的步骤进行操作。

打开参考页面

1. 请输入关键字“api”。
2. 按“Tab”键或“空格”。
3. 输入 API 的完整名称。
   • 或从过往搜索记录列表中选择
4. 此时，系统会打开一个新的 Chrome API 参考页面。

它应如下所示：

<ph type="x-smartling-placeholder">

</ph> <ph type="x-smartling-placeholder">

</ph> 用于打开 Runtime API 的快速 API 扩展程序。

打开今日提示

点击导航栏上的“Tip”（提示）按钮，打开扩展程序提示。

<ph type="x-smartling-placeholder">

</ph> <ph type="x-smartling-placeholder">

</ph> 用于打开今日提示的快速 API 扩展程序。

。

注意：Popover API 是在 Chrome 114 中发布的。

🎯? 提升潜力

根据您今天学到的知识，尝试完成以下任一操作：

• 了解实施多功能框建议的其他方式。
• 创建自己的自定义模态，以显示扩展程序提示。
• 打开指向 MDN 的 Web Extensions 参考 API 页面的另一个页面。

继续努力！

恭喜您学完本教程 🎉?。通过完成其他课程来继续提升技能 新手教程：

扩展程序	学习内容
阅读时间	在一组特定页面上自动插入元素。
标签页管理器	创建用于管理浏览器标签页的弹出式窗口。
专注模式	点击扩展程序操作后在当前网页上运行代码。

继续探索

要继续学习您的 Extensions Service Worker 学习路线，我们建议您浏览以下文章：

• 扩展程序 Service Worker 简介。
• 扩展程序 Service Worker 生命周期。
• Service Worker 中的事件