透過服務工作站處理事件

說明擴充功能 Service Worker 概念的教學課程

總覽

本教學課程提供 Chrome 擴充功能服務 Worker 的簡介。在本教學課程中，您將建構擴充功能，讓使用者能使用網址列快速前往 Chrome API 參考資料頁面。您將學習以下內容：

• 註冊 Service Worker 並匯入模組。
• 對擴充功能 Service Worker 進行偵錯。
• 管理狀態及處理事件。
• 觸發定期事件。
• 與內容腳本通訊。

事前準備

本指南假設您具備基本的網頁開發經驗。建議您查看「擴充功能 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 模組

我們的服務工作處理程序會導入兩項功能。為提高可維護性，我們會在個別的模組中實作各項功能。首先，我們必須在資訊清單中宣告服務工作處理程序為 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 (非使用中)」連結進行檢查。請見下方動畫。

檢查 Service Worker 後，有沒有註意到服務 worker 已將其喚醒？在開發人員工具中開啟 Service Worker，讓服務工作站保持啟用狀態。為了確保擴充功能在服務工作處理程序終止時正常運作，請記得關閉開發人員工具。

現在，請破壞擴充功能，瞭解如何找出錯誤。其中一種方法是從 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 儲存值。此外，服務工作站是短期的執行環境；在使用者的瀏覽器工作階段中會不斷終止，導致他們與全域變數不相容。請改用 chrome.storage.local，將資料儲存在本機電腦。

如要瞭解擴充功能服務工作站的其他儲存空間選項，請參閱保留資料，而不是使用全域變數。

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

重點：擴充功能服務工作站可以使用網路 API 和 Chrome API，但有少數例外，詳情請參閱服務工作站事件。

步驟 6：設定週期性活動

setTimeout() 或 setInterval() 方法常用於執行延遲或週期性工作。不過，這些 API 可能會失敗，因為排程器會在服務工作站終止時取消計時器。擴充功能可以改用 chrome.alarms API。

首先，請在資訊清單中要求 "alarms" 權限。此外，如要從遠端代管位置擷取擴充功能提示，您必須要求主機權限：

manifest.json:

{
  ...
  "permissions": ["storage", "alarms"],
  "permissions": ["storage"],
  "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);

重點提示：所有 Chrome API 事件監聽器和方法都會重新啟動 Service Worker 的 30 秒終止計時器。詳情請參閱擴充功能服務工作站生命週期。

步驟 7：與其他情境溝通

擴充功能會使用內容指令碼讀取及修改網頁內容。使用者造訪 Chrome API 參考頁面時，擴充功能的內容指令碼會更新網頁，顯示當日的小費。而是傳送訊息，向服務工作人員要求當天的小費。

首先，在資訊清單中宣告內容指令碼，然後新增與 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;
}

最後一步是將訊息處理常式新增至服務工作處理程序，以傳送每日小費的回覆內容指令碼。

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 參考資料頁面。

看起來應該像這樣：

開啟 Runtime API 的 Quick API 擴充功能。

開啟當天小費

按一下導覽列上的「提示」按鈕，即可開啟擴充功能提示。

開啟 Quick API 擴充功能，打開當日小秘訣。

注意：Popover API 已於 Chrome 114 推出。

🎯? 可能的強化項目

根據今天學到的知識，您可以試著完成下列任一步驟：

• 請探索其他實作網址列建議的方式。
• 建立自訂互動視窗來顯示擴充功能提示。
• 開啟可前往 MDN 的 Web Extensions 參考 API 頁面的額外頁面。

繼續建構！

恭喜您完成本教學課程 🎉?。請完成其他新手教學課程，繼續精進您的技能：

延伸	學習目標
閱讀時間	在特定一組網頁上自動插入元素。
分頁管理工具	建立用於管理瀏覽器分頁的彈出式視窗。
專注模式	點按擴充功能動作後，可在目前網頁上執行程式碼。

繼續探索

如要繼續進行擴充功能服務員工學習路徑，建議您瀏覽下列文章：

• 關於擴充功能 Service Worker。
• 擴充功能服務工作站生命週期。
• Service Worker 中的事件