通知 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["silent"] 为 true 并且 options["vibrate"] 存在，则抛出 TypeError。

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

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

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

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

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

8. 将 notification 的源设置为 origin。

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

10. 如果 options["navigate"] 存在，则使用 baseURL 解析它，如果解析不返回失败，则将 notification 的导航 URL 设置为返回值。（否则 notification 的导航 URL 保持为 null。）

11. 将 notification 的标签设置为 options["tag"]。

12. 如果 options["image"] 存在，则使用 baseURL 解析它，如果解析不返回失败，则将 notification 的图像 URL 设置为返回值。（否则 notification 的图像 URL 不设置。）

13. 如果 options["icon"] 存在，则使用 baseURL 解析它，如果解析不返回失败，则将 notification 的图标 URL 设置为返回值。（否则 notification 的图标 URL 不设置。）

14. 如果 options["badge"] 存在，则使用 baseURL 解析它，如果解析不返回失败，则将 notification 的徽章 URL 设置为返回值。（否则 notification 的徽章 URL 不设置。）

15. 如果 options["vibrate"] 存在，则 验证和规范化它，并将 notification 的 振动模式设置为返回值。

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

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

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

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

20. 将 notification 的操作设置为 « »。

21. 对于 options["actions"] 中的每个 entry，直到支持的 最大操作数量（跳过任何多余的条目）：

    1. 令 action 为新的通知操作。

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

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

    4. 如果 entry["navigate"] 存在，则使用 baseURL 解析它，如果解析不返回失败，则将 action 的导航 URL 设置为返回值。 （否则 action 的导航 URL 保持为 null。）

    5. 如果 entry["icon"] 存在，则使用 baseURL 解析它，如果解析不返回失败，则将 action 的图标 URL 设置为返回值。（否则 action 的图标 URL 保持为 null。）

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

22. 返回 notification。

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

1. 令 permissionState 为使用 "notifications" 获取当前权限状态 的结果。

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

3. 返回 permissionState。

获取步骤，用于给定 通知 notification：

1. 如果通知平台支持图片，则 获取 notification 的 图片 URL（如果已设置）。

   意图是类似于 <img> 的方式获取该资源，但这 需要抽象。

   然后，并行：

   1. 等待 响应。

   2. 如果 响应的 内部响应的 类型为 "default"，则尝试将资源解码为图片。

   3. 如果图片格式受支持，则将 notification 的 图片资源 设置为解码后的资源。（否则 notification 没有 图片资源。）

2. 如果通知平台支持图标，则 获取 notification 的 图标 URL（如果已设置）。

   意图是类似于 <img> 的方式获取该资源，但这 需要抽象。

   然后，并行：

   1. 等待 响应。

   2. 如果 响应的 内部响应的 类型为 "default"，则尝试将资源解码为图片。

   3. 如果图片格式受支持，则将 notification 的 图标资源 设置为解码后的资源。（否则 notification 没有 图标资源。）

3. 如果通知平台支持徽章，则 获取 notification 的 徽章 URL（如果已设置）。

   意图是类似于 <img> 的方式获取该资源，但这 需要抽象。

   然后，并行：

   1. 等待 响应。

   2. 如果 响应的 内部响应的 类型为 "default"，则尝试将资源解码为图片。

   3. 如果图片格式受支持，则将 notification 的 徽章资源 设置为解码后的资源。（否则 notification 没有 徽章资源。）

4. 如果通知平台支持操作和操作图标，则对于 notification 的每个 action：如果 图标 URL 非空，则 获取 action 的 图标 URL。

   意图是类似于 <img> 的方式获取该资源，但这 需要抽象。

   然后，并行：

   1. 等待 响应。

   2. 如果 响应的 内部响应的 类型为 "default"，则尝试将资源解码为图片。

   3. 如果图片格式受支持，则将 action 的 图标资源 设置为解码后的资源。（否则 action 的 图标资源 保持为 null。）

通知显示步骤，用于给定的通知 notification：

1. 为 notification 运行获取步骤。

2. 等待任何获取完成，以及 notification 的 图像资源、 图标资源和 徽章资源 被设置（如果有），以及 notification 的 操作的 图标 资源（如果有）。

3. 令 shown 为 false。

4. 令 oldNotification 为通知列表中的通知，其标签不是空字符串且与 notification 的标签相同， 并且其源与 notification 的源同源（如果有），否则为 null。

5. 如果 oldNotification 非 null，则：

   1. 用 oldNotification 处理关闭事件。

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

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

      2. 将 shown 设置为 true。

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

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

6. 如果 shown 为 false，则：

   1. 将 notification 附加到通知列表。

   2. 在设备上显示 notification（例如，通过调用适当的通知平台 API）。

7. 如果 shown 为 false 或 oldNotification 非 null，并且 notification 的重新通知偏好为 true，则为 notification 运行提醒步骤。

8. 如果 notification 是非持久通知，则队列任务以在代表 notification 的 Notification 对象上触发事件，事件名为 show。

当通知 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. 给定 notification 和 actionName，触发 Service Worker 通知 事件，事件名为 "notificationclick"。

7. 否则，队列任务以运行以下步骤：

   1. 令 intoFocus 为在代表 notification 的 Notification 对象上触发事件的结果，事件名为 click，其 cancelable 属性初始化为 true。

      鼓励用户代理使 focus() 在名为 click 的事件的事件监听器中工作。

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

在整个 Web 平台中，"activate" 故意被错误命名为 "click"。

关闭步骤，用于给定的 通知 notification：

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

2. 用 notification 处理 关闭事件。

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

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

1. 如果 notification 是持久通知且 notification 被终端用户关闭，则给定 notification，触发 Service Worker 通知 事件，事件名为 "notificationclose"。

2. 如果 notification 是非持久通知，则队列任务以在代表 notification 的 Notification 对象上触发事件，事件名为 close。

提醒步骤，用于提醒终端用户关于给定的 通知 notification：

1. 使用 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;
  [SameObject] readonly attribute FrozenArray<unsigned long> vibrate;
  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;
  VibratePattern vibrate;
  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运行通知显示步骤。

静态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("Gebrünn Gebrünn by Paul Kalkbrenner", { 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 为在this的相关 Realm中一个新的 promise。

3. 如果this的活动 worker为 null，则用一个TypeError拒绝 promise 并返回 promise。

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

5. 将 notification 的service worker 注册设置为 this。

6. 并行运行以下步骤：

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

   2. 为 notification 运行通知显示步骤。

   3. 将notification的service worker 注册的 是否已成功调用 showNotification() 设置为 true。

   4. 在DOM 操作任务源上排队一个全局任务，给定 global 以用 undefined 解决 promise。

7. 返回 promise。

getNotifications(filter) 方法的步骤是：

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

2. 让 realm 为this的相关 Realm。

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

4. 让 promise 为在 realm 中一个新的 promise。

5. 并行运行以下步骤：

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

   2. 让 notifications 为通知列表中所有通知的列表，这些通知的源与 origin 同源，其service worker 注册为this，并且 如果 tag 不是空字符串，其标签为 tag。

   3. 在DOM 操作任务源上排队一个全局任务，给定 global 以运行以下步骤：

      1. 让 objects 为一个列表。

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

      3. 用 objects 解决 promise。

6. 返回 promise。

此方法返回零个或多个新的Notification 对象，这些对象可能代表与已存在的Notification 对象相同的底层通知。

要触发一个 service worker 通知事件，名为 name，给定一个 通知 notification，以及一个可选字符串 action（默认为空字符串）：运行触发功能性事件，给定 name、NotificationEvent、 notification 的service worker 注册，以及以下初始化：

notification

一个代表 notification 的新 Notification 对象。

action

action

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

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