browser\_action
===============

|  |  |
| --- | --- |
| 类型 | `Object` |
| 是否必须 | 否 |
| 示例 | 
```json
"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` | `Object` 或 `String` | 
 使用此项以指定一个或多个 browser action
 之图标。该图标默认显示在浏览器工具栏里。

图标使用相对于 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>`
 and
 `<script>`
 元素来包含 CSS 和 JavaScript，就像普通网页一样。


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

这是一个可本地化属性。 |
| `default_title` | `String` | 按钮的工具提示，在用户将鼠标移到其上时显示。
这是一个可本地化属性。 |

选择图标大小
------

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

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

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

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


```json
"default\_icon": "path/to/geo.svg"
```


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

Firefox 中：

* 工具栏中图标的默认宽高为 16 \* `window.devicePixelRatio`。
* 菜单面板中图标的默认宽高为 32 \* `window.devicePixelRatio`。

所以你可以选定精确匹配的图标，不论普通屏还是 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"
  }
}
```


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


```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 tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.