ServiceWorkerRegistration:showNotification() 方法

安全上下文: 此项功能仅在一些支持的浏览器安全上下文(HTTPS)中可用。

备注: 此特性在 Web Worker 中可用。

ServiceWorkerRegistration 接口的 showNotification() 方法在一个活动状态下的 Service Worker 上创建通知。

语法

js
showNotification(title)
showNotification(title, options)

参数

title

定义通知的标题,显示在通知窗口的顶部。

options 可选

允许配置通知的对象。它可以具有以下属性:

actions 可选 实验性

要在通知中显示的一系列操作的数组,默认值为空数组。数组中的每个元素都是一个具有以下成员的对象:

action

一个标识要在通知上显示的用户操作的字符串。

title

一个包含要向用户显示的操作文本的字符串。

icon 可选

一个包含与操作一起显示的图标 URL 的字符串。

使用 notificationclick 事件中的 event.action 构建适当的响应。

badge 可选 实验性

一个当没有足够的空间来显示通知本身(例如 Android 通知栏)时来表示通知的图像 URL 的字符串。在 Android 设备上,徽章应适应高达 4 倍分辨率(约 96 x 96 像素)的设备,并且图像将被自动遮罩。

body 可选

一个表示通知正文的字符串,显示在标题下方,默认值是一个空字符串。

data 可选 实验性

你想要与通知关联的任意数据。它可以是任何可结构化克隆的数据类型。默认值为 null

dir 可选

表示通知的方向。默认为 auto,即采用浏览器的语言设置行为,但你可以通过设置 ltrrtl 的值来覆盖该行为(尽管大多数浏览器似乎会忽略这些设置)。

icon 可选

一个包含要在通知中显示的图标的 URL 的字符串。

image 可选 实验性

一个包含要在通知中显示的图像的 URL 的字符串。

lang 可选

指定通知的语言,根据 RFC 5646: 识别语言的标签(也被称为 BCP47)使用表示语言标签的字符串指定。请参阅 Sitepoint ISO 2 字母语言代码页面以获取简单参考。默认值为空字符串。

renotify 可选 实验性

一个布尔值,指示重复使用 tag 值时是否阻止振动和声音提醒。默认为 false,表示不会通知。如果为 true,则还必须设置 tag 参数。

requireInteraction 可选 实验性

表示通知应保持活动状态直到用户点击或关闭它,而不是自动关闭。默认值为 false

silent 可选

一个布尔值,用于指定通知是否静音(不发出声音或振动),无论设备设置如何。默认值为 null,表示遵循设备默认值。如果为 true,则 vibrate 参数不得指定。

tag 可选

表示通知的标签的字符串。默认值为空字符串。

timestamp 可选

一个时间戳,以毫秒为单位的 Unix 时间,表示与通知关联的时间。这可能是在过去,当通知用于因设备离线而无法立即发送的消息时,或者在将来,当通知用于即将开始的会议时。

vibrate 可选 实验性

设备振动硬件随通知一起发出的振动模式。当该值被指定时,silent 参数不得设置为 true

返回值

一个兑现 undefinedPromise

异常

TypeError

如果当前 Service Worker 的状态不是 activatingactivated,或者用户明确拒绝了浏览器使用 API 的权限请求,则抛出该异常。

TypeError

如果满足以下条件之一,则抛出该异常:

  • 当前 service worker 的状态不是 activatingactivated
  • 用户已明确拒绝浏览器使用该 API 的权限请求。
  • silent 选项是 truevibrate 选项被同时指定。
  • renotify 选项是 true 但是 tag 选项为空值。
DataCloneError DOMException

若由于某种原因序列化 data 选项失败,则抛出该异常。

示例

js
navigator.serviceWorker.register("sw.js");

function showNotification() {
  Notification.requestPermission().then((result) => {
    if (result === "granted") {
      navigator.serviceWorker.ready.then((registration) => {
        registration.showNotification("Vibration Sample", {
          body: "Buzz! Buzz!",
          icon: "../images/touch/chrome-touch-icon-192x192.png",
          vibrate: [200, 100, 200, 100, 200, 100, 200],
          tag: "vibration-sample",
        });
      });
    }
  });
}

要在适当的时间调用上述函数,你可以监听 notificationclick 事件。

你还可以使用以下 ServiceWorkerRegistration.getNotifications() 方法检索当前 Service Worker 已触发的 Notification 的详细信息。

规范

Specification
Notifications API
# dom-serviceworkerregistration-shownotification

浏览器兼容性

Report problems with this compatibility data on GitHub
desktopmobile
Chrome
Edge
Firefox
Opera
Safari
Chrome Android
Firefox for Android
Opera Android
Safari on iOS
Samsung Internet
WebView Android
WebView on iOS
showNotification
options.actions parameter
Experimental
options.badge parameter
options.data parameter
Experimental
options.image parameter
Experimental
options.renotify parameter
Experimental
options.requireInteraction parameter
Experimental
options.vibrate parameter
Experimental

Legend

Tip: you can click/tap on a cell for more information.

Full support
Full support
No support
No support
Experimental. Expect behavior to change in the future.
See implementation notes.