chrome.notifications

说明

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

权限

notifications

类型

NotificationBitmap

NotificationButton

属性

  • iconUrl

    字符串（可选）

    <ph type="x-smartling-placeholder"></ph> 自 Chrome 59 起弃用

    按钮图标对 Mac OS X 用户不可见。

  • 标题

    字符串

NotificationItem

属性

  • 消息

    字符串

    关于此内容的其他详细信息。

  • 标题

    字符串

    列表通知中一项的标题。

NotificationOptions

属性

  • appIconMaskUrl

    字符串（可选）

    <ph type="x-smartling-placeholder"></ph> 自 Chrome 59 起弃用

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

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

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

  • 按钮

    NotificationButton[] 可选

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

  • contextMessage

    字符串（可选）

    使用较细字体的备用通知内容。

  • eventTime

    编号（选填）

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

  • iconUrl

    字符串（可选）

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

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

    **注意：**notifications.create() 方法需要使用此值。

  • imageUrl

    字符串（可选）

    <ph type="x-smartling-placeholder"></ph> 自 Chrome 59 起弃用

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

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

  • isClickable

    布尔值（可选）

    <ph type="x-smartling-placeholder"></ph> 自 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。

  • 标题

    字符串（可选）

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

    **注意：**notifications.create() 方法需要使用此值。

  • 类型

    TemplateType 选填

    要显示的通知类型。对于 notifications.create 方法为必需参数。

PermissionLevel

枚举

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

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

TemplateType

枚举

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

"image"
包含一个图标、标题、消息、ExpandMessage、图片以及最多两个按钮。

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

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

方法

clear()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.notifications.clear(
  notificationId: string,
  callback?: function,
)

清除指定的通知。

参数

  • notificationId

    字符串

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

  • callback

    函数（可选）

    callback 参数如下所示： 

    (wasCleared: boolean) => void

    • wasCleared

      布尔值

返回

  • Promise&lt;boolean&gt;

    Chrome 116 及更高版本

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

create()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.notifications.create(
  notificationId?: string,
  options: NotificationOptions,
  callback?: function,
)

创建并显示通知。

参数

  • notificationId

    字符串（可选）

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

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

  • 通知的内容。

  • callback

    函数（可选）

    callback 参数如下所示： 

    (notificationId: string) => void

    • notificationId

      字符串

返回

  • 承诺<字符串>

    Chrome 116 及更高版本

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

getAll()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.notifications.getAll(
  callback?: function,
)

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

参数

  • callback

    函数（可选）

    callback 参数如下所示： 

    (notifications: object) => void

    • 通知

      对象

返回

  • Promise&lt;object&gt;

    Chrome 116 及更高版本

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

getPermissionLevel()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.notifications.getPermissionLevel(
  callback?: function,
)

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

参数

返回

  • Promise&lt;PermissionLevel&gt;

    Chrome 116 及更高版本

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

update()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.notifications.update(
  notificationId: string,
  options: NotificationOptions,
  callback?: function,
)

更新现有通知。

参数

  • notificationId

    字符串

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

  • 要更新的通知的内容。

  • callback

    函数（可选）

    callback 参数如下所示： 

    (wasUpdated: boolean) => void

    • wasUpdated

      布尔值

返回

  • Promise&lt;boolean&gt;

    Chrome 116 及更高版本

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

事件

onButtonClicked

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

用户按了通知中的按钮。

参数

  • callback

    函数

    callback 参数如下所示： 

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

    • notificationId

      字符串

    • buttonIndex

      number

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

<ph type="x-smartling-placeholder"></ph> 自 Chrome 65 起弃用
chrome.notifications.onShowSettings.addListener(
  callback: function,
)

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

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

参数

  • callback

    函数

    callback 参数如下所示： 

    () => void