訊息 API 可讓您在與擴充功能相關聯的環境中執行的不同指令碼之間進行通訊。包括 Service Worker、chrome-extension://pages 和內容指令碼之間的通訊。舉例來說,RSS 閱讀器擴充功能可能會使用內容指令碼偵測網頁上是否有 RSS 動態消息,然後通知 Service Worker 更新該網頁的動作圖示。
訊息傳遞 API 有兩種:一種用於一次性要求,另一種較複雜,用於長期連線,可傳送多則訊息。
如要瞭解如何在擴充功能之間傳送訊息,請參閱「跨擴充功能訊息」一節。
一次性要求
如要將單一訊息傳送至擴充功能的其他部分,並視需要取得回應,請呼叫 runtime.sendMessage() 或 tabs.sendMessage()。這些方法可讓您從內容指令碼傳送一次性 JSON 可序列化訊息至擴充功能,或從擴充功能傳送至內容指令碼。這兩個 API 都會傳回 Promise,解析為接收端提供的回應。
從內容指令碼傳送要求的方式如下:
content-script.js:
(async () => {
const response = await browser.runtime.sendMessage({greeting: "hello"});
// do something with response here, not outside the function
console.log(response);
})();
回應
如要監聽訊息,請使用 browser.runtime.onMessage 事件:
// Event listener
function handleMessages(message, sender, sendResponse) {
if (message !== 'get-status') return;
fetch('https://example.com')
.then((response) => sendResponse({statusCode: response.status}))
// Since `fetch` is asynchronous, must return an explicit `true`
return true;
}
browser.runtime.onMessage.addListener(handleMessages);
// From the sender's context...
const {statusCode} = await browser.runtime.sendMessage('get-status');
呼叫事件監聽器時,系統會將 sendResponse 函式做為第三個參數傳遞。這個函式可呼叫來提供回應。根據預設,sendResponse 回呼必須同步呼叫。
如果呼叫 sendResponse 時未提供任何參數,系統會傳送 null 做為回應。
如要以非同步方式傳送回應,有兩種做法:傳回 true 或傳回 Promise。
傳回 true
如要使用 sendResponse() 以非同步方式回應,請從事件監聽器傳回常值 true (不只是 truthy 值)。這樣一來,訊息管道會保持開啟,直到呼叫 sendResponse 為止,讓您稍後可以呼叫。
傳回 Promise
從 Chrome 148 開始,您可以從訊息監聽器傳回 Promise,以非同步方式回應。這項更新會逐步推出,因此部分使用者的瀏覽器可能還無法使用。請務必確保擴充功能可以處理這項功能是否啟用。無論是否啟用這項功能,使用 return true; 仍可繼續處理非同步回應。
如果 Promise 解析,解析的值會做為回應傳送。
如果承諾遭拒,傳送者的 sendMessage() 呼叫會遭到拒絕,並顯示錯誤訊息。詳情和範例請參閱錯誤處理一節。
以下範例說明如何傳回可能解析或拒絕的 Promise:
// Event listener
function handleMessages(message, sender, sendResponse) {
// Return a promise that wraps fetch
// If the response is OK, resolve with the status. If it's not OK then reject
// with the network error that prevents the fetch from completing.
return new Promise((resolve, reject) => {
fetch('https://example.com')
.then(response => {
if (!response.ok) {
reject(response);
} else {
resolve(response.status);
}
})
.catch(error => {
reject(error);
});
});
}
browser.runtime.onMessage.addListener(handleMessages);
您也可以將事件監聽器宣告為 async,以傳回 Promise:
browser.runtime.onMessage.addListener(async function(message, sender) {
const response = await fetch('https://example.com');
if (!response.ok) {
// rejects the promise returned by `async function`.
throw new Error(`Fetch failed: ${response.status}`);
}
// resolves the promise returned by `async function`.
return {statusCode: response.status};
});
傳回 Promise:async 函式注意事項
請注意,即使沒有 return 陳述式,async 函式做為事件監聽器時,也「一律」會傳回 Promise。如果 async 事件監聽器未傳回值,其 Promise 會隱含解析為 undefined,並將 null 做為回應傳送給傳送者。如果有多個事件監聽器,可能會導致非預期的行為:
// content_script.js
function handleResponse(message) {
// The first listener promise resolves to `undefined` before the second
// listener can respond. When a listener responds with `undefined`, Chrome
// sends null as the response.
console.assert(message === null);
}
function notifyBackgroundPage() {
const sending = browser.runtime.sendMessage('test');
sending.then(handleResponse);
}
notifyBackgroundPage();
// background.js
browser.runtime.onMessage.addListener(async (message) => {
// This just causes the function to pause for a millisecond, but the promise
// is *not* returned from the listener so it doesn't act as a response.
await new Promise(resolve => {
setTimeout(resolve, 1, 'OK');
});
// `async` functions always return promises. So once we
// reach here there is an implicit `return undefined;`. Chrome translates
// `undefined` responses to `null`.
});
browser.runtime.onMessage.addListener((message, sender, sendResponse) => {
return new Promise((resolve) => {
setTimeout(resolve, 1000, 'response');
});
});
錯誤處理
從 Chrome 146 開始,如果 onMessage 監聽器擲回錯誤 (同步或非同步,透過傳回拒絕的 Promise),傳送端中 sendMessage() 傳回的 Promise 會拒絕,並顯示錯誤訊息。這項更新正逐步推出,因此您可能會發現這項變更尚未在所有使用者的瀏覽器中生效。請務必確保擴充功能可以處理這項變更是否啟用。
如果事件監聽器嘗試傳回無法序列化的回應 (未擷取產生的 TypeError),也會視為事件監聽器擲回錯誤。
如果事件監聽器傳回遭拒的 Promise,則必須使用 Error 執行個體拒絕,傳送端才能收到錯誤訊息。如果承諾因任何其他值 (例如 null 或 undefined) 而遭拒,sendMessage() 則會改為因一般錯誤訊息而遭拒。
如果為 onMessage 註冊多個監聽器,只有第一個回應、拒絕或擲回錯誤的監聽器會影響傳送端;所有其他監聽器都會執行,但系統會忽略其結果。
範例
如果事件監聽器傳回遭拒的 Promise,sendMessage() 也會遭拒:
// sender.js
try {
await browser.runtime.sendMessage('test');
} catch (e) {
console.log(e.message); // "some error"
}
// listener.js
browser.runtime.onMessage.addListener((message, sender, sendResponse) => {
return Promise.reject(new Error('some error'));
});
如果事件監聽器回應的值無法序列化,系統會拒絕 sendMessage():
// sender.js
try {
await browser.runtime.sendMessage('test');
} catch (e) {
console.log(e.message); // "Error: Could not serialize message."
}
// listener.js
browser.runtime.onMessage.addListener((message, sender, sendResponse) => {
sendResponse(() => {}); // Functions are not serializable
return true; // Keep channel open for async sendResponse
});
如果事件監聽器在其他事件監聽器回應前同步擲回錯誤,系統會拒絕事件監聽器的 sendMessage() 承諾:
// sender.js
try {
await browser.runtime.sendMessage('test');
} catch (e) {
console.log(e.message); // "error!"
}
// listener.js
browser.runtime.onMessage.addListener((message, sender, sendResponse) => {
throw new Error('error!');
});
不過,如果其中一個事件監聽器在另一個事件監聽器擲回錯誤前回應,sendMessage() 就會成功:
// sender.js
const response = await browser.runtime.sendMessage('test');
console.log(response); // "OK"
// listener.js
browser.runtime.onMessage.addListener((message, sender, sendResponse) => {
sendResponse('OK');
});
browser.runtime.onMessage.addListener((message, sender, sendResponse) => {
throw new Error('error!');
});
長期連線
如要建立可重複使用的長效訊息傳遞管道,請呼叫:
runtime.connect():將訊息從內容指令碼傳遞至擴充功能頁面tabs.connect():將訊息從擴充功能頁面傳遞至內容指令碼。
您可以傳遞含有 name 鍵的選項參數,為管道命名,以區分不同類型的連線:
const port = browser.runtime.connect({name: "example"});
長效連線的可能用途之一是自動填寫表單的擴充功能。內容指令碼可能會為特定登入開啟擴充功能頁面的管道,並針對頁面上的每個輸入元素向擴充功能傳送訊息,要求填入表單資料。共用連線可讓擴充功能在擴充功能元件之間共用狀態。
建立連線時,系統會為每一端指派 runtime.Port 物件,用於透過該連線傳送及接收訊息。
請使用下列程式碼,從內容指令碼開啟管道,並傳送及監聽訊息:
content-script.js:
const port = browser.runtime.connect({name: "knockknock"});
port.onMessage.addListener(function(msg) {
if (msg.question === "Who's there?") {
port.postMessage({answer: "Madame"});
} else if (msg.question === "Madame who?") {
port.postMessage({answer: "Madame... Bovary"});
}
});
port.postMessage({joke: "Knock knock"});
如要從擴充功能傳送要求至內容指令碼,請將前一個範例中對 runtime.connect() 的呼叫替換為 tabs.connect()。
如要處理內容指令碼或擴充功能頁面的傳入連線,請設定 runtime.onConnect 事件監聽器。當擴充功能的其他部分呼叫 connect() 時,就會啟用這個事件和 runtime.Port 物件。回應傳入連線的程式碼如下所示:
service-worker.js:
browser.runtime.onConnect.addListener(function(port) {
if (port.name !== "knockknock") {
return;
}
port.onMessage.addListener(function(msg) {
if (msg.joke === "Knock knock") {
port.postMessage({question: "Who's there?"});
} else if (msg.answer === "Madame") {
port.postMessage({question: "Madame who?"});
} else if (msg.answer === "Madame... Bovary") {
port.postMessage({question: "I don't get it."});
}
});
});
序列化
在 Chrome 中,訊息傳遞 API 會使用 JSON 序列化。值得注意的是,這與其他使用結構化複製演算法實作相同 API 的瀏覽器不同。
也就是說,訊息 (和收件者提供的回覆) 可以包含任何有效的 JSON.stringify() 值。其他值會強制轉型為可序列化的值 (特別是 undefined 會序列化為 null);
郵件大小限制
訊息大小上限為 64 MiB。
通訊埠生命週期
通訊埠是擴充功能不同部分之間的雙向通訊機制。當擴充功能的一部分呼叫 tabs.connect()、runtime.connect() 或 runtime.connectNative() 時,會建立 Port,可立即使用 postMessage() 傳送訊息。
如果分頁中有多個頁框,呼叫 tabs.connect() 會為分頁中的每個頁框叫用一次 runtime.onConnect 事件。同樣地,如果呼叫 runtime.connect(),則擴充功能程序中的每個頁框都可以觸發一次 onConnect 事件。
您可能想知道連線何時關閉,例如,如果您為每個開啟的通訊埠維護個別狀態。方法是監聽 runtime.Port.onDisconnect 事件。如果管道另一端沒有有效通訊埠,就會觸發這個事件,原因可能包括:
- 另一端沒有
runtime.onConnect的事件監聽器。 - 含有通訊埠的分頁已卸載 (例如分頁已導覽)。
- 呼叫
connect()的頁框已卸載。 - 所有接收通訊埠 (透過
runtime.onConnect) 的框架都已卸載。 runtime.Port.disconnect()是由另一端呼叫。如果connect()呼叫在接收端產生多個通訊埠,且在其中任何一個通訊埠上呼叫disconnect(),則onDisconnect事件只會在傳送通訊埠觸發,而不會在其他通訊埠觸發。
跨擴充功能訊息
除了在擴充功能的不同元件之間傳送訊息,您也可以使用訊息 API 與其他擴充功能通訊。這樣一來,您就能公開 API,供其他擴充功能使用。
如要監聽來自其他擴充功能的連入要求和連線,請使用 runtime.onMessageExternal 或 runtime.onConnectExternal 方法。以下是各項的範例:
service-worker.js
// For a single request:
browser.runtime.onMessageExternal.addListener(
function(request, sender, sendResponse) {
if (sender.id !== allowlistedExtension) {
return; // don't allow this extension access
}
if (request.getTargetData) {
sendResponse({ targetData: targetData });
} else if (request.activateLasers) {
const success = activateLasers();
sendResponse({ activateLasers: success });
}
}
);
// For long-lived connections:
browser.runtime.onConnectExternal.addListener(function(port) {
port.onMessage.addListener(function(msg) {
// See other examples for sample onMessage handlers.
});
});
如要傳送訊息給其他擴充功能,請傳遞要通訊的擴充功能 ID,如下所示:
service-worker.js
// The ID of the extension we want to talk to.
const laserExtensionId = "abcdefghijklmnoabcdefhijklmnoabc";
// For a minimal request:
browser.runtime.sendMessage(laserExtensionId, {getTargetData: true},
function(response) {
if (targetInRange(response.targetData))
browser.runtime.sendMessage(laserExtensionId, {activateLasers: true});
}
);
// For a long-lived connection:
const port = browser.runtime.connect(laserExtensionId);
port.postMessage(...);
從網頁傳送訊息
擴充功能也可以接收及回應來自網頁的訊息。如要從網頁傳送訊息至擴充功能,請在 manifest.json 中使用 "externally_connectable" 資訊清單金鑰,指定要允許哪些網站傳送訊息。例如:
manifest.json
"externally_connectable": {
"matches": ["https://*.example.com/*"]
}
這會將訊息 API 公開給符合您指定比對模式的任何網頁。
使用 runtime.sendMessage() 或 runtime.connect() API 將訊息傳送至特定擴充功能。例如:
webpage.js
// The ID of the extension we want to talk to.
const editorExtensionId = 'abcdefghijklmnoabcdefhijklmnoabc';
// Check if extension is installed
if (chrome && browser.runtime) {
// Make a request:
browser.runtime.sendMessage(
editorExtensionId,
{
openUrlInEditor: url
},
(response) => {
if (!response.success) handleError(url);
}
);
}
在擴充功能中,使用 runtime.onMessageExternal 或 runtime.onConnectExternal API 監聽網頁訊息,如跨擴充功能訊息。範例如下:
service-worker.js
browser.runtime.onMessageExternal.addListener(
function(request, sender, sendResponse) {
if (sender.url === blocklistedWebsite)
return; // don't allow this web page access
if (request.openUrlInEditor)
openUrl(request.openUrlInEditor);
});
無法從擴充功能傳送訊息到網頁。
原生訊息傳遞
擴充功能可以與註冊為 內建訊息傳遞主機的原生應用程式交換訊息。如要進一步瞭解這項功能,請參閱「原生訊息」。
安全性考量
以下是與訊息功能相關的幾項安全性考量。
內容指令碼的可信度較低
內容指令碼的可信度低於擴充功能 Service Worker。舉例來說,惡意網頁可能會破壞執行內容指令碼的轉譯器程序。假設內容指令碼中的訊息可能由攻擊者製作,並務必驗證及清理所有輸入內容。假設傳送至內容指令碼的任何資料都可能外洩至網頁。限制從內容指令碼收到的訊息可觸發的特殊權限動作範圍。
跨網站指令碼攻擊
請務必保護指令碼,防範跨網站指令碼攻擊。從不受信任的來源 (例如使用者輸入內容、其他網站透過內容指令碼或 API) 接收資料時,請務必避免將其解讀為 HTML,或以可能允許執行非預期程式碼的方式使用。
盡可能使用不執行指令碼的 API:
service-worker.js
browser.tabs.sendMessage(tab.id, {greeting: "hello"}, function(response) { // JSON.parse doesn't evaluate the attacker's scripts. const resp = JSON.parse(response.farewell); });
service-worker.js
browser.tabs.sendMessage(tab.id, {greeting: "hello"}, function(response) { // innerText does not let the attacker inject HTML elements. document.getElementById("resp").innerText = response.farewell; });
請避免使用下列方法,以免擴充功能容易受到攻擊:
service-worker.js
browser.tabs.sendMessage(tab.id, {greeting: "hello"}, function(response) { // WARNING! Might be evaluating a malicious script! const resp = eval(`(${response.farewell})`); });
service-worker.js
browser.tabs.sendMessage(tab.id, {greeting: "hello"}, function(response) { // WARNING! Might be injecting a malicious script! document.getElementById("resp").innerHTML = response.farewell; });