操作

类型 对象
强制
清单版本 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
  }]
}

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

此键在清单 V3 扩展中替换了 browser_action

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

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

语法

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

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

可选,默认为 false

不要将 browser_style 设置为 true:其在清单 V3 中的支持已在 Firefox 118 中删除。请参阅 清单 V3 迁移指南,了解 browser_style

default_area
可选
字符串

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

  • "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
可选
字符串

包含弹出窗口规范的 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 中,菜单面板中的图标大于工具栏中的图标。
  • 在像 Retina 显示屏这样的高密度显示屏上,图标需要大两倍。

如果浏览器在给定情况下找不到合适大小的图标,它将选择最佳匹配项并对其进行缩放。缩放可能会使图标显得模糊,因此仔细选择图标大小非常重要。

主要有两种方法可以实现这一点。您可以提供单个图标作为 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
"action": {
  "default_icon": {
    "16": "button/geo-16.png",
    "32": "button/geo-32.png"
  }
}

仅用两个大小指定了图标的操作。当用户单击图标时,扩展的后台脚本可以接收单击事件,使用类似于以下代码的代码

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

具有图标、标题和弹出窗口的操作。当用户单击按钮时,将显示弹出窗口。

浏览器兼容性

BCD 表格仅在浏览器中加载