說明
使用 chrome.action API 控制 Google Chrome 工具列中的擴充功能圖示。
可用性
資訊清單
如要使用 chrome.action API，請將 "manifest_version" 指定為 3，並在資訊清單檔案中加入 "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" 鍵。
概念與用途
使用者介面各部分
圖示
圖示是擴充功能工具列上的主要圖片，由資訊清單 "action" 鍵中的 "default_icon" 鍵設定。圖示的寬度和高度必須為 16 個與裝置無關的像素 (DIP)。
"default_icon" 鍵是大小到圖片路徑的字典。Chrome 會使用這些圖示選擇要使用的圖片比例。如果找不到完全相符的結果，Chrome 會選取最接近的可用圖片，並縮放圖片以符合大小，這可能會影響圖片品質。
由於 1.5 倍或 1.2 倍等較不常見的縮放比例裝置越來越普及，建議您提供多種尺寸的圖示。此外，這也能確保擴充功能在圖示顯示大小可能變更時，仍能正常運作。不過，如果只提供單一尺寸，"default_icon" 鍵也可以設為含有單一圖示路徑的字串，而非字典。
您也可以呼叫 action.setIcon()，透過指定其他圖片路徑或使用 HTML 畫布元素提供動態產生的圖示，以程式輔助方式設定擴充功能的圖示。如果從擴充功能服務工作人員設定，則可使用 offscreen canvas API。
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); chrome.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 顏色值字串。
chrome.action.setBadgeBackgroundColor( {color: [0, 255, 0, 0]}, // Green () => { /* ... */ }, ); chrome.action.setBadgeBackgroundColor( {color: '#00FF00'}, // Also green () => { /* ... */ }, ); chrome.action.setBadgeBackgroundColor( {color: 'green'}, // Also, also green () => { /* ... */ }, ); 彈出式廣告
使用者點選工具列中的擴充功能動作按鈕時，系統會顯示動作的彈出式視窗。彈出式視窗可包含任何 HTML 內容，並會自動調整大小以配合內容。彈出式視窗的大小必須介於 25x25 至 800x600 像素之間。
彈出式視窗最初是由 manifest.json 檔案中 "action" 鍵的 "default_popup" 屬性設定。如果存在，這項屬性應指向擴充功能目錄內的相對路徑。您也可以使用 action.setPopup() 方法，動態更新為指向其他相對路徑。
用途
分頁狀態
每個分頁的擴充功能動作可能處於不同狀態。如要為個別分頁設定值，請使用 action API 設定方法中的 tabId 屬性。舉例來說，如要設定特定分頁的徽章文字，請執行下列操作：
function getTabId() { /* ... */} function getTabBadge() { /* ... */} chrome.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 chrome.action.onClicked.addListener((tab) => { chrome.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 chrome.runtime.onInstalled.addListener(() => { // Page actions are disabled by default and enabled on select tabs chrome.action.disable(); // Clear all rules to ensure only our expected rules are set chrome.declarativeContent.onPageChanged.removeRules(undefined, () => { // Declare a rule to enable the action on example.com pages let exampleRule = { conditions: [ new chrome.declarativeContent.PageStateMatcher({ pageUrl: {hostSuffix: '.example.com'}, }) ], actions: [new chrome.declarativeContent.ShowAction()], }; // Finally, apply our new array of rules let rules = [exampleRule]; chrome.declarativeContent.onPageChanged.addRules(rules); }); }); 類型
OpenPopupOptions
屬性
- windowId
號碼 選填
要在哪個視窗中開啟動作彈出式視窗。如未指定，則預設為目前作用中的視窗。
TabDetails
屬性
- tabId
號碼 選填
要查詢狀態的分頁 ID。如未指定分頁，系統會傳回非分頁專屬的狀態。
UserSettings
使用者指定的一組擴充功能動作相關設定。
屬性
- isOnToolbar
布林值
擴充功能的動作圖示是否顯示在瀏覽器視窗的頂層工具列 (也就是使用者是否「釘選」擴充功能)。
UserSettingsChange
屬性
- isOnToolbar
布林值 選填
擴充功能的動作圖示是否顯示在瀏覽器視窗的頂層工具列 (也就是使用者是否「釘選」擴充功能)。
方法
disable()
chrome.action.disable(
tabId?: number,
): Promise<void>
停用分頁的動作。
參數
- tabId
號碼 選填
您要修改動作的分頁 ID。
傳回
-
Promise<void>
enable()
chrome.action.enable(
tabId?: number,
): Promise<void>
啟用分頁的動作。動作預設為啟用。
參數
- tabId
號碼 選填
您要修改動作的分頁 ID。
傳回
-
Promise<void>
getBadgeBackgroundColor()
chrome.action.getBadgeBackgroundColor(
details: TabDetails,
): Promise<extensionTypes.ColorArray>
取得動作的背景顏色。
參數
- 詳細資料
傳回
-
Promise<extensionTypes.ColorArray>
getBadgeText()
chrome.action.getBadgeText(
details: TabDetails,
): Promise<string>
取得動作的徽章文字。如未指定分頁，系統會傳回非分頁專屬的徽章文字。如果啟用 displayActionCountAsBadgeText，系統會傳回預留位置文字，除非有 declarativeNetRequestFeedback 權限，或已提供分頁專屬的徽章文字。
參數
- 詳細資料
傳回
-
Promise<string>
getBadgeTextColor()
chrome.action.getBadgeTextColor(
details: TabDetails,
): Promise<extensionTypes.ColorArray>
取得動作的文字顏色。
參數
- 詳細資料
傳回
-
Promise<extensionTypes.ColorArray>
參數
- 詳細資料
傳回
-
Promise<string>
參數
- 詳細資料
傳回
-
Promise<string>
getUserSettings()
chrome.action.getUserSettings(): Promise<UserSettings>
傳回與擴充功能動作相關的使用者指定設定。
傳回
-
Promise<UserSettings>
isEnabled()
chrome.action.isEnabled(
tabId?: number,
): Promise<boolean>
指出是否為分頁啟用擴充功能動作 (如未提供 tabId，則為全域啟用)。使用 declarativeContent 啟用的動作一律會傳回 false。
參數
- tabId
號碼 選填
要檢查啟用狀態的分頁 ID。
傳回
-
Promise<boolean>
openPopup()
chrome.action.openPopup(
options?: OpenPopupOptions,
): Promise<void>
開啟擴充功能的彈出式視窗。在 Chrome 118 到 Chrome 126 之間，這項功能僅適用於透過政策安裝的擴充功能。
參數
- 選項
OpenPopupOptions optional
指定開啟彈出式視窗的選項。
傳回
-
Promise<void>
setBadgeBackgroundColor()
chrome.action.setBadgeBackgroundColor(
details: object,
): Promise<void>
設定徽章的背景顏色。
參數
- 詳細資料
物件
- 顏色
字串 | ColorArray
陣列包含四個介於 [0,255] 的整數，組成徽章的 RGBA 顏色。舉例來說，不透明的紅色是
[255, 0, 0, 255]。也可以是含有 CSS 值的字串，不透明的紅色為#FF0000或#F00。 - tabId
號碼 選填
將變更限制為選取特定分頁時。關閉分頁時會自動重設。
-
傳回
-
Promise<void>
setBadgeText()
chrome.action.setBadgeText(
details: object,
): Promise<void>
設定動作的徽章文字。徽章會顯示在圖示上方。
參數
- 詳細資料
物件
- tabId
號碼 選填
將變更限制為選取特定分頁時。關閉分頁時會自動重設。
- 文字
字串 選填
可傳遞任意數量的字元，但空間只能容納約四個字元。如果傳遞空白字串 (
'')，徽章文字就會清除。如果指定tabId，但text為空值，則指定分頁的文字會清除，並預設為全域徽章文字。
-
傳回
-
Promise<void>
setBadgeTextColor()
chrome.action.setBadgeTextColor(
details: object,
): Promise<void>
設定徽章的文字顏色。
參數
- 詳細資料
物件
- 顏色
字串 | ColorArray
陣列包含四個介於 [0,255] 的整數，組成徽章的 RGBA 顏色。舉例來說，不透明的紅色是
[255, 0, 0, 255]。也可以是含有 CSS 值的字串，不透明的紅色為#FF0000或#F00。如果不設定這個值，系統會自動選擇與徽章背景顏色形成對比的顏色，確保文字清晰可見。如果 Alpha 值等於 0，系統就不會設定顏色，並傳回錯誤。 - tabId
號碼 選填
將變更限制為選取特定分頁時。關閉分頁時會自動重設。
-
傳回
-
Promise<void>
setIcon()
chrome.action.setIcon(
details: object,
): Promise<void>
設定動作的圖示。圖示可以指定為圖片檔案的路徑、畫布元素的像素資料，或其中任一項的字典。必須指定 path 或 imageData 屬性。
參數
- 詳細資料
物件
- imageData
ImageData | 物件 選用
ImageData 物件或代表要設定圖示的字典 {size -> ImageData}。如果圖示指定為字典，系統會根據螢幕的像素密度選擇要使用的實際圖片。如果可放入一個螢幕空間單位的圖片像素數量等於
scale，系統就會選取大小為scale* n 的圖片，其中 n 是 UI 中圖示的大小。至少須指定一張圖片。請注意，「details.imageData = foo」等同於「details.imageData = {'16': foo}」。 - 路徑
字串 | 物件 選用
相對圖片路徑或指向要設定圖示的字典 {size -> relative image path}。如果圖示指定為字典，系統會根據螢幕的像素密度選擇要使用的實際圖片。如果可放入一個螢幕空間單位的圖片像素數量等於
scale，系統就會選取大小為scale* n 的圖片，其中 n 是 UI 中圖示的大小。至少須指定一張圖片。請注意，「details.path = foo」等同於「details.path = {'16': foo}」 - tabId
號碼 選填
將變更限制為選取特定分頁時。關閉分頁時會自動重設。
-
傳回
-
Promise<void>
Chrome 96 以上版本
setPopup()
chrome.action.setPopup(
details: object,
): Promise<void>
設定使用者點選動作圖示時，要以彈出式視窗開啟的 HTML 文件。
參數
- 詳細資料
物件
- 彈出式訊息
字串
要在彈出式視窗中顯示的 HTML 檔案相對路徑。如果設為空字串 (
'')，系統就不會顯示彈出式視窗。 - tabId
號碼 選填
將變更限制為選取特定分頁時。關閉分頁時會自動重設。
-
傳回
-
Promise<void>
setTitle()
chrome.action.setTitle(
details: object,
): Promise<void>
設定動作的標題。這會顯示在工具提示中。
參數
- 詳細資料
物件
- tabId
號碼 選填
將變更限制為選取特定分頁時。關閉分頁時會自動重設。
- title
字串
滑鼠懸停時動作應顯示的字串。
-
傳回
-
Promise<void>
事件
onClicked
chrome.action.onClicked.addListener(
callback: function,
)
點選動作圖示時觸發。如果動作會顯示彈出式視窗，系統就不會觸發這個事件。
onUserSettingsChanged
chrome.action.onUserSettingsChanged.addListener(
callback: function,
)
當使用者指定的擴充功能動作相關設定變更時，就會觸發這個事件。
參數
- callback
函式
callback參數如下：(change: UserSettingsChange) => void