通知 API 标准

要 创建通知，使用设置 对象，给定字符串 title、 NotificationOptions 字典 options，以及 环境设置对象 settings：

1. 令 origin 为 settings 的 源。

2. 令 baseURL 为 settings 的 API 基础 URL。

3. 令 fallbackTimestamp 为从 Unix 纪元 到 settings 的 当前挂钟时间 的毫秒数，舍入到 最近的整数。

4. 返回以下操作的结果：创建通知，给定 title、 options、origin、baseURL 和 fallbackTimestamp。

要 创建一个 通知，给定字符串 title、 NotificationOptions 字典 options、一个 源 origin、一个 URL baseURL，以及一个 EpochTimeStamp fallbackTimestamp：

1. 令 notification 为一个新的 通知。

2. 如果 options["renotify"] 为 true，并且 options["tag"] 为空字符串，则 抛出 一个 TypeError。

3. 将 notification 的 数据 设置为 StructuredSerializeForStorage(options["data"])。

4. 将 notification 的 标题 设置为 title。

5. 将 notification 的 方向 设置为 options["dir"]。

6. 将 notification 的 语言 设置为 options["lang"]。

7. 将 notification 的 源 设置为 origin。

8. 将 notification 的 正文 设置为 options["body"]。

9. 如果 options["navigate"] 存在，则 解析 它，使用 baseURL，如果该操作未 返回 failure，则将 notification 的 导航 URL 设置为返回值。(否则 notification 的 导航 URL 保持为 null。)

10. 将 notification 的 标记 设置为 options["tag"]。

11. 如果 options["image"] 存在，则 解析 它，使用 baseURL，如果该操作未 返回 failure，则将 notification 的 图像 URL 设置为返回值。(否则 notification 的 图像 URL 不设置。)

12. 如果 options["icon"] 存在，则 解析 它，使用 baseURL，如果该操作未 返回 failure，则将 notification 的 图标 URL 设置为返回值。(否则 notification 的 图标 URL 不设置。)

13. 如果 options["badge"] 存在，则 解析 它，使用 baseURL，如果该操作未 返回 failure，则将 notification 的 徽章 URL 设置为返回值。(否则 notification 的 徽章 URL 不设置。)

14. 如果 options["timestamp"] 存在，则将 notification 的 时间戳 设置为该值。否则，将 notification 的 时间戳 设置为 fallbackTimestamp。

15. 将 notification 的 重新通知偏好 设置为 options["renotify"]。

16. 将 notification 的 静默偏好 设置为 options["silent"]。

17. 将 notification 的 要求交互偏好 设置为 options["requireInteraction"]。

18. 将 notification 的 动作 设置为 « »。

19. 对于 options["actions"] 中的每个 entry， 数量不超过 最大动作数量 的支持值 (跳过任何 超出的条目)：

    1. 令 action 为一个新的 通知动作。

    2. 将 action 的 名称 设置为 entry["action"]。

    3. 将 action 的 标题 设置为 entry["title"]。

    4. 如果 entry["navigate"] 存在，则 解析 它，使用 baseURL，如果该操作 未返回 failure， 则将 action 的 导航 URL 设置为返回 值。 (否则 action 的 导航 URL 保持为 null。)

    5. 如果 entry["icon"] 存在，则 解析 它，使用 baseURL，如果该操作 未返回 failure， 则将 action 的 图标 URL 设置为返回值。(否则 action 的 图标 URL 保持为 null。)

    6. 将 action 追加到 notification 的 动作 中。

20. 返回 notification。

要 获取通知权限状态，运行以下 步骤：

1. 令 permissionState 为以下操作的结果：获取当前权限 状态， 使用 "notifications"。

2. 如果 permissionState 为 "prompt"，则返回 "default"。

3. 返回 permissionState。

获取步骤，给定 一个 通知 notification 和 null 或 一个 环境设置对象 settings，如下：

1. 如果通知平台支持图像，并且 notification 的 图像 URL 已设置，则 获取通知资源，给定 notification、notification 的 图像 URL、 settings，以及以下步骤，给定资源 resource：将 notification 的 图像资源 设置为 resource。

2. 如果通知平台支持图标，并且 notification 的 图标 URL 已设置，则 获取通知资源，给定 notification、notification 的 图标 URL、 settings，以及以下步骤，给定资源 resource：将 notification 的 图标资源 设置为 resource。

3. 如果通知平台支持徽章，并且 notification 的 徽章 URL 已设置，则 获取通知资源，给定 notification、notification 的 徽章 URL、 settings，以及以下步骤，给定资源 resource：将 notification 的 徽章资源 设置为 resource。

4. 如果通知平台支持动作和动作图标，则 对于每个 action，属于 notification 的 动作：如果 action 的 图标 URL 非 null，则 获取通知资源，给定 notification、 action 的 图标 URL、settings，以及 以下步骤，给定资源 resource：将 action 的 图标 资源 设置为 resource。

要 获取一个 通知资源，给定一个 通知 notification、一个 URL url、null 或一个 环境设置对象 settings，以及 一个算法 processResource，它接受一个资源：

1. 令 request 为一个新的 请求，其 URL 为 url，客户端 为 settings，目标 为 "image"，模式 为 "no-cors"，并且 凭据模式 为 "include"。

2. 如果 settings 为 null，则将 request 的 源 设置为 notification 的 源，将 request 的 引用来源 设置为 "no-referrer"，并将 request 的 服务工作线程模式 设置为 "none"。

   当用户代理显示以下通知时，就属于这种情况： 声明式推送 消息的通知。这种通知的资源在获取时不涉及 服务工作线程，因为声明式推送消息 被设计为不需要服务工作线程。 [PUSH-API]

3. 获取 request，将 useParallelQueue 设置为 true， 并将 processResponseConsumeBody 设置为 以下步骤，给定一个 响应 response，以及 null、failure 或一个 字节序列 bytes：

   1. 如果 bytes 为 null 或 failure，则返回。

   2. 尝试将 bytes 解码为图像。

   3. 如果支持该图像格式，则运行 processResource，给定解码后的 资源。

   目的是以类似于以下元素的方式获取此资源： <img>， 但这 需要抽象化。

通知 显示步骤，给定一个 通知 notification，以及 null 或一个 环境设置对象 settings， 如下：

1. 运行 获取步骤， 给定 notification 和 settings。

2. 等待所有 获取操作 完成，并等待 notification 的 图像资源、 图标资源，以及 徽章资源 设置完毕 (如果有)，以及以下 图标 资源，用于 notification 的 动作 (如果有)。

3. 令 shown 为 false。

4. 令 oldNotification 为以下 通知，位于 通知 列表 中，其 标记 不是空字符串，且等于 notification 的 标记，并且 其 源 同源 于 notification 的 源，如果存在， 否则为 null 。

5. 如果 oldNotification 非 null：

   1. 处理关闭事件，使用 oldNotification。

   2. 如果通知平台支持替换：

      1. 替换 oldNotification，使用 notification，在以下 通知列表 中。

      2. 将 shown 设置为 true。

      强烈鼓励通知平台 支持原生 替换，因为这能带来更好的用户体验。

   3. 否则，移除 oldNotification，从以下 通知列表 中。

6. 如果 shown 为 false：

   1. 追加 notification 到以下 通知列表 中。

   2. 在设备上显示 notification (例如，通过调用相应的 通知平台 API)。

7. 如果 shown 为 false，或者 oldNotification 非 null，且 notification 的 重新通知偏好 为 true，则可以选择 以用户代理定义的方式提醒最终用户 (例如，播放声音)。

8. 如果 notification 是一个 非持久化通知，则 将一个任务入队， 以 触发一个事件，名称为 show，目标为 Notification 对象，该对象表示 notification。

当一个 通知 notification，或其某个 动作 被最终用户激活时， 假设底层通知 平台支持激活，用户代理必须 (除非另有规定) 运行以下步骤：

1. 令 action 为 null。

2. 如果 notification 的某个 动作 被最终 用户激活，则将 action 设置为该 通知动作。

3. 令 navigationURL 为 notification 的 导航 URL。

4. 如果 action 非 null，则将 navigationURL 设置为 action 的 导航 URL。

   这是有意如此设计的，使得当一个 通知动作 的 导航 URL 为 null 时，它会 继续执行到 click 事件，为 Web 开发者提供更大的灵活性。

5. 如果 navigationURL 非 null：

   1. 从以下两个选项中选择一个，以 由实现定义 的方式：

      • 导航 一个现有的 顶层可遍历对象，它位于用户 代理的 顶层可遍历对象集合 中，目标为 navigationURL。

      • 创建一个全新的顶层 可遍历对象，给定 navigationURL。

      强烈鼓励用户代理遵循平台 惯例。

   2. 返回。

6. 如果 notification 是一个 持久化通知：

   1. 令 actionName 为空字符串。

   2. 如果 action 非 null，则将 actionName 设置为 action 的 名称。

   3. 触发一个服务工作线程通知 事件，名称为 "notificationclick"，给定 notification 和 actionName。

7. 否则，将一个任务入队，以运行以下步骤：

   1. 令 intoFocus 为以下操作的结果：触发一个事件，名称为 click，目标为 Notification 对象，该对象表示 notification，其 cancelable 属性初始化为 true。

      鼓励用户代理使 focus() 能够在事件 监听器内部起作用，该监听器监听名为 click 的事件。

   2. 如果 intoFocus 为 true，则用户代理应使 notification 相关的 浏览上下文 的视口获得焦点。

在整个 Web 平台中，“激活”被有意误称为“点击”。

关闭步骤，针对一个 给定的 通知 notification，如下：

1. 如果 通知列表 不 包含 notification，则中止这些步骤。

2. 处理 关闭事件，使用 notification。

3. 移除 notification，从以下 通知 列表 中。

要 处理关闭 事件，给定一个 通知 notification：

1. 如果 notification 是一个 持久化通知，并且 notification 被最终用户关闭，则 触发一个服务工作线程通知 事件，名称为 "notificationclose"，给定 notification。

2. 如果 notification 是一个 非持久化通知，则 将一个任务入队， 以 触发一个事件，名称为 close，目标为 Notification 对象，该对象表示 notification。

[Exposed=(Window,Worker)]
interface Notification : EventTarget {
  constructor(DOMString title, optional NotificationOptions options = {});

  static readonly attribute NotificationPermission permission;
  [Exposed=Window] static Promise<NotificationPermission> requestPermission(optional NotificationPermissionCallback deprecatedCallback);

  static readonly attribute unsigned long maxActions;

  attribute EventHandler onclick;
  attribute EventHandler onshow;
  attribute EventHandler onerror;
  attribute EventHandler onclose;

  readonly attribute DOMString title;
  readonly attribute NotificationDirection dir;
  readonly attribute DOMString lang;
  readonly attribute DOMString body;
  readonly attribute USVString navigate;
  readonly attribute DOMString tag;
  readonly attribute USVString image;
  readonly attribute USVString icon;
  readonly attribute USVString badge;
  readonly attribute EpochTimeStamp timestamp;
  readonly attribute boolean renotify;
  readonly attribute boolean? silent;
  readonly attribute boolean requireInteraction;
  [SameObject] readonly attribute any data;
  [SameObject] readonly attribute FrozenArray<NotificationAction> actions;

  undefined close();
};

dictionary NotificationOptions {
  NotificationDirection dir = "auto";
  DOMString lang = "";
  DOMString body = "";
  USVString navigate;
  DOMString tag = "";
  USVString image;
  USVString icon;
  USVString badge;
  EpochTimeStamp timestamp;
  boolean renotify = false;
  boolean? silent = null;
  boolean requireInteraction = false;
  any data = null;
  sequence<NotificationAction> actions = [];
};

enum NotificationPermission {
  "default",
  "denied",
  "granted"
};

enum NotificationDirection {
  "auto",
  "ltr",
  "rtl"
};

dictionary NotificationAction {
  required DOMString action;
  required DOMString title;
  USVString navigate;
  USVString icon;
};

callback NotificationPermissionCallback = undefined (NotificationPermission permission);

该 new Notification(title, options) 构造函数的步骤如下：

1. 如果 this 的 相关全局对象 是一个 ServiceWorkerGlobalScope 对象， 则 抛出 一个 TypeError。

2. 如果 options["actions"] 不是 空的，则 抛出 一个 TypeError。

   动作 仅支持用于 持久化 通知。

3. 令 notification 为以下操作的结果： 创建通知，使用一个 设置对象，给定 title、options， 以及 this 的 相关设置对象。

4. 将 this 与 notification 关联。

5. 运行以下步骤，并行 执行：

   1. 如果以下操作的结果：获取通知 权限状态，不为 "granted"，则 将一个任务入队，以 触发一个事件，名称为 error，目标为 this，并中止 这些步骤。

   2. 运行 通知显示步骤，给定 notification 和 this 的 相关设置对象。

静态 permission 获取器的步骤是 返回以下操作的结果：获取通知权限状态。

const permission = await navigator.permissions.query({name: "notifications"});
if (permission.state === "granted") {
   // 我们已获准使用此 API…
}

静态 requestPermission(deprecatedCallback) 方法的步骤如下：

1. 令 global 为 当前全局对象。

2. 令 promise 为 一个新的 promise，位于 this 的 相关 Realm 中。

3. 运行以下步骤，并行 执行：

   1. 令 permissionState 为以下操作的结果： 请求使用权限，针对 "notifications"。

   2. 将一个全局任务入队，使用 DOM 操作任务源，给定 global， 以运行以下步骤：

      1. 如果给定了 deprecatedCallback，则 调用 deprecatedCallback，使用 « permissionState » 和 "report"。

      2. 兑现 promise，使用 permissionState。

4. 返回 promise。

var not = new Notification("Paul Kalkbrenner 的 Gebrünn Gebrünn", { icon: "newsong.svg", tag: "song" });
not.onclick = function() { displaySong(this); };

self.registration.showNotification("来自 Alice 的新邮件", {
  actions: [{action: 'archive', title: "归档"}]
});

self.addEventListener('notificationclick', function(event) {
  event.notification.close();
  if (event.action === 'archive') {
    silentlyArchiveEmail();
  } else {
    clients.openWindow("/inbox");
  }
}, false);

实例 1                                   | 实例 2
                                             |
// 实例注意到有新邮件。       |
new Notification("来自 John Doe 的新邮件",   |
                 { tag: 'message1' });       |
                                             |
                                             |  // 稍后，此实例注意到
                                             |  // 有新邮件。
                                             |  new Notification("来自 John Doe 的新邮件",
                                             |                   { tag: 'message1' });

// Bob 说 "嗨"
new Notification("Bob: 嗨", { tag: 'chat_Bob' });

// Bob 说 "你今天下午有空吗？"
new Notification("Bob: 嗨 / 你今天下午有空吗？", { tag: 'chat_Bob' });

dictionary GetNotificationOptions {
  DOMString tag = "";
};

partial interface ServiceWorkerRegistration {
  Promise<undefined> showNotification(DOMString title, optional NotificationOptions options = {});
  Promise<sequence<Notification>> getNotifications(optional GetNotificationOptions filter = {});
};

[Exposed=ServiceWorker]
interface NotificationEvent : ExtendableEvent {
  constructor(DOMString type, NotificationEventInit eventInitDict);

  readonly attribute Notification notification;
  readonly attribute DOMString action;
};

dictionary NotificationEventInit : ExtendableEventInit {
  required Notification notification;
  DOMString action = "";
};

partial interface ServiceWorkerGlobalScope {
  attribute EventHandler onnotificationclick;
  attribute EventHandler onnotificationclose;
};

该 showNotification(title, options) 方法的步骤如下：

1. 令 global 为 this 的 相关全局对象。

2. 令 promise 为 一个新的 promise，位于 this 的 相关 Realm 中。

3. 如果 this 的 活动工作线程 为 null，则 拒绝 promise，使用一个 TypeError， 并返回 promise。

4. 令 notification 为以下操作的结果： 创建通知，使用一个 设置对象，给定 title、options， 以及 this 的 相关设置对象。如果此操作抛出 异常，则 拒绝 promise，使用该异常，并返回 promise。

5. 将 notification 的 服务工作线程注册 设置为 this。

6. 运行以下步骤，并行 执行：

   1. 如果以下操作的结果：获取通知 权限状态，不为 "granted"，则 将一个全局任务入队，使用 DOM 操作任务源，给定 global，以 拒绝 promise，使用一个 TypeError， 并中止这些步骤。

   2. 运行 通知显示步骤，给定 notification 和 this 的 相关设置对象。

   3. 将 notification 的 服务工作线程注册 的 是否 showNotification() 已被成功调用 设置为 true。

   4. 将一个全局任务入队，使用 DOM 操作任务源，给定 global，以 兑现 promise，使用 undefined。

7. 返回 promise。

该 getNotifications(filter) 方法的步骤如下：

1. 令 global 为 this 的 相关全局对象。

2. 令 realm 为 this 的 相关 Realm。

3. 令 origin 为 this 的 相关设置对象 的 源。

4. 令 promise 为 一个新的 promise，位于 realm 中。

5. 运行以下步骤，并行 执行：

   1. 令 tag 为 filter["tag"]。

   2. 令 notifications 为一个 列表，包含所有 通知，它们位于 通知列表 中，其 源 为 同源，相对于 origin，其 服务工作线程注册 为 this，并且 其 标记，如果 tag 不是空字符串，则为 tag。

   3. 将一个全局任务入队，使用 DOM 操作任务源，给定 global， 以运行以下步骤：

      1. 令 objects 为一个 列表。

      2. 对于每个 通知，它位于 notifications 中，按创建 顺序，创建一个 新的 Notification 对象，使用 realm，表示 通知，并 追加 它到 objects。

      3. 兑现 promise，使用 objects。

6. 返回 promise。

此方法返回零个或多个新的 Notification 对象，它们可能表示 相同的底层 通知，与以下 Notification 已有对象所表示的通知相同。

要 触发一个服务工作线程通知事件，名称为 name，给定一个 通知 notification，以及一个可选字符串 action (默认为 空字符串)：运行 触发功能事件，给定 name、NotificationEvent、 notification 的 服务工作线程注册，以及以下 初始化项：

notification

一个新的 Notification 对象，表示 notification。

action

action

notification 获取器的步骤 是 返回其初始化时的值。

action 获取器的步骤是返回 其 初始化时的值。