說明
使用 chrome.action API 控制 Google Chrome 工具列中的擴充功能圖示。
可用性
資訊清單
如要使用 browser.action API，請指定 3 的 "manifest_version"，並在資訊清單檔案中加入 "action" 鍵。
{
"name": "Action Extension",
...
"action": {
"default_icon": { // optional
"16": "images/icon16.png", // optional
"24": "images/icon24.png", // optional
"32": "images/icon32.png" // optional
},
"default_title": "Click Me", // optional, shown in tooltip
"default_popup": "popup.html" // optional
},
...
}
"action" 鍵 (及其子項) 為選用項目。如果未加入，擴充功能仍會顯示在工具列中，方便使用者存取擴充功能選單。因此，建議您一律至少加入 "action" 和 "default_icon" 鍵。
概念和用途
UI 的各個部分
圖示
圖示是擴充功能工具列上的主要圖片，由資訊清單 "action" 鍵中的 "default_icon" 鍵設定。圖示的寬度和高度必須為 16 密度獨立像素 (DIP)。
"default_icon" 鍵是大小與圖片路徑的字典。Chrome 會使用這些圖示來選擇要使用的圖片比例。如果找不到完全相符的結果，Chrome 會選取最接近的可用結果，並縮放至符合圖片大小，這可能會影響圖片品質。
由於 1.5 倍或 1.2 倍等較不常見的縮放比例係數裝置越來越普遍，建議您為圖示提供多種大小。這也能確保擴充功能在未來圖示顯示大小可能變更時，仍能正常運作。不過，如果只提供單一大小，"default_icon" 鍵也可以設為包含單一圖示路徑的字串，而非字典。
您也可以呼叫 action.setIcon()，透過程式輔助方式設定擴充功能圖示，方法是指定不同的圖片路徑，或使用 HTML 畫布元素提供動態產生的圖示，或使用 offscreen canvas API (如果從擴充功能 Service Worker 設定)。
const canvas = new OffscreenCanvas(16, 16);
const context = canvas.getContext('2d');
context.clearRect(0, 0, 16, 16);
context.fillStyle = '#00FF00'; // Green
context.fillRect(0, 0, 16, 16);
const imageData = context.getImageData(0, 0, 16, 16);
browser.action.setIcon({imageData: imageData}, () => { /* ... */ });
如果是封裝擴充功能 (從 .crx 檔案安裝)，圖片可以採用 Blink 轉譯引擎可顯示的大多數格式，包括 PNG、JPEG、BMP、ICO 等。不支援 SVG。 未封裝的擴充功能必須使用 PNG 圖片。
工具提示 (標題)
當使用者將滑鼠游標懸停在工具列中的擴充功能圖示上時，就會顯示工具提示或標題。當按鈕獲得焦點時，螢幕閱讀器也會讀出這段文字。
預設工具提示是使用 manifest.json 中 "action" 鍵的 "default_title" 欄位設定。您也可以呼叫 action.setTitle()，透過程式輔助方式設定。
徽章
動作可以選擇顯示「徽章」，也就是疊加在圖示上的文字。這樣一來，您就能更新動作，顯示少量的擴充功能狀態資訊，例如計數器。徽章包含文字元件和背景顏色。由於空間有限，建議徽章文字使用四個或更少的字元。
如要建立徽章，請呼叫 action.setBadgeBackgroundColor() 和 action.setBadgeText()，以程式輔助方式設定。資訊清單中沒有預設徽章設定。徽章顏色值可以是四個介於 0 到 255 之間的整數組成的陣列，構成徽章的 RGBA 顏色，也可以是包含 CSS 顏色值的字串。
browser.action.setBadgeBackgroundColor(
{color: [0, 255, 0, 0]}, // Green
() => { /* ... */ },
);
browser.action.setBadgeBackgroundColor(
{color: '#00FF00'}, // Also green
() => { /* ... */ },
);
browser.action.setBadgeBackgroundColor(
{color: 'green'}, // Also, also green
() => { /* ... */ },
);
彈出式廣告
使用者點選工具列中的擴充功能動作按鈕時，系統會顯示動作的彈出式視窗。彈出式視窗可包含任何 HTML 內容，並會自動調整大小以符合內容。彈出式視窗的大小必須介於 25x25 至 800x600 像素之間。
彈出式視窗一開始是由 manifest.json 檔案中 "action" 鍵的 "default_popup" 屬性設定。如有這項屬性，應指向擴充功能目錄中的相對路徑。您也可以使用 action.setPopup() 方法動態更新，指向不同的相對路徑。
用途
各分頁狀態
擴充功能動作在每個分頁中可能會有不同的狀態。如要設定個別分頁的值，請在 action API 的設定方法中使用 tabId 屬性。舉例來說，如要設定特定分頁的徽章文字，請執行下列操作：
function getTabId() { /* ... */}
function getTabBadge() { /* ... */}
browser.action.setBadgeText(
{
text: getTabBadge(tabId),
tabId: getTabId(),
},
() => { ... }
);
如果省略 tabId 屬性，系統會將該設定視為全域設定。分頁專屬設定的優先順序高於全域設定。
啟用狀態
根據預設，每個分頁都會啟用工具列動作 (可點選)。如要變更這項預設值，請在資訊清單的 action 鍵中設定 default_state 屬性。如果 default_state 設為 "disabled"，動作預設為停用，必須透過程式輔助方式啟用，才能點選。如果 default_state 設為 "enabled" (預設)，則動作預設為啟用且可點選。
您可以使用 action.enable() 和 action.disable() 方法，透過程式輔助方式控制狀態。這只會影響是否將彈出式視窗 (如有) 或 action.onClicked 事件傳送至擴充功能，不會影響動作在工具列中的顯示。
範例
以下範例說明擴充功能中常見的動作使用方式。如要試用這個 API，請從 chrome-extension-samples 存放區安裝 Action API 範例。
顯示彈出式視窗
使用者點選擴充功能動作時，擴充功能通常會顯示彈出式視窗。如要在自己的擴充功能中實作這項功能，請在 manifest.json 中宣告彈出式視窗，並指定 Chrome 應在彈出式視窗中顯示的內容。
// manifest.json
{
"name": "Action popup demo",
"version": "1.0",
"manifest_version": 3,
"action": {
"default_title": "Click to view a popup",
"default_popup": "popup.html"
}
}
<!-- popup.html -->
<!DOCTYPE html>
<html>
<head>
<style>
html {
min-height: 5em;
min-width: 10em;
background: salmon;
}
</style>
</head>
<body>
<p>Hello, world!</p>
</body>
</html>
點選時插入內容指令碼
擴充功能的常見模式是使用擴充功能的動作，公開其主要功能。以下範例說明瞭這個模式。使用者點選動作時，擴充功能會將內容指令碼插入目前頁面。接著，內容指令碼會顯示快訊，確認一切運作正常。
// manifest.json
{
"name": "Action script injection demo",
"version": "1.0",
"manifest_version": 3,
"action": {
"default_title": "Click to show an alert"
},
"permissions": ["activeTab", "scripting"],
"background": {
"service_worker": "background.js"
}
}
// background.js
browser.action.onClicked.addListener((tab) => {
browser.scripting.executeScript({
target: {tabId: tab.id},
files: ['content.js']
});
});
// content.js
alert('Hello, world!');
使用 declarativeContent 模擬動作
這個範例說明擴充功能的背景邏輯如何 (a) 預設停用動作，以及 (b) 使用 declarativeContent 在特定網站上啟用動作。
// service-worker.js
// Wrap in an onInstalled callback to avoid unnecessary work
// every time the service worker is run
browser.runtime.onInstalled.addListener(() => {
// Page actions are disabled by default and enabled on select tabs
browser.action.disable();
// Clear all rules to ensure only our expected rules are set
browser.declarativeContent.onPageChanged.removeRules(undefined, () => {
// Declare a rule to enable the action on example.com pages
let exampleRule = {
conditions: [
new browser.declarativeContent.PageStateMatcher({
pageUrl: {hostSuffix: '.example.com'},
})
],
actions: [new browser.declarativeContent.ShowAction()],
};
// Finally, apply our new array of rules
let rules = [exampleRule];
browser.declarativeContent.onPageChanged.addRules(rules);
});
});
類型
OpenPopupOptions
屬性
-
windowId
數字 選填
要在其中開啟動作彈出式視窗的視窗 ID。如未指定，則預設為目前使用中的視窗。
TabDetails
屬性
-
tabId
數字 選填
要查詢狀態的分頁 ID。如未指定分頁，系統會傳回非分頁專屬狀態。
UserSettings
使用者指定設定的集合，與擴充功能動作相關。
屬性
-
isOnToolbar
布林值
擴充功能的動作圖示是否顯示在瀏覽器視窗的頂層工具列 (即使用者是否已「固定」擴充功能)。
UserSettingsChange
屬性
-
isOnToolbar
布林值 選填
擴充功能的動作圖示是否顯示在瀏覽器視窗的頂層工具列 (即使用者是否已「固定」擴充功能)。
方法
disable()
browser.action.disable(
tabId?: number,
): Promise<void>
停用分頁動作。
參數
-
tabId
數字 選填
要修改動作的分頁 ID。
傳回
-
承諾<void>
enable()
browser.action.enable(
tabId?: number,
): Promise<void>
啟用分頁動作。根據預設，系統會啟用動作。
參數
-
tabId
數字 選填
要修改動作的分頁 ID。
傳回
-
承諾<void>
getBadgeBackgroundColor()
browser.action.getBadgeBackgroundColor(
details: TabDetails,
): Promise<extensionTypes.ColorArray>
取得動作的背景顏色。
參數
-
詳細資料
傳回
-
Promise<extensionTypes.ColorArray>
getBadgeText()
browser.action.getBadgeText(
details: TabDetails,
): Promise<string>
取得動作的徽章文字。如未指定分頁，系統會傳回非分頁專屬的徽章文字。如果啟用 displayActionCountAsBadgeText，除非有 declarativeNetRequestFeedback 權限或提供分頁專屬標記文字，否則會傳回預留位置文字。
參數
-
詳細資料
傳回
-
Promise<string>
getBadgeTextColor()
browser.action.getBadgeTextColor(
details: TabDetails,
): Promise<extensionTypes.ColorArray>
取得動作的文字顏色。
參數
-
詳細資料
傳回
-
Promise<extensionTypes.ColorArray>
參數
-
詳細資料
傳回
-
Promise<string>
參數
-
詳細資料
傳回
-
Promise<string>
getUserSettings()
browser.action.getUserSettings(): Promise<UserSettings>
傳回與擴充功能動作相關的使用者指定設定。
傳回
-
Promise<UserSettings>
isEnabled()
browser.action.isEnabled(
tabId?: number,
): Promise<boolean>
指出是否為分頁啟用擴充功能動作 (如未提供 tabId，則為全域啟用)。如果只使用 declarativeContent 啟用動作，一律會傳回 false。
參數
-
tabId
數字 選填
要檢查啟用狀態的分頁 ID。
傳回
-
Promise<boolean>
openPopup()
browser.action.openPopup(
options?: OpenPopupOptions,
): Promise<void>
開啟擴充功能的彈出式視窗。在 Chrome 118 到 Chrome 126 之間，只有透過政策安裝的擴充功能才能使用這項功能。
參數
-
選項
指定開啟彈出式視窗的選項。
傳回
-
承諾<void>
setBadgeBackgroundColor()
browser.action.setBadgeBackgroundColor(
details: object,
): Promise<void>
設定徽章的背景顏色。
參數
-
詳細資料
物件
-
顏色
string | ColorArray
由四個整數組成的陣列，範圍為 [0,255]，構成徽章的 RGBA 顏色。例如，不透明紅色為
[255, 0, 0, 255]。也可以是含有 CSS 值的字串，不透明紅色為#FF0000或#F00。 -
tabId
數字 選填
只有在選取特定分頁時，才會套用變更。分頁關閉時會自動重設。
-
傳回
-
承諾<void>
setBadgeText()
browser.action.setBadgeText(
details: object,
): Promise<void>
設定動作的徽章文字。徽章會顯示在圖示上方。
參數
-
詳細資料
物件
-
tabId
數字 選填
只有在選取特定分頁時，才會套用變更。關閉分頁時會自動重設。
-
文字
字串 選填
您可以傳遞任意數量的字元，但該空間只能容納約四個字元。如果傳遞空白字串 (
'')，系統會清除徽章文字。如果指定tabId，且text為空值，系統會清除指定分頁的文字，並預設為全域徽章文字。
-
傳回
-
承諾<void>
setBadgeTextColor()
browser.action.setBadgeTextColor(
details: object,
): Promise<void>
設定徽章的文字顏色。
參數
-
詳細資料
物件
-
顏色
string | ColorArray
由四個整數組成的陣列，範圍為 [0,255]，構成徽章的 RGBA 顏色。例如，不透明紅色為
[255, 0, 0, 255]。也可以是含有 CSS 值的字串，不透明紅色為#FF0000或#F00。如未設定這個值，系統會自動選擇與徽章背景顏色對比的顏色，確保文字清晰可見。如果顏色的 Alpha 值等於 0，系統就不會設定該顏色，並會傳回錯誤。 -
tabId
數字 選填
只有在選取特定分頁時，才會套用變更。分頁關閉時會自動重設。
-
傳回
-
承諾<void>
setIcon()
browser.action.setIcon(
details: object,
): Promise<void>
設定動作的圖示。圖示可以指定為圖片檔的路徑、畫布元素的像素資料，或其中一項的字典。必須指定 path 或 imageData 屬性。
參數
-
詳細資料
物件
-
imageData
ImageData | 物件 選填
ImageData 物件或字典 {size -> ImageData}，代表要設定的圖示。如果圖示指定為字典，系統會根據螢幕的像素密度選擇要使用的實際圖片。如果一個螢幕空間單位可容納的圖片像素數量等於
scale，系統就會選取大小為scale* n 的圖片，其中 n 是使用者介面中的圖示大小。至少須指定一張圖片。請注意，「details.imageData = foo」等同於「details.imageData = {'16': foo}」 -
路徑
字串 | 物件 選填
相對圖片路徑或字典 {size -> relative image path}，指向要設定的圖示。如果圖示指定為字典，系統會根據螢幕的像素密度選擇要使用的實際圖片。如果一個螢幕空間單位可容納的圖片像素數量等於
scale，系統就會選取大小為scale* n 的圖片，其中 n 是 UI 中的圖示大小。至少須指定一張圖片。請注意，「details.path = foo」等同於「details.path = {'16': foo}」 -
tabId
數字 選填
只有在選取特定分頁時，才會套用變更。分頁關閉時會自動重設。
-
傳回
-
承諾<void>
Chrome 96 以上版本 Chrome 148 以上版本中的 browser.*
setPopup()
browser.action.setPopup(
details: object,
): Promise<void>
設定使用者點選動作圖示時，要以彈出式視窗開啟的 HTML 文件。
參數
-
詳細資料
物件
-
彈出式訊息
字串
HTML 檔案的相對路徑，用於在彈出式視窗中顯示。如果設為空字串 (
'')，就不會顯示彈出式視窗。 -
tabId
數字 選填
只有在選取特定分頁時，才會套用變更。分頁關閉時會自動重設。
-
傳回
-
承諾<void>
setTitle()
browser.action.setTitle(
details: object,
): Promise<void>
設定動作的標題。這會顯示在工具提示中。
參數
-
詳細資料
物件
-
tabId
數字 選填
只有在選取特定分頁時，才會套用變更。分頁關閉時會自動重設。
-
title
字串
滑鼠游標懸停在動作上時，應顯示的字串。
-
傳回
-
承諾<void>
事件
onClicked
browser.action.onClicked.addListener(
callback: function,
)
使用者點選動作圖示時觸發。如果動作有彈出式視窗，就不會觸發這個事件。
onUserSettingsChanged
browser.action.onUserSettingsChanged.addListener(
callback: function,
)
當使用者指定的擴充功能動作相關設定變更時，就會觸發這個事件。
參數
-
callback
函式
callback參數如下：(change: UserSettingsChange) => void