chrome.pageAction

描述：	使用 `chrome.pageAction` API 在地址栏中添加图标。页面按钮代表用于当前网页的操作，但是不适用于所有网页。
可用版本：	从 Chrome 5 开始支持。
清单文件：	"page_action": {...}

例如：

订阅当前页面的 RSS 供稿
以幻灯片的方式显示此页面的照片

以下屏幕截图中的 RSS 图标是一个页面按钮，让您为当前页面订阅 RSS 供稿。

如果您希望扩展程序的图标一直可见，请改用浏览器按钮。

清单文件

在扩展程序的清单文件中注册您的页面按钮，如下所示：

      {
        "name": "我的扩展程序",
        ...
        "page_action": {
          "default_icon": {                    // 可选
            "19": "images/icon19.png",           // 可选
            "38": "images/icon38.png"            // 可选
          },
          "default_title": "Google Mail",      // 可选，在工具提示中显示
          "default_popup": "popup.html"        // 可选
        },
        ...
      }

如果您只提供 19px 或 38px 图标大小中的一个，扩展程序系统将会缩放您提供的图标，以适应用户显示器的像素密度，这有可能会丢失细节或使它看上去很模糊。注册默认图标的旧语法仍然支持：

      {
        "name": "我的扩展程序",
        ...
        "page_action": {
          ...
          "default_icon": "images/icon19.png"  // 可选
          // 与 "default_icon": { "19": "images/icon19.png" } 等价
        },
        ...
      }

用户界面的几个部分

与浏览器按钮类似，页面按钮也可以有图标、工具提示和弹出内容，不过没有徽章。此外，页面按钮可以显示和隐藏。您可以阅读浏览器按钮的用户界面了解有关图标、工具提示和弹出内容的信息。

您可以分别通过 pageAction.show 和 pageAction.hide 方法使页面按钮显示和隐藏。默认情况下，页面按钮是隐藏的。当您显示它时，您需要指定要显示图标的标签页。图标将一直显示着，直到标签页关闭或者开始显示另一个 URL（例如用户单击链接后）。

提示

为了达到最好的视觉效果，请遵循下面的指导：

对于仅对少数页面有意义的功能请使用页面按钮。
对于适用于大多数页面的功能请不要使用页面按钮，而应该使用浏览器按钮。
请不要一直使用动画图标，那样只会显得很烦人。

例子

您可以在 examples/api/pageAction 目录中找到使用页面按钮的简单例子。有关其他例子以及查看源代码的帮助，请参见示例。

摘要

类型
ImageDataType
方法
show − `chrome.pageAction.show(integer tabId)`
hide − `chrome.pageAction.hide(integer tabId)`
setTitle − `chrome.pageAction.setTitle(object details)`
getTitle − `chrome.pageAction.getTitle(object details, function callback)`
setIcon − `chrome.pageAction.setIcon(object details, function callback)`
setPopup − `chrome.pageAction.setPopup(object details)`
getPopup − `chrome.pageAction.getPopup(object details, function callback)`
事件
onClicked

类型

ImageDataType

从 Chrome 23 开始支持。

图片的像素数据，必须为 ImageData 对象（例如来自 canvas 元素）。

方法

show


              chrome.pageAction.show(integer tabId)

显示页面按钮，页面按钮在指定的标签页选定时显示。

参数
integer	tabId	您需要修改的页面按钮所在标签页的标识符。

hide


              chrome.pageAction.hide(integer tabId)

隐藏页面按钮。

参数
integer	tabId	您需要修改的页面按钮所在标签页的标识符。

setTitle


              chrome.pageAction.setTitle(object details)

设置页面按钮的标题，显示在页面按钮下的工具提示中。

参数

object

details

integer	tabId	您需要修改的页面按钮所在标签页的标识符。
string	title	工具提示字符串。

getTitle


              chrome.pageAction.getTitle(object details, function callback)

从 Chrome 19 开始支持。

获取页面按钮的标题。

参数

object

details

integer

tabId

指定要获取标题的标签页。

function

callback

callback 参数应该是一个如下形式的函数：

function(string result) {...};

string

result

setIcon


              chrome.pageAction.setIcon(object details, function callback)

设置页面按钮的图标。图标既可以指定为图片文件的路径，也可以指定来自 canvas 元素的像素数据，或者这两者中任意一个的词典。path 或 imageData 属性中有且只有一个必须指定。

参数

object

details

integer	tabId	您需要修改的页面按钮所在标签页的标识符。
ImageDataType or object	（可选） imageData	ImageData 对象或一个词典（大小 -> ImageData），表示要设置的图标。如果图标以词典的形式指定，实际使用的图标取决于屏幕的像素密度。如果单位屏幕空间容纳的图片的像素数等于 `scale`，则会选择大小为 `scale` * 19的图片。目前只支持缩放比例 1 和 2。至少要指定一个图片。注意“details.imageData = foo”等价于“details.imageData = {'19': foo}”。
string or object	（可选） path	图片的相对路径或一个词典（大小 -> 图片的相对路径），指向要设置的图标。如果图标以词典的形式指定，实际使用的图标取决于屏幕的像素密度。如果单位屏幕空间容纳的图片的像素数等于 `scale`，则会选择大小为 `scale` * 19的图片。目前只支持缩放比例 1 和 2。至少要指定一个图片。注意“details.path = foo”等价于“details.path = {'19': foo}”。
integer	（可选） iconIndex	已弃用。该参数将忽略。

function

（可选）
callback

如果您指定了 callback 参数，它应该是一个如下形式的函数：

function() {...};

setPopup


              chrome.pageAction.setPopup(object details)

设置当用户单击页面按钮的图标时显示为弹出内容的 HTML 文档。

参数

object

details

integer	tabId	您需要修改的页面按钮所在标签页的标识符。
string	popup	显示在弹出内容中的 HTML 文件。如果设为空字符串（""），则不显示弹出内容。

getPopup


              chrome.pageAction.getPopup(object details, function callback)

从 Chrome 19 开始支持。

获取设置为该页面按钮弹出内容的 HTML 文档。

参数

object

details

integer

tabId

指定要获取弹出内容的标签页。

function

callback

callback 参数应该是一个如下形式的函数：

function(string result) {...};

string

result

事件

onClicked

页面按钮的图标单击时产生，如果页面按钮有弹出内容则不会触发该事件。

addListener


                    chrome.pageAction.onClicked.addListener(function callback)

参数

function

callback

callback 参数应该是一个如下形式的函数：

function( tabs.Tab tab) {...};

tabs.Tab

tab

示例扩展程序

Animated Page Action – This extension adds an animated browser action to the toolbar.
Mappy – Finds addresses in the web page you're on and pops up a map window.