This page was saved using WebZIP 7.0.3.1030 offline browser on 12/24/13 11:31:36.
Address: https://crxdoc-zh.appspot.com/extensions/pageAction.html
Title: chrome.pageAction - Google Chrome 扩展程序开发文档（非官方中文版）  •  Size: 44888

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" } 等价
  },
  ...
}

用户界面的几个部分

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

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

提示

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

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

例子

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

chrome.pageAction 参考

类型

ImageDataType

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

方法

show

chrome.pageAction.show(integer tabId)

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

参数

tabId ( integer )

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

hide

chrome.pageAction.hide(integer tabId)

隐藏页面按钮。

参数

tabId ( integer )

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

setTitle

chrome.pageAction.setTitle(object details)

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

参数

details ( object )

属性

tabId ( integer )

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

title ( string )

工具提示字符串。

getTitle

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

获取页面按钮的标题。

参数

details ( object )

属性

tabId ( integer )

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

callback ( function )

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

function(string result) {...};

result ( string )

setIcon

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

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

参数

details ( object )

属性

tabId ( integer )

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

imageData ( optional ImageDataType or object )

ImageData 对象或一个词典（大小 -> ImageData），表示要设置的图标。如果图标以词典的形式指定，实际使用的图标取决于屏幕的像素密度。如果单位屏幕空间容纳的图片的像素数等于 scale，则会选择大小为 scale * 19的图片。目前只支持缩放比例 1 和 2。至少要指定一个图片。注意“details.imageData = foo”等价于“details.imageData = {'19': foo}”。

path ( optional string or object )

图片的相对路径或一个词典（大小 -> 图片的相对路径），指向要设置的图标。如果图标以词典的形式指定，实际使用的图标取决于屏幕的像素密度。如果单位屏幕空间容纳的图片的像素数等于 scale，则会选择大小为 scale * 19的图片。目前只支持缩放比例 1 和 2。至少要指定一个图片。注意“details.path = foo”等价于“details.path = {'19': foo}”。

iconIndex ( optional integer )

已弃用。该参数将忽略。

callback ( optional function )

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

function() {...};

setPopup

chrome.pageAction.setPopup(object details)

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

参数

details ( object )

属性

tabId ( integer )

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

popup ( string )

显示在弹出内容中的 HTML 文件。如果设为空字符串（""），则不显示弹出内容。

getPopup

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

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

参数

details ( object )

属性

tabId ( integer )

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

callback ( function )

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

function(string result) {...};

result ( string )

事件

onClicked

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

addListener

chrome.pageAction.onClicked.addListener(function callback)

参数

callback ( function )

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

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

tab ( tabs.Tab )