跳转到内容

通知中的 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 Worker
self.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 以剪影方式绘制:每个不透明像素都变成白色(或系统强调色),带内部细节的 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 截取数组,会保留前几个按钮,由代码决定省略哪些后续按钮。数组按「主要、次要、破坏性」排列时,这样可以保留预定的优先顺序。

规范

规范状态
无。