# Browser Actions
## Contents
1. [Manifest](browserAction.html#manifest)
2. [UI的组成部分](browserAction.html#ui)
1. [图标](browserAction.html#icon)
2. [tooltip](browserAction.html#tooltip)
3. [Badge](browserAction.html#badge)
4. [Popup](browserAction.html#popups)
3. [Tips](browserAction.html#H2-6)
4. [范例](browserAction.html#examples)
5. [API reference: chrome.browserAction](browserAction.html#apiReference)
1. [Methods](browserAction.html#methods)
1. [setBadgeBackgroundColor](browserAction.html#method-setBadgeBackgroundColor)
2. [setBadgeText](browserAction.html#method-setBadgeText)
3. [setIcon](browserAction.html#method-setIcon)
4. [setPopup](browserAction.html#method-setPopup)
5. [setTitle](browserAction.html#method-setTitle)
2. [Events](browserAction.html#events)
1. [onClicked](browserAction.html#event-onClicked)
用 browser actions 可以在chrome主工具条的地址栏右侧增加一个图标。作为这个图标的延展，一个browser action图标还可以有[](browserAction.html#tooltip)[tooltip](browserAction.html#tooltip)、[badge](browserAction.html#badge)和[popup](browserAction.html#popups)。
如下图, 地址栏右侧的彩色正方形是一个browser action的图标， 图标下面的是popup。
如果你想创建一个不总是可见的图标, 可以使用[page action](pageAction.html)来代替browser action.
**注意:**Packaged apps 不能使用browser actions.
## Manifest
在[extension manifest](manifest.html)中用下面的方式注册你的browser action:
```
{
"name": "My extension",
...
**"browser_action": {
"default_icon": "images/icon19.png", _// optional_
"default_title": "Google Mail", _// optional; shown in tooltip_
"default_popup": "popup.html" _// optional_
}**,
...
}
```
## UI的组成部分
一个 browser action 可以拥有一个[图标](browserAction.html#icon)，一个[tooltip](browserAction.html#tooltip)，一个[badge](browserAction.html#badge)和一个[popup](browserAction.html#popups)。
### 图标
Browser action 图标推荐使用宽高都为19像素，更大的图标会被缩小。
你可以用两种方式来设置图标: 使用一个静态图片或者使用HTML5[canvas element](http://www.whatwg.org/specs/web-apps/current-work/multipage/the-canvas-element.html)。 使用静态图片适用于简单的应用程序，你也可以创建诸如平滑的动画之类更丰富的动态UI(如canvas element)。
静态图片可以是任意WebKit支持的格式，包括 BMP，GIF，ICO，JPEG或 PNG。
修改**browser_action**的[manifest](browserAction.html#manifest)中 **default_icon**字段，或者调用[setIcon()](browserAction.html#method-setIcon)方法。
### ToolTip
修改**browser_action**的[manifest](browserAction.html#manifest)中**default_title**字段[](browserAction.html#manifest)，或者调用[setTitle()](browserAction.html#method-setTitle)方法。你可以为**default_title**字段指定本地化的字符串；点击[Internationalization](i18n.html)查看详情。
### Badge
Browser actions可以选择性的显示一个_badge_— 在图标上显示一些文本。Badges 可以很简单的为browser action更新一些小的扩展状态提示信息。
因为badge空间有限，所以只支持4个以下的字符。
设置badge文字和颜色可以分别使用[setBadgeText()](browserAction.html#method-setBadgeText)and[setBadgeBackgroundColor()](browserAction.html#method-setBadgeBackgroundColor)。
### Popup
如果browser action拥有一个popup，popup 会在用户点击图标后出现。popup 可以包含任意你想要的HTML内容，并且会自适应大小。
在你的browser action中添加一个popup，创建弹出的内容的HTML文件。 修改**browser_action**的[manifest](browserAction.html#manifest)中**default_popup**字段来指定HTML文件， 或者调用[setPopup()](browserAction.html#method-setPopup)方法。
## Tips
为了获得最佳的显示效果, 请遵循以下原则：
* **确认** Browser actions 只使用在大多数网站都有功能需求的场景下。
* **确认** Browser actions 没有使用在少数网页才有功能的场景， 此场景请使用[page actions](pageAction.html)。
* **确认**你的图标尺寸尽量占满19x19的像素空间。 Browser action 的图标应该看起来比page action的图标更大更重。
* **不要**尝试模仿Google Chrome的扳手图标，在不同的themes下它们的表现可能出现问题,，并且扩展应该醒目些。
* **尽量**使用alpha通道并且柔滑你的图标边缘，因为很多用户使用themes，你的图标应该在在各种背景下都表现不错。
* **不要**不停的闪动你的图标，这很惹人反感。
## 范例
你可以在 [examples/api/browserAction](http://src.chromium.org/viewvc/chrome/trunk/src/chrome/common/extensions/docs/examples/api/browserAction/)目录找到简单的browser actions范例，更多的范例和帮助文档可以参考[Samples](samples.html)。
## API reference: chrome.browserAction
### Properties
<a></a>
#### getLastError
chrome.extensionlastError
### Methods
#### setBadgeBackgroundColor
void chrome.browserAction.setBadgeBackgroundColor(, object `details`)
Undocumented.
设置badge的背景颜色。
#### Parameters
`details`_( optional enumerated Type array of object )_
Undocumented.
Description of this parameter from the json schema.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key [minimum_chrome_version](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version.
`color`_( optional enumerated Type array of Type array of integer paramType )_
Undocumented.
范围为[0,255]整数构成的结构，用来描述badge的RGBA颜色。例如：不透明的红色是[255, 0, 0, 255]。
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key [minimum_chrome_version](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version.
`tabId`_( optional enumerated Type array of integer )_
Undocumented.
可选参数，将设置限制在被选中的标签，当标签关闭时重置。
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key [minimum_chrome_version](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version.
#### Returns
#### Callback function
The callback _parameter_ should specify a function that looks like this:
If you specify the _callback_ parameter, it should specify a function that looks like this:
```
function(Type param1, Type param2) {...};
```
This function was added in version . If you require this function, the manifest key [minimum_chrome_version](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version.
#### setBadgeText
void chrome.browserAction.setBadgeText(, object `details`)
Undocumented.
设置browser action的badge文字，badge 显示在图标上面。
#### Parameters
`details`_( optional enumerated Type array of object )_
Undocumented.
Description of this parameter from the json schema.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key [minimum_chrome_version](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version.
`text`_( optional enumerated Type array of string )_
Undocumented.
任意长度的字符串，但只有前4个字符会被显示出来。
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key [minimum_chrome_version](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version.
`tabId`_( optional enumerated Type array of integer )_
Undocumented.
可选参数，将设置限制在被选中的标签，当标签关闭时重置。
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key [minimum_chrome_version](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version.
#### Returns
#### Callback function
The callback _parameter_ should specify a function that looks like this:
If you specify the _callback_ parameter, it should specify a function that looks like this:
```
function(Type param1, Type param2) {...};
```
This function was added in version . If you require this function, the manifest key [minimum_chrome_version](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version.
#### setIcon
void chrome.browserAction.setIcon(, object `details`)
Undocumented.
设置browser action的图标。图标可以是一个图片的路径或者是从一个canvas元素提取的像素信息.。无论是**图标路径**还是canvas的 **imageData**，这个属性必须被指定。
#### Parameters
`details`_( optional enumerated Type array of object )_
Undocumented.
Description of this parameter from the json schema.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key [minimum_chrome_version](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version.
`imageData`_( optional enumerated Type array of ImageData )_
Undocumented.
图片的像素信息。必须是一个ImageData 对象(例如：一个canvas元素)。
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key [minimum_chrome_version](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version.
`path`_( optional enumerated Type array of string )_
Undocumented.
图片在扩展中的的相对路径。
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key [minimum_chrome_version](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version.
`tabId`_( optional enumerated Type array of integer )_
Undocumented.
可选参数，将设置限制在被选中的标签，当标签关闭时重置。
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key [minimum_chrome_version](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version.
#### Returns
#### Callback function
The callback _parameter_ should specify a function that looks like this:
If you specify the _callback_ parameter, it should specify a function that looks like this:
```
function(Type param1, Type param2) {...};
```
This function was added in version . If you require this function, the manifest key [minimum_chrome_version](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version.
#### setPopup
void chrome.browserAction.setPopup(, object `details`)
Undocumented.
设置一个点击browser actions时显示在popup中的HTML。
#### Parameters
`details`_( optional enumerated Type array of object )_
Undocumented.
Description of this parameter from the json schema.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key [minimum_chrome_version](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version.
`tabId`_( optional enumerated Type array of integer )_
Undocumented.
可选参数，将设置限制在被选中的标签，当标签关闭时重置。
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key [minimum_chrome_version](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version.
`popup`_( optional enumerated Type array of string )_
Undocumented.
popup中显示的html文件。如果设置为空字符('')，将不显示popup。
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key [minimum_chrome_version](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version.
#### Returns
#### Callback function
The callback _parameter_ should specify a function that looks like this:
If you specify the _callback_ parameter, it should specify a function that looks like this:
```
function(Type param1, Type param2) {...};
```
这个功能已经在**chromium 5.0.316.0版本**添加。如果你需要这个功能，可以通过manifest的[minimum_chrome_version](manifest.html#minimum_chrome_version)键值来确认你的扩展不会运行在早期的浏览器版本。
#### setTitle
void chrome.browserAction.setTitle(, object `details`)
Undocumented.
设置browser action的标题，这个将显示在tooltip中。
#### Parameters
`details`_( optional enumerated Type array of object )_
Undocumented.
Description of this parameter from the json schema.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key [minimum_chrome_version](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version.
`title`_( optional enumerated Type array of string )_
Undocumented.
鼠标移动到browser action上时显示的文字。
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key [minimum_chrome_version](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version.
`tabId`_( optional enumerated Type array of integer )_
Undocumented.
可选参数，将设置限制在被选中的标签，当标签关闭时重置。
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key [minimum_chrome_version](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version.
#### Returns
#### Callback function
The callback _parameter_ should specify a function that looks like this:
If you specify the _callback_ parameter, it should specify a function that looks like this:
```
function(Type param1, Type param2) {...};
```
This function was added in version . If you require this function, the manifest key [minimum_chrome_version](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version.
### Events
#### onClicked
chrome.browserAction.onClicked.addListener(function(Tab tab) {...});
Undocumented.
当browser action 图标被点击的时候触发，当browser action是一个popup的时候，这个事件将不会被触发。
#### Parameters
`tab`_( optional enumerated [Tab](tabs.html#type-Tab) array of paramType )_
Undocumented.
Description of this parameter from the json schema.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key [minimum_chrome_version](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version.
### Types
<a></a>
#### type name
- 基础文档
- 综述
- 调试
- 格式：Manifest文件
- 模式匹配
- 改变浏览器外观
- Browser Actions
- Context Menus
- 桌面通知
- Omnibox
- Override替代页
- Page Actions
- 主题
- 与浏览器交互
- 书签
- Cookies
- chrome.devtools.* APIs
- Events
- chrome.history
- Management
- 标签
- 视窗
- 实现扩展
- 无障碍性(a11y)
- 背景页
- Content Scripts
- 跨域 XMLHttpRequest 请求
- 国际化 (i18n)
- 消息传递
- Optional Permissions
- NPAPI 插件
- 完成并发布应用
- 自动升级
- 托管
- 打包
- 规范和协议
- 应用设计规范
- 开发人员协议
- 免责声明