browser_action

型別 Object
必填
Manifest 版本 2
示例
json
"browser_action": {
  "default_icon": {
    "16": "button/geo-16.png",
    "32": "button/geo-32.png"
  },
  "default_title": "Whereami?",
  "default_popup": "popup/geo.html",
  "theme_icons": [{
    "light": "icons/geo-16-light.png",
    "dark": "icons/geo-16.png",
    "size": 16
  }, {
    "light": "icons/geo-32-light.png",
    "dark": "icons/geo-32.png",
    "size": 32
  }]
}

瀏覽器操作(browser action)是擴充套件程式在瀏覽器工具欄中新增的一個按鈕。該按鈕帶有一個圖示,並且可以選擇性地帶有彈出視窗,其內容使用 HTML、CSS 和 JavaScript 指定。

此鍵在 Manifest V3 擴充套件中已被 action 鍵取代。

要包含瀏覽器工具欄按鈕,您必須指定此鍵。指定後,您可以使用 browserAction API 以程式設計方式操作該按鈕。

如果您提供了彈出視窗,則使用者點選按鈕時會開啟該彈出視窗,您在彈出視窗中執行的 JavaScript 可以處理使用者與之的互動。如果您未提供彈出視窗,則當用戶點選按鈕時,將向擴充套件程式的 背景指令碼 分派一個點選事件。

語法

browser_action 鍵是一個物件,可能包含以下任何屬性,均為可選屬性。

名稱 型別 描述
browser_style
可選
Boolean

可選,預設為 false

請勿將 browser_style 設定為 true:自 Firefox 118 起,它在 Manifest V3 中不受支援。請參閱 browser_style 的 Manifest V3 遷移

在 Firefox 中,您可以在 macOS 上透過 chrome://browser/content/extension.css 或 chrome://browser/content/extension-mac.css 檢視樣式表。在設定尺寸時,請注意此樣式表設定了 box-sizing: border-box(請參閱 box-sizing)。

瀏覽器樣式 描述了您可以應用於彈出視窗中元素的類,以獲得特定的樣式。

來自 latest-download 的示例擴充套件在其彈出視窗中使用了 browser_style

注意:browser_style 設定為 true 會阻止使用者選擇擴充套件程式的彈出視窗或側邊欄內容中的文字。這是正常行為。您無法選擇瀏覽器中 UI 的部分。但是,您可以透過兩種方式來規避此限制,允許使用者選擇文字:

  1. browser_style 設定為 false
  2. 對側邊欄或彈出視窗的 HTML 的 body 使用 CSS 樣式,透過新增值為 alltext-moz-user-select 規則來允許文字選擇。
default_area
可選
String

定義按鈕最初放置在瀏覽器的哪個部分。這是一個字串,可以取四個值之一:

  • "navbar": 按鈕放置在主瀏覽器工具欄中,緊鄰 URL 欄。
  • "menupanel": 按鈕放置在彈出面板中。
  • "tabstrip": 按鈕放置在包含瀏覽器標籤頁的工具欄中。
  • "personaltoolbar": 按鈕放置在書籤工具欄中。

此屬性僅在 Firefox 中受支援。

此屬性是可選的,預設為 "menupanel"。

Firefox 會記住擴充套件程式的 default_area 設定,即使該擴充套件程式被解除安裝並重新安裝。要強制瀏覽器識別 default_area 的新值,必須更改擴充套件程式的 ID。

擴充套件程式安裝後無法更改按鈕的位置,但使用者可以使用瀏覽器內建的 UI 自定義機制移動按鈕。

default_icon
可選
ObjectString

使用此選項指定瀏覽器操作的一個或多個圖示。預設情況下,該圖示會顯示在瀏覽器工具欄中。

圖示指定為相對於 manifest.json 檔案本身的 URL。

您可以透過在此處提供一個字串來指定單個圖示檔案。

json
"default_icon": "path/to/geo.svg"

要指定不同尺寸的多個圖示,請在此處指定一個物件。每個屬性的名稱是圖示的畫素高度,並且必須可轉換為整數。值是 URL。例如:

json
    "default_icon": {
      "16": "path/to/geo-16.png",
      "32": "path/to/geo-32.png"
    }

您不能指定相同尺寸的多個圖示。

有關更多指導,請參閱 選擇圖示尺寸

default_popup
可選
String

包含彈出視窗規格的 HTML 檔案的路徑。

HTML 檔案可以使用 <link><script> 元素包含 CSS 和 JavaScript 檔案,就像普通網頁一樣。但是,<script> 必須具有 src 屬性才能載入檔案。請勿使用帶有嵌入式程式碼的 <script>,否則您將收到令人困惑的內容策略違規錯誤。

與普通網頁不同,在彈出視窗中執行的 JavaScript 可以訪問所有 WebExtension API(當然,前提是擴充套件程式具有相應的 許可權)。

這是一個 可本地化屬性

default_title
可選
String

按鈕的工具提示,當用戶將滑鼠懸停在其上時顯示。如果按鈕被新增到瀏覽器的菜單面板,這裡也會顯示應用程式圖示下的標題。

這是一個 可本地化屬性

theme_icons
可選
Array

此屬性使您能夠為不同主題指定不同的圖示,具體取決於 Firefox 是檢測到主題使用了深色文字還是淺色文字。

如果此屬性存在,則它是一個包含至少一個 ThemeIcons 物件的陣列。ThemeIcons 物件包含三個必需屬性:

"dark"
指向圖示的 URL。當啟用使用深色文字的主題時(例如 Firefox Light 主題,以及未指定 default_icon 的 Default 主題),將顯示此圖示。
"light"
指向圖示的 URL。當啟用使用淺色文字的主題時(例如 Firefox Dark 主題),將顯示此圖示。
"size"
兩個圖示的畫素尺寸。

圖示指定為相對於 manifest.json 檔案的 URL。

您應該提供 16x16 和 32x32(用於視網膜顯示屏)的 ThemeIcons

選擇圖示尺寸

在不同情況下,瀏覽器操作的圖示可能需要以不同尺寸顯示。

  • 圖示顯示在瀏覽器工具欄中。舊版本的 Firefox 支援將圖示放置在瀏覽器菜單面板(使用者單擊“漢堡包”圖示時開啟的面板)的選項。在那些版本的 Firefox 中,菜單面板中的圖示比工具欄中的圖示要大。
  • 在高密度顯示屏(如 Retina 螢幕)上,圖示需要大一倍。

如果瀏覽器在給定情況下找不到合適尺寸的圖示,它會選擇最佳匹配並進行縮放。縮放可能會使圖示顯得模糊,因此仔細選擇圖示尺寸非常重要。

有兩種主要方法可以做到這一點。您可以提供單個 SVG 檔案圖示,它會被正確縮放。

json
"default_icon": "path/to/geo.svg"

或者,您可以提供多種不同尺寸的圖示,瀏覽器會選擇最佳匹配。

在 Firefox 中

因此,您可以透過提供三個圖示檔案並像這樣指定它們,來精確匹配正常和 Retina 顯示屏的尺寸:

json
"default_icon": {
  "16": "path/to/geo-16.png",
  "32": "path/to/geo-32.png",
  "64": "path/to/geo-64.png"
}

如果 Firefox 找不到與所需尺寸完全匹配的圖示,它將選擇指定尺寸中大於理想尺寸的最小圖示。如果所有圖示都小於理想尺寸,它將選擇指定尺寸中最大的圖示。

示例

json
"browser_action": {
  "default_icon": {
    "16": "button/geo-16.png",
    "32": "button/geo-32.png"
  }
}

一個只有圖示的瀏覽器操作,以兩種不同尺寸指定。當用戶使用類似這樣的程式碼點選圖示時,擴充套件程式的背景指令碼可以接收點選事件:

js
browser.browserAction.onClicked.addListener(handleClick);
json
"browser_action": {
  "default_icon": {
    "16": "button/geo-16.png",
    "32": "button/geo-32.png"
  },
  "default_title": "Whereami?",
  "default_popup": "popup/geo.html"
}

一個帶有圖示、標題和彈出視窗的瀏覽器操作。當用戶點選按鈕時,將顯示彈出視窗。

有關一個簡單但完整的、使用瀏覽器操作的擴充套件程式,請參閱 教程

瀏覽器相容性

另見