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

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

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

浏览器兼容性

Update compatibility data on GitHub
DesktopMobile
ChromeEdgeFirefoxOperaFirefox for Android
Basic supportChrome Full support Yes
Notes
Full support Yes
Notes
Notes If an extension defines a browser action, it is not allowed to define a page action as well.
Edge Full support 14Firefox Full support 48Opera Full support Yes
Notes
Full support Yes
Notes
Notes If an extension defines a browser action, it is not allowed to define a page action as well.
Firefox Android Full support 55
browser_styleChrome No support NoEdge No support NoFirefox Full support 48Opera No support NoFirefox Android No support No
default_areaChrome No support NoEdge No support No
Notes
No support No
Notes
Notes Microsoft Edge instead uses the browser_action_next_to_addressbar property of the browser_specific_settings manifest key
Firefox Full support 54Opera No support NoFirefox Android No support No
default_iconChrome Full support Yes
Notes
Full support Yes
Notes
Notes SVG icons are not supported.
Edge Full support 14
Notes
Full support 14
Notes
Notes SVG icons are not supported.
Notes 'default_icon' must be an object, with explicit sizes.
Firefox Full support 48Opera Full support Yes
Notes
Full support Yes
Notes
Notes SVG icons are not supported.
Firefox Android No support No
default_popupChrome Full support YesEdge Full support 14Firefox Full support 48Opera Full support YesFirefox Android Full support 57
default_titleChrome Full support YesEdge Full support 14Firefox Full support 48Opera Full support YesFirefox Android Full support 55
Notes
Full support 55
Notes
Notes Browser actions are presented as menu items, and the title is the menu item's label.
theme_iconsChrome No support NoEdge No support NoFirefox Full support 56Opera No support NoFirefox Android No support No

Legend

Full support  
Full support
No support  
No support
See implementation notes.
See implementation notes.

文档标签和贡献者

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