chrome.browserAction

說明

可用性

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

如果您想建立的圖示不是一律處於啟用狀態，請使用網頁動作，而非瀏覽器動作。

資訊清單

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

{
  "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.5x 或 1.2x) 的裝置越來越多，建議您為圖示提供多種尺寸。這也能確保如果圖示顯示大小有所變更，您就不需要再提供其他圖示！

系統仍支援註冊預設圖示的舊語法：

{
  "name": "My extension",
  ...
  "browser_action": {
    ...
    "default_icon": "images/icon32.png"  // optional
    // equivalent to "default_icon": { "32": "images/icon32.png" }
  },
  ...
}

使用者介面的部分

瀏覽器動作可以包含圖示、工具提示、徽章和彈出式視窗。

圖示

Chrome 中的瀏覽器動作圖示寬度和高度為 16 個 dip (裝置獨立像素)。較大的圖示會調整大小以符合螢幕尺寸，但為了獲得最佳效果，請使用 16 像素正方形圖示。

您可以使用靜態圖片或 HTML5 畫布元素，以兩種方式設定圖示。使用靜態圖片可讓簡單的應用程式更容易操作，但您可以使用畫布元素建立更多動態 UI，例如流暢的動畫。

靜態圖片可採用 WebKit 支援的任何格式，包括 BMP、GIF、ICO、JPEG 或 PNG。如果是未解壓縮的擴充功能，圖片必須為 PNG 格式。

如要設定圖示，請使用資訊清單中的 default_icon 的 default_icon 欄位，或呼叫 browserAction.setIcon 方法。

為了在螢幕像素密度 (比例 size_in_pixel / size_in_dip) 與 1 不同時正確顯示圖示，可以將圖示定義為一組不同大小的圖片。系統會從集合中選取實際要顯示的圖片，以便最適合 16 個像素點大小。圖示集合可包含任何大小的圖示規格，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 方法。

訣竅

如要獲得最佳視覺效果，請遵循下列規範：

• 請針對大多數網頁上適合的功能使用瀏覽器動作。
• 不要將瀏覽器動作用於僅適用於少數網頁的功能。請改用頁面動作。
• 請使用大且色彩鮮豔的圖示，充分運用 16 x 16 點的空間。瀏覽器動作圖示應比網頁動作圖示稍大且較醒目。
• 請勿模仿 Google Chrome 的單色選單圖示。這對主題設計不太適合，而且擴充功能應與主題有所區隔。
• 請使用 Alpha 透明度，為圖示加入柔和邊緣。由於許多人都會使用主題，因此您的圖示應能在各種背景顏色下看起來很棒。
• 請勿持續為圖示加上動畫效果。這真是令人困擾。

範例

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

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

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

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

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

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

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

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

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

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

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

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

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