本頁面由 Cloud Translation API 翻譯而成。

chrome.browserAction

說明

使用瀏覽器動作將圖示放在 Google Chrome 主要工具列的網址列右側。除了其圖示以外，瀏覽器動作也可以提供工具提示、徽章和彈出式視窗。

可用性

&leq;MV2

在下圖中，網址列右側的彩色方塊是瀏覽器動作。圖示下方會顯示彈出式視窗。

如果您想建立不一定會有效的圖示，請使用網頁動作，而不要使用瀏覽器動作。

資訊清單

在擴充功能資訊清單中註冊瀏覽器動作，如下所示：

{
  "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 dip 空間。不過，如果未提供確切大小縮放可能會導致圖示細節遺失��看起來模糊不清。

由於縮放比例係數 (例如 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 都會選擇最合適的規格。

如要設定工具提示，請使用 manifest 中 browser_action 的 default_title 欄位，或是呼叫 browserAction.setTitle 方法。您可以指定 default_title 欄位；詳情請參閱國際化。

徽章

瀏覽器動作可選擇顯示「標記」，也就是在圖示上疊加的一小段文字。標記可讓您輕鬆更新瀏覽器動作，以顯示擴充功能的狀態

由於徽章的空間有限，因此長度不得超過 4 個半形字元。

使用 browserAction.setBadgeText 和 browserAction.setBadgeBackgroundColor。

如果瀏覽器動作含有彈出式視窗，當使用者按一下擴充功能的圖示時，系統會顯示彈出式視窗。彈出式視窗可包含任何您想要的 HTML 內容，並且會自動調整其大小，以符合內容。彈出式視窗不得小於 25x25，也不得大於 800x600。

如要為瀏覽器動作加入彈出式視窗，請建立含有彈出式視窗內容的 HTML 檔案。請指定加入 manifest 中 browser_action 的 default_popup 欄位中 HTML 檔案，或是呼叫 browserAction.setPopup 方法。

提示

為了獲得最佳視覺效果，請遵守以下規定：

請使用瀏覽器動作，以提供多數網頁適用的功能。
請勿將瀏覽器動作用於僅適用於少數網頁的功能。使用頁面 action。
請使用彩色的大型圖示，充分利用 16x16 dip 空間。瀏覽器動作圖示應該比網頁動作圖示更大、更顯眼
請勿嘗試模仿 Google Chrome 的單色選單圖示。這項功能不適合主題，但無論如何，擴充功能都應該脫穎而出。
請使用 Alpha 透明度，為圖示加上柔和的邊緣。許多人使用主題圖示在各種背景顏色上都能呈現良好的視覺效果。
請勿持續製作圖示動畫，真煩人。

範例

您可以在 examples/api/browserAction 找到瀏覽器動作的簡單範例。目錄。如需其他範例及瞭解如何查看原始碼，請參閱「範例」。

類型

ColorArray

類型

[數字、數字、數字、數字]

ImageDataType

圖片的像素資料。必須為 ImageData 物件；例如從 canvas 元素中移除

類型

ImageData

TabDetails

Chrome 88 以上版本

屬性

tabId

編號選填

要查詢狀態的分頁 ID。如未指定分頁，系統會傳回非分頁專屬的狀態。

方法

disable()

Promise

chrome.browserAction.disable(
  tabId?: number,
  callback?: function,
)

停用分頁的瀏覽器動作。

參數

tabId

編號選填

要修改瀏覽器動作的分頁 ID。
回呼

函式選用

Chrome 67 以上版本

callback 參數如下所示：
```
() => void
```

傳回

承諾<void>

Chrome 88 以上版本

Promise 僅適用於 Manifest V3 及以上版本，其他平台需要使用回呼。

enable()

Promise

chrome.browserAction.enable(
  tabId?: number,
  callback?: function,
)

為分頁啟用瀏覽器動作。預設為啟用。

參數

tabId

編號選填

要修改瀏覽器動作的分頁 ID。
回呼

函式選用

Chrome 67 以上版本

callback 參數如下所示：
```
() => void
```

傳回

承諾<void>

Chrome 88 以上版本

Promise 僅適用於 Manifest V3 及以上版本，其他平台需要使用回呼。

getBadgeBackgroundColor()

Promise

chrome.browserAction.getBadgeBackgroundColor(
  details: TabDetails,
  callback?: function,
)

取得瀏覽器動作的背景顏色。

參數

詳細資料

TabDetails
回呼

函式選用

callback 參數如下所示：
```
(result: ColorArray) => void
```
- 結果
  
  ColorArray

傳回

Promise<ColorArray>

Chrome 88 以上版本

Promise 僅適用於 Manifest V3 及以上版本，其他平台需要使用回呼。

getBadgeText()

Promise

chrome.browserAction.getBadgeText(
  details: TabDetails,
  callback?: function,
)

取得瀏覽器動作的徽章文字。如未指定分頁，系統會傳回非分頁專屬的標記文字。

參數

詳細資料

TabDetails
回呼

函式選用

callback 參數如下所示：
```
(result: string) => void
```
- 結果
  
  字串

傳回

承諾<字串>

Chrome 88 以上版本

Promise 僅適用於 Manifest V3 及以上版本，其他平台需要使用回呼。

getPopup()

Promise

chrome.browserAction.getPopup(
  details: TabDetails,
  callback?: function,
)

取得 HTML 文件，設為此瀏覽器動作的彈出式視窗。

參數

詳細資料

TabDetails
回呼

函式選用

callback 參數如下所示：
```
(result: string) => void
```
- 結果
  
  字串

傳回

承諾<字串>

Chrome 88 以上版本

Promise 僅適用於 Manifest V3 及以上版本，其他平台需要使用回呼。

getTitle()

Promise

chrome.browserAction.getTitle(
  details: TabDetails,
  callback?: function,
)

取得瀏覽器動作的標題。

參數

詳細資料

TabDetails
回呼

函式選用

callback 參數如下所示：
```
(result: string) => void
```
- 結果
  
  字串

傳回

承諾<字串>

Chrome 88 以上版本

Promise 僅適用於 Manifest V3 及以上版本，其他平台需要使用回呼。

setBadgeBackgroundColor()

Promise

chrome.browserAction.setBadgeBackgroundColor(
  details: object,
  callback?: function,
)

設定徽章的背景顏色。

參數

詳細資料

物件
- 顏色
  
  string |ColorArray
  
  構成徽章的 RGBA 顏色的四個整數陣列，範圍介於 0 到 255 之間。也可以是包含 CSS 十六進位顏色值的字串；例如 #FF0000 或 #F00 (紅色)。以完整不透明度呈現顏色。
- tabId
  
  編號選填
  
  限制在選取特定分頁的時機。會在分頁關閉時自動重設。
回呼

函式選用

Chrome 67 以上版本

callback 參數如下所示：
```
() => void
```

傳回

承諾<void>

Chrome 88 以上版本

Promise 僅適用於 Manifest V3 及以上版本，其他平台需要使用回呼。

setBadgeText()

Promise

chrome.browserAction.setBadgeText(
  details: object,
  callback?: function,
)

設定瀏覽器動作的徽章文字。徽章會顯示在圖示頂端。

參數

詳細資料

物件
- tabId
  
  編號選填
  
  限制在選取特定分頁的時機。會在分頁關閉時自動重設。
- 文字
  
  string optional
  
  可以傳送任意數量的字元，但大約只有 4 個字元可以放入空間。如果傳遞空白字串 ('')，系統會清除徽章文字。如果指定 tabId 且 text 為空值，系統會清除指定分頁的文字，並預設為全域徽章文字。
回呼

函式選用

Chrome 67 以上版本

callback 參數如下所示：
```
() => void
```

傳回

承諾<void>

Chrome 88 以上版本

Promise 僅適用於 Manifest V3 及以上版本，其他平台需要使用回呼。

setIcon()

Promise

chrome.browserAction.setIcon(
  details: object,
  callback?: function,
)

設定瀏覽器動作的圖示。可以將圖示指定為圖片檔的路徑、畫布元素的像素資料，或是項目的字典。必須指定 path 或 imageData 屬性。

參數

詳細資料

物件
- 圖片資料
  
  ImageData |物件 optional
  
  ImageData 物件或字典 {size ->ImageData} 代表要設定的圖示。如果圖示指定為字典，系統會根據螢幕的像素密度選擇所使用的圖片。如果單一螢幕空間單元的圖片像素數量等於 scale，系統會選取大小為 scale * n 的圖片，其中 n 是使用者介面中的圖示尺寸。至少須指定一張圖片。請注意，「details.imageData = foo」相當於 'details.imageData = {'16': foo}'
- 路徑
  
  string |物件 optional
  
  相對圖片路徑或字典 {size ->相對圖片路徑}，指向要設定的圖示。如果圖示指定為字典，系統會根據螢幕的像素密度選擇所使用的圖片。如果單一螢幕空間單元的圖片像素數量等於 scale，系統會選取大小為 scale * n 的圖片，其中 n 是使用者介面中的圖示尺寸。至少須指定一張圖片。請注意，「details.path = foo」相當於 'details.path = {'16': foo}'
- tabId
  
  編號選填
  
  限制在選取特定分頁的時機。會在分頁關閉時自動重設。
回呼

函式選用

callback 參數如下所示：
```
() => void
```

傳回

承諾<void>

Chrome 116 以上版本

Promise 僅適用於 Manifest V3 及以上版本，其他平台需要使用回呼。

setPopup()

Promise

chrome.browserAction.setPopup(
  details: object,
  callback?: function,
)

設定當使用者按一下瀏覽器動作圖示時，要以彈出式視窗開啟 HTML 文件。

參數

詳細資��

物件
- 彈出式訊息
  
  字串
  
  在彈出式視窗中顯示的 HTML 檔案的相對路徑。如果設為空字串 ('')，系統不會顯示彈出式視窗。
- tabId
  
  編號選填
  
  限制在選取特定分頁的時機。會在分頁關閉時自動重設。
回呼

函式選用

Chrome 67 以上版本

callback 參數如下所示：
```
() => void
```

傳回

承諾<void>

Chrome 88 以上版本

Promise 僅適用於 Manifest V3 及以上版本，其他平台需要使用回呼。

setTitle()

Promise

chrome.browserAction.setTitle(
  details: object,
  callback?: function,
)

設定瀏覽器動作的標題。這個標題會顯示在工具提示中。

參數

詳細資料

物件
- tabId
  
  編號選填
  
  限制在選取特定分頁的時機。會在分頁關閉時自動重設。
- title
  
  字串
  
  滑鼠遊標懸停時，瀏覽器動作應顯示的字串。
回呼

函式選用

Chrome 67 以上版本

callback 參數如下所示：
```
() => void
```

傳回

承諾<void>

Chrome 88 以上版本

Promise 僅適用於 Manifest V3 及以上版本，其他平台需要使用回呼。

活動

onClicked

chrome.browserAction.onClicked.addListener(
  callback: function,
)

按下瀏覽器動作圖示時觸發。如果瀏覽器動作含有彈出式視窗，則不會觸發。

參數

回呼

函式

callback 參數如下所示：
```
(tab: tabs.Tab) => void
```
- 分頁
  
  tabs.Tab