类型 Object
是否必须
示例
"browser_action": {
  "browser_style": true,
  "default_icon": {
    "16": "button/geo-16.png",
    "32": "button/geo-32.png"
  },
  "default_title": "Whereami?",
  "default_popup": "popup/geo.html"
}

浏览器按钮(browser action)指您的扩展在浏览器工具栏上所添加的按钮。该按钮有个图标,并可可选地拥有一个使用 HTML,CSS,和 JavaScript 指定内容的弹出窗口。

如果您使用弹窗(popup),则该弹窗将在用户点击该按钮时打开,并且弹窗中你所提供的运行中的 JavaScript 将可处理用户与其的交互。如果您不使用弹窗,则会在用户点击该按钮时将点击事件传递给你扩展的 background scripts 中。

您同样可以使用 browserAction API 以编程的方式创建及控制浏览器按钮。

语法

browser_action 键是一个可能有以下任何属性的对象,均是可选:

名称 类型 详细描述
browser_style Boolean
Firefox 48 中新出现

可选,默认为 false

使用此项来包含一个样式表以使其与浏览器 UI 和其它使用了 browser_style 属性的扩展外观上保持一致。虽然此键值默认为 false,还是建议您将其包含并设其为 true

在 Firefox 中,该样式表详阅 chrome://browser/content/extension.css,OS X 系统或见于 chrome://browser/content/extension-mac.css。

Firefox Style Guide 记述了为获得特定样式您所能为弹窗中元素应用的 class。

latest-download 中的示例扩展的弹窗使用了 browser_style

default_area String
Firefox 54 中新出现

定义浏览器最初放置该按钮的位置。该字符串可能是以下四个值中的一个:

  • "navbar":按钮会被放置到浏览器主工具栏中,与 URL 栏并肩。
  • "menupanel":按钮会被放置到弹出面板中。
  • "tabstrip":按钮会被放置到包含浏览器选项卡的工具栏中。
  • "personaltoolbar":按钮会被放置到书签工具栏中。

该属性只有 Firefox 支持。

这个属性是可选的,并默认为 "navbar"。

扩展不能在其被安装后主动更改其按钮的位置,但用户可以使用浏览器内置的界面定制机制来移动按钮。

default_icon ObjectString

使用此项以指定一个或多个 browser action 之图标。该图标默认显示在浏览器工具栏里。

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

你可以通过提供一个字符串以指定单个的图标文件:

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

要指定多个不同大小的图标,则在此指定一个对象。每个属性的名字是以像素记的该图标的高,且其必须被转换为一个整数。值为其 URL。示例:

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

参阅 选择图标大小 以获得此项的更多指引。

default_popup String

指向包含弹窗信息的 HTML 文件之路径

该 HTML 文件可能会使用 <link> and <script> 元素来包含 CSS 和 JavaScript,就像普通网页一样。

与普通网页不同,弹窗中运行的 JavaScript 能访问所有的 WebExtension APIs(当然,仅对于拥有适当权限的扩展)。

这是一个可本地化属性

default_title String

按钮的工具提示,在用户将鼠标移到其上时显示。

这是一个可本地化属性

选择图标大小

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

  • 图标默认是在浏览器工具栏中显示,但用户能把它挪到浏览器菜单面板里(那个在用户点击 “汉堡” 图标时打开的面板)。工具栏里的图标比菜单面板里的图标小。
  • 在像 Retina 屏的高密度显示器上,图标大要两倍。

如果浏览器在给定的情况下找不到正确尺寸的图标,它就会选最匹配的并对其缩放。缩放可能会使图标模糊,所以一件很重要的事情就是小心地选择图标尺寸。

对此有两种常用方法。你可以以 SVG 文件的形式提供单个图标,然后它就会被正确地缩放:

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

或者,您可以提供几个不同尺寸的图标,浏览器将选择最佳匹配。

Firefox 中:

所以你可以选定精确匹配的图标,不论普通屏还是 Retina 屏的显示,都仅需要提供三个图标文件,并把它们像这样确定下来:

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

如果 Firefox 找不到其需要的精确匹配的尺寸,则它会选择大于理想尺寸的已指定的最小图标。如果所有图标都小于理想尺寸,它就将选择已指定的最大图标。

示例

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

只有一个图标的浏览器按钮,指定了 2 种不同大小。其扩展的 background scripts 能接收用户点击其图标时的点击事件代码大概像这样:

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

浏览器按钮具有一个图标,一个标题,还有一个弹窗。弹窗会在用户点击按钮时出现。

对于一个简易,但是完整,使用了浏览器按钮的扩展,参见演练教程

浏览器兼容性

ChromeEdgeFirefoxFirefox for AndroidOpera
Basic Support (Yes) (Yes)4855 (Yes)
default_title (Yes) (Yes)48551 (Yes)
default_icon (Yes)2 (Yes)2 348 No (Yes)
default_popup (Yes) (Yes)48 No (Yes)
browser_style No No48 No No
default_area No No54 No No

1. Browser actions are presented as menu items, and the title is the menu item's label.

2. SVG icons are not supported.

3. 'default_icon' must be an object, with explicit sizes.

文档标签和贡献者

 此页面的贡献者: PaperFlu
 最后编辑者: PaperFlu,