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"
}

一个带有图标、标题和弹出窗口的浏览器操作。当用户点击按钮时,将显示弹出窗口。

有关一个简单但完整的、使用浏览器操作的扩展程序,请参阅 教程

浏览器兼容性

另见