chrome.notifications

refresh date: 2026-09-25 robots: noindex

说明

使用 chrome.notifications API 可通过模板创建富通知，并在系统任务栏中向用户显示这些通知。

权限

notifications

类型

NotificationBitmap

NotificationButton

属性

  • iconUrl

    字符串 可选

    自 Chrome 59 起已弃用

    Mac OS X 用户看不到按钮图标。

  • title

    字符串

NotificationItem

属性

  • 私信

    字符串

    有关此商品的其他详细信息。

  • title

    字符串

    列表通知中某一项的标题。

NotificationOptions

属性

  • appIconMaskUrl

    字符串 可选

    自 Chrome 59 起已弃用

    Mac OS X 用户看不到应用图标遮罩。

    指向应用图标遮罩的网址。网址与 iconUrl 具有相同的限制。

    应用图标遮罩应位于 Alpha 通道中，因为系统只会考虑图片的 Alpha 通道。

  • 按钮

    NotificationButton[] 可选

    最多两个通知操作按钮的文本和图标。

  • contextMessage

    字符串 可选

    使用字重较轻的字体显示备用通知内容。

  • eventTime

    number 可选

    与通知关联的时间戳，以自新纪元开始算起的毫秒数表示（例如 Date.now() + n）。

  • iconUrl

    字符串 可选

    发件人头像、应用图标或图片通知缩略图的网址。

    网址可以是数据网址、blob 网址或相对于此扩展程序的 .crx 文件中资源的网址

    **注意：**notifications.create() 方法必须提供此值。

  • imageUrl

    字符串 可选

    自 Chrome 59 起已弃用

    Mac OS X 用户无法看到该图片。

    图片类型通知的图片缩略图网址。网址与 iconUrl 具有相同的限制。

  • isClickable

    布尔值 （可选）

    自 Chrome 67 起已弃用

    自 Chrome 67 起，此界面提示会被忽略

  • 项目

    NotificationItem[] 可选

    多项通知中的内容。Mac OS X 用户只能看到第一项。

  • 私信

    字符串 可选

    主要通知内容。

    **注意：**notifications.create() 方法必须提供此值。

  • 优先级

    number 可选

    优先级范围为 -2 到 2。-2 表示最低优先级。2 表示最高。默认值为零。在不支持通知中心的平台（Windows、Linux 和 Mac）上，-2 和 -1 会导致错误，因为具有这些优先级的通知根本不会显示。

  • 进度

    number 可选

    当前进度范围为 0 到 100。

  • requireInteraction

    布尔值 （可选）

    Chrome 50 及更高版本

    表示通知应一直显示在屏幕上，直到用户激活或关闭通知。此字段默认为 false。

  • 静音

    布尔值 （可选）

    Chrome 70 及更高版本

    表示在显示通知时不应发出任何声音或振动。此字段默认为 false。

  • title

    字符串 可选

    通知的标题（例如电子邮件的发件人姓名）。

    **注意：**notifications.create() 方法必须提供此值。

  • 类型

    TemplateType 选填

    要显示的通知类型。notifications.create 方法必需。

PermissionLevel

枚举

"granted"
指定用户已选择显示来自应用或扩展程序的通知。这是安装时的默认设置。

"denied"
指定用户已选择不显示来自应用或扩展程序的通知。

TemplateType

枚举

"basic"
包含图标、标题、消息、expandedMessage 和最多两个按钮。

“image”
包含图标、标题、消息、expandedMessage、图片和最多两个按钮。

"list"
包含图标、标题、消息、内容和最多两个按钮。Mac OS X 用户只能看到第一项。

"progress"
包含图标、标题、消息、进度和最多两个按钮。

方法

clear()

Promise 
chrome.notifications.clear(
  notificationId: string,
  callback?: function,
): Promise<boolean>

清除指定的通知。

参数

  • notificationId

    字符串

    要清除的通知的 ID。此值由 notifications.create 方法返回。

  • callback

    函数可选

    callback 参数如下所示： 

    (wasCleared: boolean) => void

    • wasCleared

      布尔值

返回

  • Promise<boolean>

    Chrome 116 及更高版本

    返回一个 Promise，该 Promise 会解析为指示是否存在匹配的通知。

    只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

create()

Promise 
chrome.notifications.create(
  notificationId?: string,
  options: NotificationOptions,
  callback?: function,
): Promise<string>

创建并显示通知。

参数

  • notificationId

    字符串 可选

    通知的标识符。如果未设置或留空，系统会自动生成一个 ID。如果与现有通知匹配，此方法会先清除该通知，然后再继续执行创建操作。标识符的长度不得超过 500 个字符。

    在 Chrome 42 之前，notificationId 参数是必需的。

  • 通知的内容。

  • callback

    函数可选

    callback 参数如下所示： 

    (notificationId: string) => void

    • notificationId

      字符串

返回

  • Promise<string>

    Chrome 116 及更高版本

    返回一个 Promise，该 Promise 会解析为代表所创建通知的通知 ID（提供或生成）。

    只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

getAll()

Promise 
chrome.notifications.getAll(
  callback?: function,
): Promise<object>

检索此应用或扩展程序的所有通知。

参数

  • callback

    函数可选

    callback 参数如下所示： 

    (notifications: object) => void

    • 通知

      对象

返回

  • Promise<object>

    Chrome 116 及更高版本

    返回一个 Promise，该 Promise 会解析为系统中的一组 notification_id。

    只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

getPermissionLevel()

Promise 
chrome.notifications.getPermissionLevel(
  callback?: function,
): Promise<PermissionLevel>

检索用户是否已启用来自此应用或扩展程序的通知。

参数

返回

  • Promise<PermissionLevel>

    Chrome 116 及更高版本

    返回一个 Promise，该 Promise 会解析为当前权限级别。

    只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

update()

Promise 
chrome.notifications.update(
  notificationId: string,
  options: NotificationOptions,
  callback?: function,
): Promise<boolean>

更新现有通知。

参数

  • notificationId

    字符串

    要更新的通知的 ID。此值由 notifications.create 方法返回。

  • 要更新到的通知内容。

  • callback

    函数可选

    callback 参数如下所示： 

    (wasUpdated: boolean) => void

    • wasUpdated

      布尔值

返回

  • Promise<boolean>

    Chrome 116 及更高版本

    返回一个 Promise，该 Promise 会解析为指示是否存在匹配的通知。

    只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

事件

onButtonClicked

chrome.notifications.onButtonClicked.addListener(
  callback: function,
)

用户按下了通知中的按钮。

参数

  • callback

    函数

    callback 参数如下所示： 

    (notificationId: string, buttonIndex: number) => void

    • notificationId

      字符串

    • buttonIndex

      数值

onClicked

chrome.notifications.onClicked.addListener(
  callback: function,
)

用户点击了通知的非按钮区域。

参数

  • callback

    函数

    callback 参数如下所示： 

    (notificationId: string) => void

    • notificationId

      字符串

onClosed

chrome.notifications.onClosed.addListener(
  callback: function,
)

通知已关闭，可能是由系统关闭，也可能是由用户操作关闭。

参数

  • callback

    函数

    callback 参数如下所示： 

    (notificationId: string, byUser: boolean) => void

    • notificationId

      字符串

    • byUser

      布尔值

onPermissionLevelChanged

chrome.notifications.onPermissionLevelChanged.addListener(
  callback: function,
)

用户更改权限级别。从 Chrome 47 开始，只有 ChromeOS 具有分派此事件的界面。

参数

onShowSettings

自 Chrome 65 起已弃用
chrome.notifications.onShowSettings.addListener(
  callback: function,
)

不再支持自定义通知设置按钮。

用户点击了应用通知设置的链接。从 Chrome 47 开始，只有 ChromeOS 具有可分派此事件的界面。从 Chrome 65 开始，该界面也已从 ChromeOS 中移除。

参数

  • callback

    函数

    callback 参数如下所示： 

    () => void