action

型別 Object
必填
Manifest 版本 3 或更高版本
示例
json
"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
  }]
}

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

此鍵在 Manifest V3 擴充套件程式中取代了 browser_action

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

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

語法

action 鍵是一個物件,可以包含以下任意屬性,所有屬性都是可選的。

名稱 型別 描述
browser_style
可選
已棄用
Boolean

可選,預設為 false

請勿將 browser_style 設定為 true:其在 Firefox 118 中已從 Manifest V3 中移除支援。請參閱 browser_style 的 Manifest V3 遷移

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
"action": {
  "default_icon": {
    "16": "button/geo-16.png",
    "32": "button/geo-32.png"
  }
}

一個只包含圖示的操作,指定了 2 種大小。當用戶單擊該圖示時,擴充套件程式的背景指令碼可以使用類似如下的程式碼接收點選事件:

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

一個包含圖示、標題和彈出視窗的操作。單擊按鈕時會顯示彈出視窗。

瀏覽器相容性