browser_action

类型 对象
必需 否
清单版本 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
  }]
}

浏览器操作是扩展添加到浏览器工具栏的按钮。该按钮有一个图标，并且可以选择有一个弹出窗口，其内容使用 HTML、CSS 和 JavaScript 指定。

此键在清单 V3 扩展中被 action 替换。

您必须指定此键才能在扩展中包含浏览器工具栏按钮。指定后，您可以使用 browserAction API 以编程方式操作该按钮。

如果您提供弹出窗口，则当用户单击按钮时将打开弹出窗口，并且您的弹出窗口中运行的 JavaScript 可以处理用户与它的交互。如果您不提供弹出窗口，则当用户单击按钮时，将向您的扩展的 后台脚本 分派一个单击事件。

语法

browser_action 键是一个对象，它可能具有以下任何属性，所有这些属性都是可选的

名称 类型 描述
browser_style
可选		 布尔值

可选，默认为 false。

不要将 browser_style 设置为 true：从 Firefox 118 开始，清单 V3 中不支持它。请参阅 清单 V3 针对 browser_style 的迁移.

在 Firefox 中，可以在 chrome://browser/content/extension.css 或 macOS 上的 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 主体上使用 CSS 样式，通过添加规则 -moz-user-select 并将其值设置为 all 或 text 来允许文本选择。
default_area
可选		 字符串

定义浏览器中按钮最初放置的位置。这是一个字符串，可以取以下四个值之一

  • "navbar"：按钮放置在主浏览器工具栏中，与 URL 栏并排。
  • "menupanel"：按钮放置在弹出面板中。
  • "tabstrip"：按钮放置在包含浏览器选项卡的工具栏中。
  • "personaltoolbar"：按钮放置在书签工具栏中。

此属性仅在 Firefox 中受支持。

此属性是可选的，默认为“menupanel”。

Firefox 会记住扩展的 default_area 设置，即使该扩展被卸载并在随后重新安装也是如此。要强制浏览器确认 default_area 的新值，必须更改扩展的 ID。

扩展不能在安装后更改按钮的位置，但用户可以使用浏览器的内置 UI 自定义机制移动按钮。
default_icon
可选		 对象 或 字符串

使用此选项为浏览器操作指定一个或多个图标。图标默认显示在浏览器工具栏中。

图标被指定为相对于 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
可选		 字符串

包含弹出窗口规范的 HTML 文件的路径。

HTML 文件可以使用 <link> 和 <script> 元素包含 CSS 和 JavaScript 文件，就像普通的网页一样。但是，<script> 必须具有 src 属性才能加载文件。不要使用带有嵌入式代码的 <script>，因为您会收到令人困惑的内容违规策略错误。

与普通的网页不同，在弹出窗口中运行的 JavaScript 可以访问所有 WebExtension API（当然，前提是扩展具有适当的 权限）。

这是一个 可本地化的属性。
default_title
可选		 字符串

按钮的工具提示，在用户将鼠标悬停在按钮上时显示。如果按钮添加到浏览器的菜单面板中，则也会在应用图标下方显示此工具提示。

这是一个 可本地化的属性。
theme_icons
可选		 数组

此属性允许您为主题指定不同的图标，具体取决于 Firefox 是否检测到主题使用深色或浅色文本。

如果此属性存在，则它是一个包含至少一个 ThemeIcons 对象的数组。一个 ThemeIcons 对象包含三个必需属性

"dark"
指向图标的 URL。当使用深色文本的主题处于活动状态时（例如 Firefox Light 主题，以及如果未指定 default_icon 则使用默认主题），此图标将显示。
"light"
指向图标的 URL。当使用浅色文本的主题处于活动状态时（例如 Firefox Dark 主题），此图标将显示。
"size"
两个图标的大小（以像素为单位）。

图标被指定为相对于 manifest.json 文件本身的 URL。

您应该提供 16x16 和 32x32（用于视网膜显示屏）的 ThemeIcons。

选择图标大小

浏览器操作的图标可能需要在不同上下文中以不同的大小显示

  • 图标显示在浏览器工具栏中。旧版本的 Firefox 支持将图标放置在浏览器菜单面板（用户单击“汉堡”图标时打开的面板）中的选项。在这些版本的 Firefox 中，菜单面板中的图标比工具栏中的图标更大。
  • 在高密度显示器（如视网膜屏幕）上，图标需要大两倍。

如果浏览器在特定情况下找不到合适大小的图标，它将选择最匹配的图标并进行缩放。缩放可能会使图标看起来模糊，因此仔细选择图标大小很重要。

主要有两种方法可以解决这个问题。您可以提供单个 SVG 文件作为图标，它将被正确缩放。

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

或者，您可以提供不同大小的多个图标，浏览器将选择最匹配的图标。

在 Firefox 中

因此，您可以通过提供三个图标文件并像这样指定它们，来指定在普通和视网膜显示器上完全匹配的图标。

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

包含图标、标题和弹出窗口的浏览器操作。当用户单击按钮时，将显示弹出窗口。

有关使用浏览器操作的简单而完整的扩展程序，请参阅演练教程。

浏览器兼容性

BCD 表仅在浏览器中加载

另请参阅