chrome.notifications

说明

借助 chrome.notifications API，您可以使用模板创建内容丰富的通知，并在系统任务栏中向用户显示这些通知。

权限

notifications

类型

NotificationBitmap

NotificationButton

属性

  • iconUrl

    字符串（可选）

    从 Chrome 59 开始已废弃

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

  • title

    string

NotificationItem

属性

  • 信息

    string

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

  • title

    string

    列表通知中一项内容的标题。

NotificationOptions

属性

  • appIconMaskUrl

    字符串（可选）

    从 Chrome 59 开始已废弃

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

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

    应用图标遮罩应采用 alpha 通道，因为系统将仅考虑图片的 alpha 通道。

  • 按钮

    NotificationButton[] 可选

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

  • contextMessage

    字符串（可选）

    使用较小字体的替代通知内容。

  • eventTime

    数字可选

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

  • iconUrl

    字符串（可选）

    指向发送者头像、应用图标或图片通知缩略图的网址。

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

    **注意：**这是 notifications.create() 方法的必需值。

  • imageUrl

    字符串（可选）

    从 Chrome 59 开始已废弃

    Mac OS X 用户看不到此图像。

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

  • isClickable

    布尔值 选填

    从 Chrome 67 开始已废弃

    从 Chrome 67 开始，系统会忽略此界面提示

  • items

    NotificationItem[] 可选

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

  • 信息

    字符串（可选）

    主要通知内容。

    **注意：**这是 notifications.create() 方法的必需值。

  • 优先级

    数字可选

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

  • 进度

    数字可选

    当前进度范围从 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,
)

清除指定的通知。

参数

  • notificationId

    string

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

  • callback

    函数（可选）

    callback 参数如下所示：

    (wasCleared: boolean)=>void

    • wasCleared

      boolean

返回

  • Promise<boolean>

    Chrome 116 及更高版本

    Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。

create()

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

创建并显示通知。

参数

  • notificationId

    字符串（可选）

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

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

  • 通知的内容。

  • callback

    函数（可选）

    callback 参数如下所示：

    (notificationId: string)=>void

    • notificationId

      string

返回

  • Promise<string>

    Chrome 116 及更高版本

    Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。

getAll()

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

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

参数

  • callback

    函数（可选）

    callback 参数如下所示：

    (notifications: object)=>void

    • 通知

      对象

返回

  • Promise<object>

    Chrome 116 及更高版本

    Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。

getPermissionLevel()

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

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

参数

返回

  • Promise<PermissionLevel>

    Chrome 116 及更高版本

    Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。

update()

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

更新现有通知。

参数

  • notificationId

    string

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

  • 要更新的通知的内容。

  • callback

    函数（可选）

    callback 参数如下所示：

    (wasUpdated: boolean)=>void

    • wasUpdated

      boolean

返回

  • Promise<boolean>

    Chrome 116 及更高版本

    Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。

活动

onButtonClicked

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

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

参数

  • callback

    功能

    callback 参数如下所示：

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

    • notificationId

      string

    • buttonIndex

      number

onClicked

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

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

参数

  • callback

    功能

    callback 参数如下所示：

    (notificationId: string)=>void

    • notificationId

      string

onClosed

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

通知已关闭（由系统或用户操作）。

参数

  • callback

    功能

    callback 参数如下所示：

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

    • notificationId

      string

    • byUser

      boolean

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