notification - Web API 接口参考编辑

Note: 此特性在 Web Worker 中可用。

Secure context
This feature is available only in secure contexts (HTTPS), in some or all supporting browsers.

Notifications API 的通知接口用于向用户配置和显示桌面通知。

构造方法

let notification = new Notification(title, options)

参数

title

一定会被显示的通知标题

options 可选

一个被允许用来设置通知的对象。它包含以下属性：

dir : 文字的方向；它的值可以是 auto（自动）, ltr（从左到右）, or rtl（从右到左）
lang: 指定通知中所使用的语言。这个字符串必须在 BCP 47 language tag 文档中是有效的。
body: 通知中额外显示的字符串
tag: 赋予通知一个ID，以便在必要的时候对通知进行刷新、替换或移除。
icon: 一个图片的URL，将被用于显示通知的图标。

属性

静态属性

这些属性仅在 Notification 对象上有效。

Notification.permission 只读: 一个用于表明当前通知显示授权状态的字符串。可能的值包括：denied (用户拒绝了通知的显示), granted (用户允许了通知的显示), 或 default (因为不知道用户的选择，所以浏览器的行为与 denied 时相同).

实例属性

这些属性仅在 Notification 的实例中有效。

Notification.title 只读 (moz only): 在构造方法中指定的 title 参数。
Notification.dir 只读: 通知的文本显示方向。在构造方法的 options 中指定。
Notification.lang 只读: 通知的语言。在构造方法的 options 中指定。
Notification.body 只读: 通知的文本内容。在构造方法的 options 中指定。
Notification.tag 只读: 通知的 ID。在构造方法的 options 中指定。
Notification.icon 只读: 通知的图标图片的 URL 地址。在构造方法的 options 中指定。

事件处理

Notification.onclick: 处理 click 事件的处理。每当用户点击通知时被触发。
Notification.onshow: 处理 show 事件的处理。当通知显示的时候被触发。
Notification.onerror: 处理 error 事件的处理。每当通知遇到错误时被触发。
Notification.onclose: 处理 close 事件的处理。当用户关闭通知时被触发。

方法

静态方法

这些方法仅在 Notification 对象中有效。

Notification.requestPermission(): 用于当前页面向用户申请显示通知的权限。这个方法只能被用户行为调用（比如：onclick 事件），并且不能被其他的方式调用。

实例方法

这些方法仅在 Notification 实例或其 prototype 中有效。

Notification.close(): 用于关闭通知。

Notification 对象继承自 EventTarget 接口。

EventTarget.addEventListener(): Registers an event handler of a specific event type on the EventTarget.
EventTarget.removeEventListener(): Removes an event listener from the EventTarget.
EventTarget.dispatchEvent(): Dispatches an event to this EventTarget.

Additional methods in Mozilla chrome codebase

Mozilla includes a couple of extensions for use by JS-implemented event targets to implement onevent properties.

Example

假定有如下 HTML：

<button onclick="notifyMe()">Notify me!</button>

接下来发送一条通知：

function notifyMe() {
  // 先检查浏览器是否支持
  if (!("Notification" in window)) {
    alert("This browser does not support desktop notification");
  }

  // 检查用户是否同意接受通知
  else if (Notification.permission === "granted") {
    // If it's okay let's create a notification
    var notification = new Notification("Hi there!");
  }

  // 否则我们需要向用户获取权限
  else if (Notification.permission !== "denied") {
    Notification.requestPermission().then(function (permission) {
      // 如果用户接受权限，我们就可以发起一条消息
      if (permission === "granted") {
         var notification = new Notification("Hi there!");
      }
    });
  }


  // 最后，如果执行到这里，说明用户已经拒绝对相关通知进行授权
  // 出于尊重，我们不应该再打扰他们了
}

规范

规范	状态	备注
Notifications API	Living Standard	Initial specification.

权限

当你要在开放 web 应用中使用通知时，请确保将 desktop-notification 权限添加到你的 manifest 文件中。通知可以被用于任何权限级别，hosted 或更高。

"permissions": {
    "desktop-notification":{}
}

We're converting our compatibility data into a machine-readable JSON format. This compatibility table still uses the old format, because we haven't yet converted the data it contains. Find out how you can help!

Desktop
Mobile

Feature	Chrome	Firefox (Gecko)	Internet Explorer	Opera	Safari
Basic support	5 webkit (see notes) 22	4.0 moz (see notes) 22	未实现	25	6 (see notes)

Feature	Android	Firefox Mobile (Gecko)	Firefox OS	IE Mobile	Opera Mobile	Safari Mobile
Basic support	?	4.0 moz (see notes) 22	1.0.1 moz (see notes) 1.2	未实现	?	未实现

Gecko 备忘

在 Firefox 22 (Firefox OS <1.2) 之前，创建一个新的通知必须使用 navigator.mozNotification 对象的 createNotification 方法。
在 Firefox 22 (Firefox OS <1.2) 之前，当调用 show 方法时通知才会被显示出来，并且只支持 click 和 close 事件。
Nick Desaulniers 编写了一个 Notification shim 以向前和向后兼容各种版本的实现。
在 Firefox OS 有个特别的问题，你可以传递一个图标路径用于通知，但是如果应用被打包了你就不能使用相对路径，比如： /my_icon.png。同样的，你也不能这样用： window.location.origin + "/my_icon.png"，因为 window.location.origin 的值在打包的应用里为 null。清单来源字段可以修复这个问题，但是这个方法只在 Firefox OS 1.1+ 版本中有效。不过有个潜在的解决方案可以用于 Firefox OS <1.1 版本，就是传递图标的位于外部服务器的绝对 URL 。这个方案并不理想，如通知要立即显示而没有图标，那么将会请求服务器，但是可以用于所有版本的 Firefox OS。