說明
適用國家/地區
如下圖所示,網址列右側的彩色方塊是瀏覽器動作的圖示。圖示下方會顯示彈出式視窗,
如果您想建立不一定使用的圖示,請使用「頁面動作」,而非瀏覽器動作。
資訊清單
在擴充功能資訊清單中註冊瀏覽器動作,如下所示:
{
"name": "My extension",
...
"browser_action": {
"default_icon": { // optional
"16": "images/icon16.png", // optional
"24": "images/icon24.png", // optional
"32": "images/icon32.png" // optional
},
"default_title": "Google Mail", // optional, shown in tooltip
"default_popup": "popup.html" // optional
},
...
}
您可以提供要用於 Chrome 的任何尺寸圖示。Chrome 會選取最接近的尺寸圖示,並將該圖示調整為合適的大小,以填滿 16 像素的空間。但如果未提供確切大小,這項縮放功能可能會導致圖示遺失細節,或看起來模糊不清。
由於 1.5 倍或 1.2 倍等較不常見的比例係數的裝置越來越普遍,建議您為圖示提供多種尺寸。這也可確保如果圖示顯示大小曾經變更,您就不需要再進行任何其他操作來提供不同的圖示!
系統仍支援用於註冊預設圖示的舊語法:
{
"name": "My extension",
...
"browser_action": {
...
"default_icon": "images/icon32.png" // optional
// equivalent to "default_icon": { "32": "images/icon32.png" }
},
...
}
UI 的某些部分
圖示
Chrome 的瀏覽器動作圖示寬度為 16 低點 (裝置獨立像素),放大圖示將調整為適當大小,但為獲得最佳效果,請使用 16 dip 的正方形圖示。
您可以透過兩種方式設定圖示:使用靜態圖片或使用 HTML5 畫布元素。使用靜態圖片較容易用於簡單的應用程式,但您可以利用畫布元素建立更動態的 UI,例如流暢的動畫。
靜態圖片可以是 WebKit 可顯示的任何格式,包括 BMP、GIF、ICO、JPEG 或 PNG。未封裝的擴充功能圖片必須使用 PNG 格式。
如要設定圖示,請使用 manifest 中 browser_action 的 default_icon 欄位,或呼叫 browserAction.setIcon
方法。
如要在螢幕像素密度 (比例 size_in_pixel / size_in_dip
) 與 1 不同時正確顯示圖示,您可以將圖示定義為不同大小的圖片組合。系統會從組合中選取最適合像素大小 16 dip 的圖片。圖示集可包含任何大小的圖示規格,Chrome 會選擇最合適的圖示。
工具提示
如要設定工具提示,請使用資訊清單中 default_title 的 default_title 欄位,或呼叫 browserAction.setTitle
方法。您可以在 default_title 欄位指定語言代碼的專屬字串,詳情請參閱國際化。
徽章
瀏覽器動作可選擇顯示標記,也就是疊加在圖示上的一小段文字。標記可讓您輕鬆更新瀏覽器動作,以顯示少量與擴充功能狀態相關的資訊。
由於徽章的空間有限,因此它不得超過 4 個字元。
使用 browserAction.setBadgeText
和 browserAction.setBadgeBackgroundColor
,分別設定徽章的文字和顏色。
彈出式廣告
如果瀏覽器動作顯示彈出式視窗,則當使用者點選擴充功能的圖示時,會出現彈出式視窗。該彈出式視窗可以包含任何您喜歡的 HTML 內容,並會自動根據內容調整大小。彈出式視窗不得小於 25x25,且大小不能超過 800x600。
如要在瀏覽器動作中新增彈出式視窗,請建立含有彈出式視窗內容的 HTML 檔案。在資訊清單中 default_popup 的 default_popup 欄位中指定 HTML 檔案,或是呼叫 browserAction.setPopup
方法。
提示
為了獲得最佳視覺效果,請遵循下列守則:
- 請使用瀏覽器動作執行大多數頁面適用的功能。
- 不要使用瀏覽器動作,只用對少數網頁有意義的功能。請改用頁面動作。
- 請使用色彩繽紛的大型圖示,充分利用 16x16 的頻寬空間。瀏覽器動作圖示應該比頁面動作圖示少一點,也更顯眼。
- 請勿嘗試模仿 Google Chrome 的單色選單圖示。主題無法用到這一點 而且,擴充功能應該更顯眼。
- 請使用 Alpha 透明度,為圖示加上柔和邊緣。由於許多人都會使用主題,因此圖示應與各種背景顏色相輔相成。
- 不要不斷為圖示加上動畫效果。這只是煩人。
示例
您可以在 examples/api/browserAction 目錄中找到使用瀏覽器動作的簡單範例。如需其他範例及查看原始碼的相關說明,請參閱範例。
類型
ColorArray
類型
[數字, 數字, 數字]
ImageDataType
圖片的像素資料。必須是 ImageData 物件,例如來自 canvas
元素。
類型
ImageData
TabDetails
屬性
-
tabId
數字 選填
要查詢狀態的分頁 ID。如未指定分頁,系統會傳回非分頁專用的狀態。
方法
disable()
chrome.browserAction.disable(
tabId?: number,
callback?: function,
)
停用分頁的瀏覽器動作。
參數
-
tabId
數字 選填
要修改瀏覽器動作的分頁 ID。
-
回呼
函式選用
Chrome 67 以上版本callback
參數如下所示:() => void
傳回
-
Promise<void>
Chrome 88 以上版本Promise 僅支援 Manifest V3 以上版本,其他平台就必須使用回呼。
enable()
chrome.browserAction.enable(
tabId?: number,
callback?: function,
)
啟用分頁的瀏覽器動作。預設為啟用。
參數
-
tabId
數字 選填
要修改瀏覽器動作的分頁 ID。
-
回呼
函式選用
Chrome 67 以上版本callback
參數如下所示:() => void
傳回
-
Promise<void>
Chrome 88 以上版本Promise 僅支援 Manifest V3 以上版本,其他平台就必須使用回呼。
getBadgeBackgroundColor()
chrome.browserAction.getBadgeBackgroundColor(
details: TabDetails,
callback?: function,
)
取得瀏覽器動作的背景顏色。
參數
-
詳細資料
-
回呼
函式選用
callback
參數如下所示:(result: ColorArray) => void
-
結果
-
傳回
-
Promise<ColorArray>
Chrome 88 以上版本Promise 僅支援 Manifest V3 以上版本,其他平台就必須使用回呼。
getBadgeText()
chrome.browserAction.getBadgeText(
details: TabDetails,
callback?: function,
)
取得瀏覽器動作的徽章文字。如果未指定分頁,系統會傳回非分頁專用的徽章文字。
參數
-
詳細資料
-
回呼
函式選用
callback
參數如下所示:(result: string) => void
-
結果
字串
-
傳回
-
Promise<string>
Chrome 88 以上版本Promise 僅支援 Manifest V3 以上版本,其他平台就必須使用回呼。
getPopup()
chrome.browserAction.getPopup(
details: TabDetails,
callback?: function,
)
取得設為這個瀏覽器動作彈出式視窗的 HTML 文件。
參數
-
詳細資料
-
回呼
函式選用
callback
參數如下所示:(result: string) => void
-
結果
字串
-
傳回
-
Promise<string>
Chrome 88 以上版本Promise 僅支援 Manifest V3 以上版本,其他平台就必須使用回呼。
getTitle()
chrome.browserAction.getTitle(
details: TabDetails,
callback?: function,
)
取得瀏覽器動作的標題。
參數
-
詳細資料
-
回呼
函式選用
callback
參數如下所示:(result: string) => void
-
結果
字串
-
傳回
-
Promise<string>
Chrome 88 以上版本Promise 僅支援 Manifest V3 以上版本,其他平台就必須使用回呼。
setBadgeBackgroundColor()
chrome.browserAction.setBadgeBackgroundColor(
details: object,
callback?: function,
)
設定徽章的背景顏色。
參數
-
詳細資料
物件
-
顏色
string | ColorArray
構成徽章 RGBA 顏色的四個整數,範圍在 0 到 255 之間。這也可以是包含 CSS 十六進位顏色值的字串,例如
#FF0000
或#F00
(紅色)。以完整不透明度呈現顏色。 -
tabId
數字 選填
限制只在選取特定分頁時進行變更。關閉分頁時自動重設。
-
-
回呼
函式選用
Chrome 67 以上版本callback
參數如下所示:() => void
傳回
-
Promise<void>
Chrome 88 以上版本Promise 僅支援 Manifest V3 以上版本,其他平台就必須使用回呼。
setBadgeText()
chrome.browserAction.setBadgeText(
details: object,
callback?: function,
)
設定瀏覽器動作的徽章文字。徽章會顯示在圖示頂端。
參數
-
詳細資料
物件
-
tabId
數字 選填
限制只在選取特定分頁時進行變更。關閉分頁時自動重設。
-
text
字串 選用
可以傳遞任意數量的字元,但大約只有四個字元。如果傳遞空字串 (
''
),系統會清除徽章文字。如果指定tabId
且text
為空值,系統會清除指定分頁的文字,並預設為全域徽章文字。
-
-
回呼
函式選用
Chrome 67 以上版本callback
參數如下所示:() => void
傳回
-
Promise<void>
Chrome 88 以上版本Promise 僅支援 Manifest V3 以上版本,其他平台就必須使用回呼。
setIcon()
chrome.browserAction.setIcon(
details: object,
callback?: function,
)
設定瀏覽器動作的圖示。圖示可以指定為圖片檔路徑、畫布元素的像素資料,或是上述圖示的字典。必須指定 path
或 imageData
屬性。
參數
-
詳細資料
物件
-
imageData
ImageData | 物件 選用
代表要設定圖示的 ImageData 物件或字典 {size -> ImageData}。如果圖示指定為字典,系統會根據螢幕的像素密度選擇要使用的圖片。如果適合單一螢幕空間單元的圖片像素數量等於
scale
,系統就會選取大小為scale
* n 的圖片,其中 n 是使用者介面中圖示的大小。至少須指定一張圖片。請注意,「details.imageData = foo」等於「details.imageData = {'16': foo}」 -
path
string | object optional
相對圖片路徑,或指向要設定圖示的字典 {size -> 相對圖片路徑}。如果圖示指定為字典,系統會根據螢幕的像素密度選擇要使用的圖片。如果適合單一螢幕空間單元的圖片像素數量等於
scale
,系統就會選取大小為scale
* n 的圖片,其中 n 是使用者介面中圖示的大小。至少須指定一張圖片。請注意,「details.path = foo」等於「details.path = {'16': foo}'」 -
tabId
數字 選填
限制只在選取特定分頁時進行變更。關閉分頁時自動重設。
-
-
回呼
函式選用
callback
參數如下所示:() => void
傳回
-
Promise<void>
Chrome 116 以上版本Promise 僅支援 Manifest V3 以上版本,其他平台就必須使用回呼。
setPopup()
chrome.browserAction.setPopup(
details: object,
callback?: function,
)
設定當使用者按下瀏覽器動作圖示時,以彈出式視窗形式開啟的 HTML 文件。
參數
-
詳細資料
物件
-
彈出式視窗
字串
顯示在彈出式視窗中的 HTML 檔案的相對路徑。如果設為空白字串 (
''
),系統就不會顯示彈出式視窗。 -
tabId
數字 選填
限制只在選取特定分頁時進行變更。關閉分頁時自動重設。
-
-
回呼
函式選用
Chrome 67 以上版本callback
參數如下所示:() => void
傳回
-
Promise<void>
Chrome 88 以上版本Promise 僅支援 Manifest V3 以上版本,其他平台就必須使用回呼。
setTitle()
chrome.browserAction.setTitle(
details: object,
callback?: function,
)
設定瀏覽器動作的標題。這個標題會顯示在工具提示中。
參數
-
詳細資料
物件
-
tabId
數字 選填
限制只在選取特定分頁時進行變更。關閉分頁時自動重設。
-
title
字串
滑鼠遊標懸停時,瀏覽器動作應顯示的字串。
-
-
回呼
函式選用
Chrome 67 以上版本callback
參數如下所示:() => void
傳回
-
Promise<void>
Chrome 88 以上版本Promise 僅支援 Manifest V3 以上版本,其他平台就必須使用回呼。