chrome.browserAction

refresh date: 2026-09-25 robots: noindex

說明

使用瀏覽器動作，在 Google Chrome 主工具列 (網址列右側) 放置圖示。除了圖示，瀏覽器動作還可以有工具提示、徽章和彈出式視窗。

可用性

≤ 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 會選取最接近的大小，並縮放至適當大小，填滿 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 dip (與裝置無關的像素)。較大的圖示會調整大小以符合規定，但為獲得最佳效果，請使用 16 dip 的正方形圖示。

設定圖示的方式有兩種：使用靜態圖片，或使用 HTML5 canvas 元素。如果是簡單的應用程式，使用靜態圖片會比較容易，但您可以使用畫布元素建立更動態的 UI，例如流暢的動畫。

靜態圖片可以是 WebKit 可顯示的任何格式，包括 BMP、GIF、ICO、JPEG 或 PNG。如果是未封裝的擴充功能，圖片必須採用 PNG 格式。

如要設定圖示，請使用資訊清單中 default_icon 的 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 dip 的空間。瀏覽器動作圖示應比網頁動作圖示稍大且更醒目。
  • 請勿嘗試模仿 Google Chrome 的單色選單圖示。這與主題不搭，而且擴充功能應該要稍微突出。
  • 建議使用 Alpha 透明度，為圖示加上柔和邊緣。由於許多使用者會套用主題，因此圖示應在各種背景顏色上都能良好呈現。
  • 請勿持續為圖示加上動畫效果。真煩人。

範例

您可以在 examples/api/browserAction 目錄中找到使用瀏覽器動作的簡單範例。如需其他範例和查看原始碼的說明，請參閱「範例」。

類型

TabDetails

Chrome 88 以上版本

屬性

  • tabId

    數字 選填

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

方法

disable()

Promise 
chrome.browserAction.disable(
  tabId?: number,
  callback?: function,
): Promise<void>

停用分頁的瀏覽器動作。

參數

  • tabId

    數字 選填

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

  • callback

    函式 選填

    Chrome 67 以上版本

    callback 參數如下： 

    () => void

傳回

  • 承諾<void>

    Chrome 88 以上版本

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

enable()

Promise 
chrome.browserAction.enable(
  tabId?: number,
  callback?: function,
): Promise<void>

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

參數

  • tabId

    數字 選填

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

  • callback

    函式 選填

    Chrome 67 以上版本

    callback 參數如下： 

    () => void

傳回

  • 承諾<void>

    Chrome 88 以上版本

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

getBadgeBackgroundColor()

Promise 
chrome.browserAction.getBadgeBackgroundColor(
  details: TabDetails,
  callback?: function,
): Promise<extensionTypes.ColorArray>

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

參數

傳回

  • Chrome 88 以上版本

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

getBadgeText()

Promise 
chrome.browserAction.getBadgeText(
  details: TabDetails,
  callback?: function,
): Promise<string>

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

參數

  • 詳細資料

    TabDetails

  • callback

    函式 選填

    callback 參數如下： 

    (result: string) => void

    • 結果

      字串

傳回

  • Promise<string>

    Chrome 88 以上版本

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

getPopup()

Promise 
chrome.browserAction.getPopup(
  details: TabDetails,
  callback?: function,
): Promise<string>

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

參數

  • 詳細資料

    TabDetails

  • callback

    函式 選填

    callback 參數如下： 

    (result: string) => void

    • 結果

      字串

傳回

  • Promise<string>

    Chrome 88 以上版本

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

getTitle()

Promise 
chrome.browserAction.getTitle(
  details: TabDetails,
  callback?: function,
): Promise<string>

取得瀏覽器動作的標題。

參數

  • 詳細資料

    TabDetails

  • callback

    函式 選填

    callback 參數如下： 

    (result: string) => void

    • 結果

      字串

傳回

  • Promise<string>

    Chrome 88 以上版本

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

setBadgeBackgroundColor()

Promise 
chrome.browserAction.setBadgeBackgroundColor(
  details: object,
  callback?: function,
): Promise<void>

設定徽章的背景顏色。

參數

  • 詳細資料

    物件

    • 顏色

      string | ColorArray

      由四個整數 (範圍 0-255) 組成的陣列，代表徽章的 RGBA 顏色。也可以是包含 CSS 十六進位顏色值的字串，例如 #FF0000 或 #F00 (紅色)。以完全不透明的方式顯示顏色。

    • tabId

      數字 選填

      只有在選取特定分頁時，才會套用變更。分頁關閉時會自動重設。

  • callback

    函式 選填

    Chrome 67 以上版本

    callback 參數如下： 

    () => void

傳回

  • 承諾<void>

    Chrome 88 以上版本

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

setBadgeText()

Promise 
chrome.browserAction.setBadgeText(
  details: object,
  callback?: function,
): Promise<void>

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

參數

  • 詳細資料

    物件

    • tabId

      數字 選填

      只有在選取特定分頁時，才會套用變更。分頁關閉時會自動重設。

    • 文字

      字串 選填

      你可以傳遞任意數量的字元，但該空間只能容納約四個字元。如果傳遞空白字串 ('')，系統會清除徽章文字。如果指定 tabId，且 text 為空值，系統會清除指定分頁的文字，並預設為全域徽章文字。

  • callback

    函式 選填

    Chrome 67 以上版本

    callback 參數如下： 

    () => void

傳回

  • 承諾<void>

    Chrome 88 以上版本

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

setIcon()

Promise 
chrome.browserAction.setIcon(
  details: object,
  callback?: function,
): 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

      數字 選填

      只有在選取特定分頁時，才會套用變更。分頁關閉時會自動重設。

  • callback

    函式 選填

    callback 參數如下： 

    () => void

傳回

  • 承諾<void>

    Chrome 116 以上版本

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

setPopup()

Promise 
chrome.browserAction.setPopup(
  details: object,
  callback?: function,
): Promise<void>

設定使用者點選瀏覽器動作圖示時，要以彈出式視窗開啟的 HTML 文件。

參數

  • 詳細資料

    物件

    • 彈出式訊息

      字串

      HTML 檔案的相對路徑，用於在彈出式視窗中顯示。如果設為空字串 ('')，就不會顯示彈出式視窗。

    • tabId

      數字 選填

      只有在選取特定分頁時，才會套用變更。分頁關閉時會自動重設。

  • callback

    函式 選填

    Chrome 67 以上版本

    callback 參數如下： 

    () => void

傳回

  • 承諾<void>

    Chrome 88 以上版本

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

setTitle()

Promise 
chrome.browserAction.setTitle(
  details: object,
  callback?: function,
): Promise<void>

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

參數

  • 詳細資料

    物件

    • tabId

      數字 選填

      只有在選取特定分頁時，才會套用變更。分頁關閉時會自動重設。

    • title

      字串

      滑鼠游標懸停在瀏覽器動作上時，應顯示的字串。

  • callback

    函式 選填

    Chrome 67 以上版本

    callback 參數如下： 

    () => void

傳回

  • 承諾<void>

    Chrome 88 以上版本

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

事件

onClicked

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

在使用者點選瀏覽器動作圖示時觸發。如果瀏覽器動作有彈出式視窗，則不會觸發。

參數

  • callback

    函式

    callback 參數如下： 

    (tab: tabs.Tab) => void