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/notifications.html
Title: chrome.notifications - Google Chrome 扩展程序开发文档（非官方中文版）  •  Size: 66008

chrome.notifications

描述： 使用 chrome.notifications API 通过模板创建丰富通知，并在系统托盘中向用户显示这些通知。
可用版本： 从 Chrome 28 开始稳定支持。
权限： "notifications"
了解更多： Chrome 应用办公时间：丰富的通知

注意：目前该 API 只能在 Chrome OS、Windows 和 Mac 上使用。

用法

要使用该 API，请调用 create 方法，并通过 options 参数传递通知详情： 

chrome.notifications.create(id, options, creationCallback);

NotificationOptions 必须包含 TemplateType，它定义了可用的通知详情以及这些详情是如何显示的。

所有模板类型（simple、basic、image、list）都必须包含通知的 title（标题）和 message（消息），还要包含 iconUrl（图标 URL），指向显示在通知消息左侧的小图标。image 模板类型还包含 imageUrl（图片 URL），指向在通知中预览的图片。由于 Chrome 应用严格的内容安全策略，这些 URL 都应该指向本地资源或使用数据 URL。

如下是 basic 模板的一个例子： 

var opt = {
  type: "basic",
  title: "主要标题",
  message: "要显示的主要消息",
  iconUrl: "url_to_small_icon"
}

list（列表）模板以列表的形式显示 items。 

var opt = {
  type: "list",
  title: "主要标题",
  message: "要显示的主要消息",
  iconUrl: "url_to_small_icon",
  items: [{ title: "Item1", message: "这是项目一。"},
          { title: "Item2", message: "这是项目二。"},
          { title: "Item3", message: "这是项目三。"}]
}

如果您有关于不同布局的新模板的想法，请报告问题让我们知道。

监听和响应事件

所有通知都可以包含事件监听器和事件处理函数，响应用户的操作。例如，您可以编写一个简单的事件处理函数，响应 onButtonClicked 事件。

请考虑将事件监听器和处理函数包含在事件页面中，这样即使应用或扩展程序不在运行时也能弹出通知。

chrome.notifications 参考

类型

TemplateType

enum of "basic", "image", "list", or "progress"

PermissionLevel

enum of "granted", or "denied"

NotificationBitmap

NotificationOptions

NotificationOptions 的属性

type ( optional TemplateType )

要显示哪种类型的通知，调用 create 方法时必须指定。

iconUrl ( optional string )

发送方的图标、应用图标或图片通知的缩略图，调用 create 方法时必须指定。

title ( optional string )

通知标题（例如邮件发送者的姓名），调用 create 方法时必须指定。

message ( optional string )

通知的主要内容，调用 create 方法时必须指定。

contextMessage ( optional string )

附加通知内容，以较小的字体显示。

priority ( optional integer )

优先级，从 -2 到 2，-2 优先级最低，2 最高，默认为零。

eventTime ( optional double )

与通知相关联的时间，表示为 1970 年 1 月 1 日以来所经过的毫秒数（例如 Date.now() + n）。

buttons ( optional array of object )

通知动作按钮（最多两个）的文本和图标。

每一个对象的属性

title ( string )

iconUrl ( optional string )

imageUrl ( optional string )

图片类型通知的图片缩略图。

items ( optional array of object )

多项目通知的项目。

每一个对象的属性

title ( string )

通知列表中某个项目的标题。

message ( string )

该项目的额外详情。

progress ( optional integer )

当前进度，从 0 到 100。

isClickable ( optional boolean )

是否在用户界面中显示应用会以可见的方式响应通知正文的单击。

方法

create

chrome.notifications.create(string notificationId, NotificationOptions options, function callback)

创建并显示通知。

参数

notificationId ( string )

通知的标识符。如果为空，该方法会生成一个标识符。如果匹配已有的标识符，该方法在创建操作之前会首先清除这一通知。

options ( NotificationOptions )

通知内容。

callback ( function )

返回通知标识符（提供的或生成的），代表创建的通知。

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

function(string notificationId) {...};

notificationId ( string )

update

chrome.notifications.update(string notificationId, NotificationOptions options, function callback)

更新已有的通知。

参数

notificationId ( string )

要更新的通知标识符，由 create 方法返回。

options ( NotificationOptions )

更新后的通知内容。

callback ( function )

调用时指示是否存在匹配的通知。

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

function(boolean wasUpdated) {...};

wasUpdated ( boolean )

clear

chrome.notifications.clear(string notificationId, function callback)

清除指定的通知。

参数

notificationId ( string )

要清除的通知标识符，由 create 方法返回。

callback ( function )

调用时指示是否存在匹配的通知。

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

function(boolean wasCleared) {...};

wasCleared ( boolean )

getAll

chrome.notifications.getAll(function callback)

获取所有通知。

参数

callback ( function )

返回系统中当前所有通知标识符。

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

function(object notifications) {...};

notifications ( object )

getPermissionLevel

chrome.notifications.getPermissionLevel(function callback)

获取用户是否为当前应用或扩展程序启用通知。

参数

callback ( function )

返回当前的权限级别。

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

function(PermissionLevel level) {...};

level ( PermissionLevel )

事件

onClosed

通知由系统或用户操作关闭。

addListener

chrome.notifications.onClosed.addListener(function callback)

参数

callback ( function )

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

function(string notificationId, boolean byUser) {...};

notificationId ( string )

byUser ( boolean )

onClicked

用户单击了通知中的非按钮区域。

addListener

chrome.notifications.onClicked.addListener(function callback)

参数

callback ( function )

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

function(string notificationId) {...};

notificationId ( string )

onButtonClicked

用户按下了通知中的一个按钮。

addListener

chrome.notifications.onButtonClicked.addListener(function callback)

参数

callback ( function )

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

function(string notificationId, integer buttonIndex) {...};

notificationId ( string )

buttonIndex ( integer )

onPermissionLevelChanged

用户更改了权限级别。

addListener

chrome.notifications.onPermissionLevelChanged.addListener(function callback)

参数

callback ( function )

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

function(PermissionLevel level) {...};

level ( PermissionLevel )

onShowSettings

用户单击了应用的通知设置链接。

addListener

chrome.notifications.onShowSettings.addListener(function callback)

参数

callback ( function )

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

function() {...};