通知 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. 将 notification 的标签设置为 options["tag"]。

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

21. 返回 notification。

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

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

2. 如果 permissionState 是“prompt”，则返回“default”。

3. 返回 permissionState。

给定通知 notification 的获取步骤如下：

1. 如果通知平台支持图像，并且设置了图像 URL，则获取notification的图像 URL。

   目的是像获取 <img> 资源一样获取此资源，但这需要抽象化。

   然后，并行地：

   1. 等待响应。

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

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

2. 如果通知平台支持图标，并且设置了图标 URL，则获取notification的图标 URL。

   目的是像获取 <img> 资源一样获取此资源，但这需要抽象化。

   然后，并行地：

   1. 等待响应。

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

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

3. 如果通知平台支持徽章，并且设置了徽章 URL，则获取notification的徽章 URL。

   目的是像获取 <img> 资源一样获取此资源，但这需要抽象化。

   然后，并行地：

   1. 等待响应。

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

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

4. 如果通知平台支持操作和操作图标，则对于 notification 的操作中的每个 action：如果图标 URL非 null，则获取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. 如果 notification 是一个持久性通知，则：

   1. 令 action 为空字符串。

   2. 如果用户激活了 notification 的操作之一，则将 action 设置为该通知操作的名称。

   3. 给定 notification 和 action，触发一个名为“notificationclick”的服务工作线程通知事件。

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

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

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

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

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

给定通知 notification 的关闭步骤如下：

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

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

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

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

1. 如果 notification 是一个持久性通知并且 notification 是由最终用户关闭的，则给定 notification 触发一个名为“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 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 = "";
  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 icon;
};

callback NotificationPermissionCallback = undefined (NotificationPermission permission);

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

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

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

   操作仅支持持久性通知。

3. 令 notification 为给定 title、options 和此的相关设置对象使用设置对象创建通知的结果。

4. 将此与 notification 关联。

5. 并行运行以下步骤：

   1. 如果获取通知权限状态的结果不是 "granted"，则将一个任务排队以在此上触发一个名为 error 的事件，并中止这些步骤。

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

静态 permission getter 步骤是返回获取通知权限状态的结果。

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

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

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

2. 令 promise 为此的相关 Realm中的一个新 promise。

3. 并行运行以下步骤：

   1. 令 permissionState 为请求使用“notifications”权限的结果。

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

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

      2. 使用 permissionState 解决 promise。

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("New mail from Alice", {
  actions: [{action: 'archive', title: "Archive"}]
});

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

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

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

// Bob 说 "你今天下午有空吗？"
new Notification("Bob: Hi / 你今天下午有空吗？", { 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 为此的相关全局对象。

2. 令 promise 为此的相关 Realm 中的一个新 promise。

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

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

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

6. 并行运行以下步骤：

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

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

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

7. 返回 promise。

getNotifications(filter) 方法步骤如下：

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

2. 令 realm 为此的相关 Realm。

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

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

5. 并行运行以下步骤：

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

   2. 令 notifications 为通知列表中所有通知的列表，这些通知的源与 origin 同源，其服务工作线程注册为此，并且如果 tag 不是空字符串，则其标签为 tag。

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

      1. 令 objects 为一个列表。

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

      3. 用 objects 解决 promise。

6. 返回 promise。

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

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

notification

一个代表 notification 的新 Notification 对象。

action

action

notification getter 步骤是返回其初始化时的值。

action getter 步骤是返回其初始化时的值。