跳转到内容

通知中的 API

Notification 接口

发布于

Notification 表示一条已显示的通知,可用来读取属性和处理事件。页面或专用 worker 调用 new Notification(title, options) 会立即创建并显示非持久通知。对于持久通知,Service Worker 从 event.notification 取得同一接口。实例属性对应创建时传入的选项,事件报告显示、激活、关闭和失败。

new Notification(title)
new Notification(title, options)
notification.close()
Notification.permission
Notification.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('通知未显示'));
}

按规范,浏览器应在创建几秒后自行关闭非持久通知,并把它排除在通知中心之外,因此适合用来确认「已保存」等操作,不适合需要回头查看的消息。

在 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(),否则使用构造函数。

规范

规范状态
无。