通知中的 API
Notification 接口
发布于
Notification 表示一条已显示的通知,可用来读取属性和处理事件。页面或专用 worker 调用 new Notification(title, options) 会立即创建并显示非持久通知。对于持久通知,Service Worker 从 event.notification 取得同一接口。实例属性对应创建时传入的选项,事件报告显示、激活、关闭和失败。
new Notification(title)new Notification(title, options)notification.close()Notification.permissionNotification.maxActions构造函数暴露在 Window 以及专用和共享 worker 上,在 ServiceWorkerGlobalScope 内抛出,那里的替代是 self.registration.showNotification()。桌面端支持为 Chrome 20、Firefox 22、Safari 7、Edge 14(BCD api.Notification.Notification)。移动端方面,BCD 记录该构造函数在 Chrome for Android 和 Samsung Internet 上总是抛出异常,在 iOS 上的 Safari 中只有主屏幕 Web App 暴露该接口,发送通知仍要用 ServiceWorkerRegistration.showNotification()(细节见「异常」)。MDN 提醒几乎所有移动浏览器都会抛出异常。
实例成员均为只读,映射构造函数的 options。
| 成员 | 类型 | 含义 |
|---|---|---|
title、body、icon、image、badge |
string | 创建时传入的文本与图片 URL。缺省的选项读作 ""。 |
tag |
string | 替换键。同一源上后来带相同 tag 的通知会替换这一条。 |
data |
any | 作为 options.data 传入的可结构化克隆载荷;没有时为 null。 |
dir、lang |
string | 文字方向("auto"、"ltr"、"rtl")与 BCP 47 语言标签。 |
requireInteraction、renotify、silent |
boolean(silent 可为 null) |
行为标志;各引擎支持情况见 Notifications API 的参数表。 |
timestamp |
number | 通知所关联的时间,自纪元起的毫秒数;默认为创建时间。 |
vibrate |
数字数组 | 振动模式,Android 上的 Chromium。 |
actions |
array | 用构造函数创建的通知上为空数组,因为 options.actions 非空时构造函数会抛出异常;Service Worker 内的 event.notification 上可以有内容。 |
navigate |
string | 激活时打开的 URL,Safari 18.4。 |
事件有 show(已显示;iOS 上的 Safari 不触发)、click、close 与 error(显示失败,例如权限在检查与调用之间被撤销)。静态的 Notification.permission 见 Notification.requestPermission();Notification.maxActions 返回引擎会显示的操作按钮数量,在 Chromium 中为 2(notification.mojom 中的 kMaximumActions,chromium.googlesource.com),在 Safari 中为 undefined,因为该静态成员不存在。
| 异常 | 触发条件 |
|---|---|
TypeError |
在 Service Worker 内调用构造函数。在 NotificationConstructor 特性启用时,Chromium 的报错文本为 Illegal constructor.(notification.cc,chromium.googlesource.com)。 |
TypeError |
在 Chrome for Android 或 Samsung Internet 中从任何上下文调用构造函数;BCD 记录该构造函数在那里总是抛出(api.Notification.Notification,chrome_android)。Chromium 在那里的报错文本是 Illegal constructor. Use ServiceWorkerRegistration.showNotification() instead. |
TypeError |
options.actions 非空。Chromium 的报错文本为 Actions are only supported for persistent notifications shown using ServiceWorkerRegistration.showNotification().。 |
TypeError |
renotify 为 true 但 tag 为空,或 silent 为 true 同时设置了 vibrate。 |
ReferenceError |
iOS 与 iPadOS 上 Safari 的浏览器标签页:除非页面是 manifest 带非默认 display 的主屏幕 Web App,否则 Notification 标识符不存在。 |
权限遭拒或尚未决定时,构造函数仍会返回 Notification,随后触发 error 事件,不显示通知,也不抛出异常。因此调用前要检查 Notification.permission。
平台可用性
链接到“平台可用性”一节该接口存在于上文列出的桌面浏览器中。移动端各不相同:Chrome for Android 42 与 Samsung Internet 4 只为 Service Worker 用途暴露它,iOS 上的 Safari 16.4 只在主屏幕 Web App 内暴露它,Android WebView 没有(BCD api.Notification)。Chrome 自 49 起不在无痕模式显示通知。实例成员和事件的支持情况在 BCD 中按成员分别记录。例如 iOS 上没有 show,Safari 不支持 actions、badge、image、renotify、timestamp 与 vibrate。
构造函数示例面向桌面端。读取持久通知、检测构造函数并回退的示例也适用于 Android 和 iOS。
在桌面端显示非持久通知
链接到“在桌面端显示非持久通知”一节权限已授予时,构造函数立即显示。click 处理函数聚焦窗口并关闭通知;不调用 close() 的话,操作系统会保留它直到自己的超时。
function showOrderUpdate(orderId) { const notification = new Notification('订单已发货', { body: `订单 #${orderId} 正在路上。`, icon: '/icons/parcel.png', tag: `order-${orderId}`, data: { orderId }, }); notification.addEventListener('click', () => { window.focus(); location.hash = `#order-${notification.data.orderId}`; notification.close(); }); notification.addEventListener('error', () => console.warn('通知未显示'));}按规范,浏览器应在创建几秒后自行关闭非持久通知,并把它排除在通知中心之外,因此适合用来确认「已保存」等操作,不适合需要回头查看的消息。
在 Service Worker 中读取持久通知
链接到“在 Service Worker 中读取持久通知”一节在 notificationclick 处理函数里,同一个接口以 event.notification 到达,此时 close() 可用;actions 数组只在通知创建时带有按钮的情况下才有内容,否则为空。
self.addEventListener('notificationclick', (event) => { const { tag, data, actions } = event.notification; event.notification.close(); if (event.action === 'archive') { event.waitUntil(fetch(`/api/threads/${data.threadId}/archive`, { method: 'POST' })); return; } event.waitUntil(self.clients.openWindow(`/inbox#${tag}`));});在支持 actions 与 Notification.maxActions 的实现中,规范规定创建通知时跳过超出 maxActions 上限的条目,它们不会出现在 actions 数组中。
检测构造函数是否可用
链接到“检测构造函数是否可用”一节可靠的探测是在确认接口与权限之后,在 try 里构造。任何失败都转到持久路径,而它在 Android 和 iOS 上也是唯一的路径。
async function show(title, options) { if (!('Notification' in window) || Notification.permission !== 'granted') { return showInPage(title, options.body); // 没有接口,或没有权限 } try { return new Notification(title, options); } catch (err) { if (err.name !== 'TypeError') throw err; const registration = await navigator.serviceWorker.getRegistration(); if (!registration?.active) return showInPage(title, options.body); // 没有可退回的对象 return registration.showNotification(title, options); }}MDN 的建议是:有活动的 Service Worker 时调用 showNotification(),否则使用构造函数。
另请参阅
链接到“另请参阅”一节- Notifications API Standard: Notification interface(whatwg.org)
- Notification: Notification() constructor(developer.mozilla.org)
- Notifications API
- Notification.requestPermission()
- 通知的 actions 与 badge 选项
规范
| 规范 | 状态 |
|---|---|
| 无。 | |