說明擴充功能 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 中匯入多個檔案的其他方式,請參閱匯入指令碼。
選用:對 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"
},
}
現在,請在指令碼的頂層註冊網址列事件監聽器。當使用者在網址列中輸入網址列關鍵字 (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 });
}
步驟 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);
步驟 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 中的步驟操作。
開啟參考資料頁面
- 在瀏覽器網址列中輸入關鍵字「api」。
- 按下「Tab 鍵」或「空格鍵」。
- 輸入 API 的完整名稱。
- 或從搜尋記錄清單中選擇
- 系統會開啟新的 Chrome API 參考資料頁面。
看起來應該像這樣:
開啟當天小費
按一下導覽列上的「提示」按鈕,即可開啟擴充功能提示。
🎯? 可能的強化項目
根據今天學到的知識,您可以試著完成下列任一步驟:
- 請探索其他實作網址列建議的方式。
- 建立自訂互動視窗來顯示擴充功能提示。
- 開啟可前往 MDN 的 Web Extensions 參考 API 頁面的額外頁面。
繼續建構!
恭喜您完成本教學課程 🎉?。請完成其他新手教學課程,繼續精進您的技能:
延伸 | 學習目標 |
---|---|
閱讀時間 | 在特定一組網頁上自動插入元素。 |
分頁管理工具 | 建立用於管理瀏覽器分頁的彈出式視窗。 |
專注模式 | 點按擴充功能動作後,可在目前網頁上執行程式碼。 |
繼續探索
如要繼續進行擴充功能服務員工學習路徑,建議您瀏覽下列文章: