Browser Actions

Contents

  1. Manifest
  2. UI的组成部分
    1. 图标
    2. tooltip
    3. Badge
    4. Popup
  3. Tips
  4. 范例
  5. API reference: chrome.browserAction
    1. Methods
      1. setBadgeBackgroundColor
      2. setBadgeText
      3. setIcon
      4. setPopup
      5. setTitle
    2. Events
      1. onClicked

用 browser actions 可以在chrome主工具条的地址栏右侧增加一个图标。作为这个图标的延展，一个browser action图标还可以有tooltip、badge和popup。

如下图, 地址栏右侧的彩色正方形是一个browser action的图标， 图标下面的是popup。

如果你想创建一个不总是可见的图标, 可以使用page action来代替browser action.

注意:Packaged apps 不能使用browser actions.

Manifest

在extension manifest中用下面的方式注册你的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 可以拥有一个图标，一个tooltip，一个badge和一个popup。

图标

Browser action 图标推荐使用宽高都为19像素，更大的图标会被缩小。

你可以用两种方式来设置图标: 使用一个静态图片或者使用HTML5canvas element。 使用静态图片适用于简单的应用程序，你也可以创建诸如平滑的动画之类更丰富的动态UI(如canvas element)。

静态图片可以是任意WebKit支持的格式，包括 BMP，GIF，ICO，JPEG或 PNG。

修改browser_action的manifest中 default_icon字段，或者调用setIcon()方法。

ToolTip

修改browser_action的manifest中default_title字段，或者调用setTitle()方法。你可以为default_title字段指定本地化的字符串；点击Internationalization查看详情。

Badge

Browser actions可以选择性的显示一个badge— 在图标上显示一些文本。Badges 可以很简单的为browser action更新一些小的扩展状态提示信息。

因为badge空间有限，所以只支持4个以下的字符。

设置badge文字和颜色可以分别使用setBadgeText()andsetBadgeBackgroundColor()。

如果browser action拥有一个popup，popup 会在用户点击图标后出现。popup 可以包含任意你想要的HTML内容，并且会自适应大小。

在你的browser action中添加一个popup，创建弹出的内容的HTML文件。 修改browser_action的manifest中default_popup字段来指定HTML文件， 或者调用setPopup()方法。

Tips

为了获得最佳的显示效果, 请遵循以下原则：

  • 确认 Browser actions 只使用在大多数网站都有功能需求的场景下。
  • 确认 Browser actions 没有使用在少数网页才有功能的场景， 此场景请使用page actions。
  • 确认你的图标尺寸尽量占满19x19的像素空间。 Browser action 的图标应该看起来比page action的图标更大更重。
  • 不要尝试模仿Google Chrome的扳手图标，在不同的themes下它们的表现可能出现问题,，并且扩展应该醒目些。
  • 尽量使用alpha通道并且柔滑你的图标边缘，因为很多用户使用themes，你的图标应该在在各种背景下都表现不错。
  • 不要不停的闪动你的图标，这很惹人反感。

范例

你可以在 examples/api/browserAction目录找到简单的browser actions范例，更多的范例和帮助文档可以参考Samples。

API reference: chrome.browserAction

Properties

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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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键值来确认你的扩展不会运行在早期的浏览器版本。

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 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 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 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 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 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 can ensure that your extension won't be run in an earlier browser version.

Types

type name