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(例如用户单击链接后)。

提示

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

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

摘要

类型
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 元素的像素数据,或者这两者中任意一个的词典。pathimageData 属性中有且只有一个必须指定。

参数
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