說明
使用 chrome.action
API 控制 Google Chrome 工具列中的擴充功能圖示。
適用國家/地區
資訊清單
如要使用 chrome.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 倍等較不常見的比例係數的裝置越來越常見,因此建議您為圖示提供多種尺寸。這也能確保擴充功能日後的圖示顯示大小變更時不會發生變化。
您也可以呼叫 action.setIcon()
,透過程式輔助方式設定擴充功能圖示,方法是指定不同的圖片路徑,或是透過 HTML 畫布元素提供動態產生的圖示;如果是從擴充功能服務 Worker 進行設定,則可呼叫畫面外畫布 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.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!');
使用宣告式內容模擬動作
本範例說明擴充功能的背景邏輯如何 (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
數字 選填
要開啟動作彈出式視窗的視窗 ID。如未指定,則預設為目前使用中的視窗。
TabDetails
屬性
-
tabId
數字 選填
要查詢狀態的分頁 ID。如未指定分頁,系統會傳回非分頁專用的狀態。
UserSettings
收集使用者指定的擴充功能動作設定。
屬性
-
isOnToolbar
boolean
設定擴充功能的動作圖示是否會顯示在瀏覽器視窗的頂層工具列中 (亦即使用者是否「已固定」擴充功能)。
方法
disable()
chrome.action.disable(
tabId?: number,
callback?: function,
)
停用分頁的動作。
參數
-
tabId
數字 選填
您要修改動作的分頁 ID。
-
回呼
函式選用
callback
參數如下所示:()=>void
傳回
-
Promise<void>
Manifest V3 以上版本支援 Promise,但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。
enable()
chrome.action.enable(
tabId?: number,
callback?: function,
)
啟用分頁的動作。動作預設為啟用。
參數
-
tabId
數字 選填
您要修改動作的分頁 ID。
-
回呼
函式選用
callback
參數如下所示:()=>void
傳回
-
Promise<void>
Manifest V3 以上版本支援 Promise,但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。
getBadgeBackgroundColor()
chrome.action.getBadgeBackgroundColor(
details: TabDetails,
callback?: function,
)
取得動作的背景顏色。
參數
-
詳細資料
-
回呼
函式選用
callback
參數如下所示:(result: ColorArray)=>void
-
結果
-
傳回
-
Promise<browserAction.ColorArray>
Manifest V3 以上版本支援 Promise,但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。
getBadgeText()
chrome.action.getBadgeText(
details: TabDetails,
callback?: function,
)
取得動作的徽章文字。如果未指定分頁,系統會傳回非分頁專用的徽章文字。如果已啟用 displayActionCountAsBadgeText,系統將傳回預留位置文字,除非使用者俱備 declarativeNetRequestFeedback 權限,或提供特定分頁專用的徽章文字。
參數
-
詳細資料
-
回呼
函式選用
callback
參數如下所示:(result: string)=>void
-
結果
字串
-
傳回
-
Promise<string>
Manifest V3 以上版本支援 Promise,但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。
getBadgeTextColor()
chrome.action.getBadgeTextColor(
details: TabDetails,
callback?: function,
)
取得動作的文字顏色。
參數
-
詳細資料
-
回呼
函式選用
callback
參數如下所示:(result: ColorArray)=>void
-
結果
-
傳回
-
Promise<browserAction.ColorArray>
Manifest V3 以上版本支援 Promise,但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。
getPopup()
chrome.action.getPopup(
details: TabDetails,
callback?: function,
)
取得 HTML 文件集,做為此動作的彈出式視窗。
參數
-
詳細資料
-
回呼
函式選用
callback
參數如下所示:(result: string)=>void
-
結果
字串
-
傳回
-
Promise<string>
Manifest V3 以上版本支援 Promise,但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。
參數
-
詳細資料
-
回呼
函式選用
callback
參數如下所示:(result: string)=>void
-
結果
字串
-
傳回
-
Promise<string>
Manifest V3 以上版本支援 Promise,但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。
getUserSettings()
chrome.action.getUserSettings(
callback?: function,
)
傳回與擴充功能動作相關的使用者指定的設定。
參數
-
回呼
函式選用
callback
參數如下所示:(userSettings: UserSettings)=>void
-
userSettings
-
傳回
-
Promise<UserSettings>
Manifest V3 以上版本支援 Promise,但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。
isEnabled()
chrome.action.isEnabled(
tabId?: number,
callback?: function,
)
指出分頁是否已啟用擴充功能動作 (如未提供 tabId
,則為全域)。僅使用 declarativeContent
啟用的動作一律會傳回 false。
參數
-
tabId
數字 選填
要檢查已啟用狀態的分頁 ID。
-
回呼
函式選用
callback
參數如下所示:(isEnabled: boolean)=>void
-
isEnabled
boolean
如果已啟用擴充功能動作,則為「是」。
-
傳回
-
Promise<boolean>
Manifest V3 以上版本支援 Promise,但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。
openPopup()
chrome.action.openPopup(
options?: OpenPopupOptions,
callback?: function,
)
開啟擴充功能的彈出式視窗。
參數
-
選項
指定開啟彈出式視窗的選項。
-
回呼
函式選用
callback
參數如下所示:()=>void
傳回
-
Promise<void>
Manifest V3 以上版本支援 Promise,但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。
setBadgeBackgroundColor()
chrome.action.setBadgeBackgroundColor(
details: object,
callback?: function,
)
設定徽章的背景顏色。
參數
-
詳細資料
物件
-
顏色
string|ColorArray
代表徽章 RGBA 顏色的 [0,255] 範圍中的四個整數陣列。例如,不透明的紅色是
[255, 0, 0, 255]
。也可以是包含 CSS 值的字串,不透明紅色代表#FF0000
或#F00
。 -
tabId
數字 選填
限制只在選取特定分頁時進行變更。關閉分頁時自動重設。
-
-
回呼
函式選用
callback
參數如下所示:()=>void
傳回
-
Promise<void>
Manifest V3 以上版本支援 Promise,但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。
setBadgeText()
chrome.action.setBadgeText(
details: object,
callback?: function,
)
設定動作的徽章文字。徽章會顯示在圖示頂端。
參數
-
詳細資料
物件
-
tabId
數字 選填
限制只在選取特定分頁時進行變更。關閉分頁時自動重設。
-
text
字串 選用
可以傳遞任意數量的字元,但大約只有四個字元。如果傳遞空字串 (
''
),系統會清除徽章文字。如果指定tabId
且text
為空值,系統會清除指定分頁的文字,並預設為全域徽章文字。
-
-
回呼
函式選用
callback
參數如下所示:()=>void
傳回
-
Promise<void>
Manifest V3 以上版本支援 Promise,但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。
setBadgeTextColor()
chrome.action.setBadgeTextColor(
details: object,
callback?: function,
)
設定徽章的文字顏色。
參數
-
詳細資料
物件
-
顏色
string|ColorArray
代表徽章 RGBA 顏色的 [0,255] 範圍中的四個整數陣列。例如,不透明的紅色是
[255, 0, 0, 255]
。也可以是包含 CSS 值的字串,不透明紅色代表#FF0000
或#F00
。如果不設定這個值,系統會自動選擇會與徽章背景顏色形成對比的色彩,讓文字清晰可見。Alpha 值等於 0 的顏色不會進行設定,且會傳回錯誤。 -
tabId
數字 選填
限制只在選取特定分頁時進行變更。關閉分頁時自動重設。
-
-
回呼
函式選用
callback
參數如下所示:()=>void
傳回
-
Promise<void>
Manifest V3 以上版本支援 Promise,但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。
setIcon()
chrome.action.setIcon(
details: object,
callback?: function,
)
設定動作的圖示。圖示可指定為圖片檔路徑、畫布元素的像素資料,或是上述任一項目的字典。必須指定 path 或 imageData 屬性。
參數
-
詳細資料
物件
-
imageData
ImageData|object 選用
代表要設定圖示的 ImageData 物件或字典 {size -> ImageData}。如果圖示指定為字典,則會根據螢幕的像素密度選擇要使用的實際圖片。如果可放入一個螢幕空間單元的圖片像素數量等於
scale
,系統就會選取大小為scale
* n 的圖片,其中 n 是使用者介面中圖示的大小。至少須指定一張圖片。請注意,「details.imageData = foo」等於「details.imageData = {'16': foo}」 -
path
string|object 選用
相對圖片路徑,或指向要設定圖示的字典 {size -> 相對圖片路徑}。如果圖示指定為字典,則會根據螢幕的像素密度選擇要使用的實際圖片。如果可放入一個螢幕空間單元的圖片像素數量等於
scale
,系統就會選取大小為scale
* n 的圖片,其中 n 是使用者介面中圖示的大小。至少須指定一張圖片。請注意,「details.path = foo」等於「details.path = {'16': foo}'」 -
tabId
數字 選填
限制只在選取特定分頁時進行變更。關閉分頁時自動重設。
-
-
回呼
函式選用
callback
參數如下所示:()=>void
傳回
-
Promise<void>
Chrome 96 以上版本Manifest V3 以上版本支援 Promise,但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。
setPopup()
chrome.action.setPopup(
details: object,
callback?: function,
)
設定當使用者點選動作圖示時,在彈出式視窗中開啟 HTML 文件。
參數
-
詳細資料
物件
-
彈出式視窗
字串
顯示在彈出式視窗中的 HTML 檔案的相對路徑。如果設為空白字串 (
''
),系統就不會顯示彈出式視窗。 -
tabId
數字 選填
限制只在選取特定分頁時進行變更。關閉分頁時自動重設。
-
-
回呼
函式選用
callback
參數如下所示:()=>void
傳回
-
Promise<void>
Manifest V3 以上版本支援 Promise,但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。
setTitle()
chrome.action.setTitle(
details: object,
callback?: function,
)
設定動作的標題。這項資訊會顯示在工具提示中。
參數
-
詳細資料
物件
-
tabId
數字 選填
限制只在選取特定分頁時進行變更。關閉分頁時自動重設。
-
title
字串
滑鼠遊標懸停時,動作應顯示的字串。
-
-
回呼
函式選用
callback
參數如下所示:()=>void
傳回
-
Promise<void>
Manifest V3 以上版本支援 Promise,但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。