通知中的 API
通知的 actions 与 badge 选项
发布于 更新于
actions 为持久通知添加按钮,badge 为 Android 状态栏等放不下完整通知的位置提供小型单色图片。两者都在 ServiceWorkerRegistration.showNotification() 的 options 字典中设置。已发布的浏览器中,Chromium 支持这两个选项,Firefox 152 支持 actions。它们与 Badging API 设置的应用图标计数无关。
registration.showNotification(title, { badge: '/icons/badge-96.png', actions: [{ action: 'reply', title: '回复', icon: '/icons/reply.png' }],})Notification.maxActions只有 showNotification() 接受 actions;向 new Notification() 传入非空数组会抛出 TypeError。Notification.maxActions 是静态 getter,返回实现支持的 action 数量上限。支持情况:actions 在 Chrome 53、Edge 18、Firefox 152;badge 在 Chrome 53、Edge 18;Safari 两者都不支持(BCD api.Notification.actions、api.Notification.badge)。
| 成员 | 类型 | 含义 |
|---|---|---|
actions[].action |
string | 在 notificationclick 中以 event.action 返回的标识符。必填。 |
actions[].title |
string | 按钮文字。必填。 |
actions[].icon |
string(URL),可选 | 在绘制图标的平台(Android;Windows 不绘制)上显示在按钮上的图片。 |
actions[].navigate |
string(URL),可选 | 支持时,用户代理导航到该 URL 而不触发 notificationclick。Chromium 忽略它。 |
badge |
string(URL) | 紧凑形态使用的图片。Android 会把它遮罩成剪影并以最高 4 倍密度显示,因此带透明背景的 96 × 96 像素单色 PNG 是可用的尺寸。 |
Chromium 最多显示 kMaximumActions = 2 个按钮(notification.mojom,chromium.googlesource.com),多余的不报错直接丢弃;Firefox 152 通过 maxActions 报告自己的上限。读取这个 getter,不要把 2 写死。
| 异常 | 触发条件 |
|---|---|
TypeError |
new Notification() 上的 actions 非空。Chromium:Actions are only supported for persistent notifications shown using ServiceWorkerRegistration.showNotification(). |
TypeError |
某个 action 对象缺少 action 或 title,这两个是必填的字典成员。 |
不支持的选项不是异常:Firefox 152 之前的版本和 Safari 忽略 actions,Chromium 之外的所有引擎忽略 badge,通知仍会显示,只是缺少被忽略的功能。
支持位置
链接到“支持位置”一节actions 与 badge 在 Chrome 53(2016 年)一起发布,BCD 列出两者自 Edge 18 起支持;Firefox 在 152 加入了 actions 但仍忽略 badge;Safari 在 macOS 和 iOS 上两者都不支持,通知按钮不属于其 Web 通知界面(BCD api.Notification.actions、api.Notification.badge)。MDN 说明平台在放不下完整通知时才使用 badge,例如在状态栏中;实际显示哪些图片取决于浏览器和操作系统。
页面调用 showNotification() 显示通知,Service Worker 处理器读取 event.action,响应用户选择的操作。
两个按钮,各自一个处理分支
链接到“两个按钮,各自一个处理分支”一节Service Worker 读取 event.action。空字符串表示点的是通知主体,其他值是某个 action id。
// 页面await registration.showNotification('Ada 发来新消息', { body: '能把电话改到下午 3 点吗?', badge: '/icons/badge-96.png', tag: 'thread-42', data: { threadId: 42 }, actions: [ { action: 'reply', title: '回复' }, { action: 'mute', title: '静音此会话' }, ],});
// Service Workerself.addEventListener('notificationclick', (event) => { event.notification.close(); const { threadId } = event.notification.data; if (event.action === 'mute') { event.waitUntil(fetch(`/api/threads/${threadId}/mute`, { method: 'POST' })); } else { event.waitUntil(self.clients.openWindow(`/threads/${threadId}${event.action === 'reply' ? '#compose' : ''}`)); }});Chromium 的上限是两个,所以按「主要操作、破坏性操作」的顺序放;第三个按钮会被丢弃。
为 badge 图片定尺寸
链接到“为 badge 图片定尺寸”一节badge 以剪影方式绘制:每个不透明像素都变成白色(或系统强调色),带内部细节的 logo 会变成一团。导出一个 96 × 96 像素、透明背景的单色图形。
await registration.showNotification('下载完成', { body: 'report-2026-q3.pdf', icon: '/icons/icon-192.png', // 全彩,显示在文字旁 badge: '/icons/badge-96.png', // 单色,显示在状态栏});icon 与 badge 各有显示位置,可以同时设置。如果只设置 icon,Android 状态栏会显示浏览器自己的图标。
检测选项并在不支持处省略它们
链接到“检测选项并在不支持处省略它们”一节浏览器支持这些选项时,Notification.prototype 上会有相应属性。按条件构建选项对象,同一个调用就能在 Safari 和 Firefox 里工作。
function notificationOptions(base, buttons) { if (!('Notification' in window)) return null; // 完全没有通知 const options = { ...base }; if ('badge' in Notification.prototype) options.badge = '/icons/badge-96.png'; if ('actions' in Notification.prototype && Notification.maxActions > 0) { options.actions = buttons.slice(0, Notification.maxActions); } return options;}按 maxActions 截取数组,会保留前几个按钮,由代码决定省略哪些后续按钮。数组按「主要、次要、破坏性」排列时,这样可以保留预定的优先顺序。
另请参阅
链接到“另请参阅”一节- Notifications API Standard: actions(whatwg.org)
- Notification: actions property(developer.mozilla.org)
- Notifications API
- Notification 接口
- Badging API
规范
| 规范 | 状态 |
|---|---|
| 无。 | |