notification

Note: 此特性在 Web Worker 中可用

安全上下文

此项功能仅在安全上下文(HTTPS), 一些 支持的浏览器.

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

事件处理

Notification.onclick
处理 click (en-US) 事件的处理。每当用户点击通知时被触发。
Notification.onshow
处理 show (en-US) 事件的处理。当通知显示的时候被触发。
Notification.onerror
处理 error (en-US) 事件的处理。每当通知遇到错误时被触发。
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.

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!");
      }
    });
  }


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

See the live result

规范

规范 状态 备注
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! (en-US)

Feature Chrome Firefox (Gecko) Internet Explorer Opera Safari
Basic support 5 webkit (en-US) (see notes)
22
4.0 moz (en-US) (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 (en-US) (see notes)
22
1.0.1 moz (en-US) (see notes)
1.2
未实现 ? 未实现

Gecko 备忘

  • 在 Firefox 22 (Firefox OS <1.2) 之前,创建一个新的通知必须使用 navigator.mozNotification 对象的 createNotification 方法。
  • 在 Firefox 22 (Firefox OS <1.2) 之前,当调用 show 方法时通知才会被显示出来,并且只支持 clickclose 事件。
  • 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。

Chrome 备忘

Safari 备忘

  • Safari 在 Safari 6 版本开始支持通知,但是只能在 Mac OSX 10.8+ (Mountain Lion) 中使用。

请参见