notifications.bs

<pre class="metadata">
Title: 通知 API
Group: WHATWG
H1: 通知 API
Shortname: notifications
Status: LS
No Editor: true
Abstract: 该标准定义了一个 API 来给终端用户显示通知，通常显示在顶层浏览上下文视口。
该 API 被设计成与现有的通知系统兼容，但依然是平台独立的。
Logo: https://resources.whatwg.org/logo-notifications.svg
!参与: <a href="https://github.com/whatwg/notifications/issues/new">提交错误报告</a> (<a href="https://github.com/whatwg/notifications/issues">打开错误报告</a>)
!参与: <a href="https://whatwg.org/mailing-list">whatwg@whatwg.org</a> (<a href="https://whatwg.org/mailing-list#specs">存档</a>)
!参与: <a href="http://wiki.whatwg.org/wiki/IRC">IRC: #whatwg on Freenode</a>
!提交: <a href="https://github.com/whatwg/notifications/commits">https://github.com/whatwg/notifications/commits</a>
!提交: <a href="https://twitter.com/notifyapi">@notifyapi</a>
Indent: 2
</pre>

<h2 id=terminology>术语</h2>

<p>本规范中使用的一些术语取自DOM、Fetch、HTML、IDL、URL 和 振动 API 标准。
[[!DOM]]
[[!FETCH]]
[[!HTML]]
[[!WEBIDL]]
[[!URL]]
[[!VIBRATION]]


<h2 id=notifications>通知</h2>

<p><dfn lt="concept notification">通知</dfn>是事件发生的抽象表示，如信息发出。

<p><a lt="concept notification">通知</a>有一个关联的 DOMString 类型的
<dfn lt="concept title">标题</dfn>。

<p><a lt="concept notification">通知</a>有一个关联的 DOMString 类型的
<dfn>主体</dfn>。

<p><a lt="concept notification">通知</a>有一个关联的
<dfn lt="concept direction">方向</dfn>，其值是
<i>auto</i>、<i>ltr</i> 和 <i>rtl</i> 三者之一。

<p><a lt="concept notification">通知</a>有一个关联的 DOMString 类型的
<dfn lt="concept language">语言</dfn>，其值是一个有效的 BCP 47 语言标记或空字符串。

<p><a lt="concept notification">通知</a>有一个关联的 DOMString 类型的
<dfn>标签</dfn>。

<p><a lt="concept notification">通知</a>有一个关联的<dfn>数据</dfn>.

<p><a lt="concept notification">通知</a>有一个关联的
<dfn lt="concept origin">起源</dfn>.

<p><a lt="concept notification">通知</a>有一个关联的未被设置的
<dfn>重通知偏好标志</dfn>。设置该标志表示运行<a>替代步骤</a>后，最终用户会被警告。

<p><a lt="concept notification">通知</a>有一个关联的未被设置的
<dfn>静音偏好标志</dfn>。设置该标志表示不接收声音或者振动通知。

<p><a lt="concept notification">通知</a>有一个关联的未被设置的
<dfn>屏幕关闭偏好标志</dfn>。设置该标志表示设备屏幕不会被启用。

<p><a lt="concept notification">通知</a>有一个关联的未被设置的
<dfn>粘性偏好设置</dfn>。设置该标志表示最终用户将不能很容易地清除
<a lt="concept notification">通知</a>。<span class=note>仅适用于<a>持久通知</a>。

<p><a lt="concept notification">通知</a><em>可以</em>有相关联的
<dfn>图标 URL</dfn>、<dfn>图标资源</dfn>、<dfn>声音 URL</dfn>、
<dfn>声音资源/dfn>、<dfn>振动模式</dfn>以及。

<p class=note>不鼓励开发者通过图标、声音或振动模式来给最终用户传达信息；除非这些信息
是最终用户可以访问的。

<p><dfn>非持久通知</dfn>是没有关联<dfn>服务线程注册</dfn>的
<a lt="concept notification">通知</a>。

<p><dfn>持久通知</dfn>是关联了<dfn>服务线程注册</dfn>的
<a lt="concept notification">通知</a>。

<!-- XXX https://html.spec.whatwg.org/#fingerprinting-vector -->

<hr>

<p>为<dfn>创建通知</dfn>, 给定一个 <var>title</var> 和 <var>options</ar>，执行
这些步骤：

<ol>
  <li><p>设 <var>notification</var> 是一个新的
  <a lt="concept notification">通知</a>.

  <li><p>如果 <var>options</var> 的 <code>silent</code> 为 true, 那么
  <var>options</var> 的 <code>sound</code> 或者 <var>options</var> 的
  <code>vibrate</code> 出现时，<a>抛出</a> <code>TypeError</code> 异常。

  <li><p>如果 <var>options</var> 的 <code>renotify</code> 为 true 并且
  <var>options</var> 的 <code>tag</code> 为空字符串，那么<a>抛出</a>
  <code>TypeError</code> 异常.

  <li><p>设置 <var>notification</var> 的 <a>data</a> 为<a>结构化克隆</a>的
  <var>options</var> 的 <code>data</code>。重新抛出任何异常。

  <li><p>设置 <var>notification</var> 的 <a lt="concept title">title</a>
  为 <var>options</var> 的 <code>title</code>。

  <li><p>设置 <var>notification</var> 的 <a lt="concept direction">direction</a>
  为 <var>options</var> 的 <code>dir</code>。

  <li><p>如果 <var>options</var> 的 <code>lang</code> 是一个有效的 BCP 47 
  语言标记或空字符串, 设置 <var>notification</var> 的
  <a lt="concept language">language</a> 为 <var>options</var> 的
  <code>lang</code>；否则将之设置为空字符串。 [[!LANG]]

  <li><p>设置 <var>notification</var> 的 <a lt="concept origin">origin</a> 为
  <a>入口设置对象</a> 的 <a>origin</a>。

  <li><p>设置 <var>notification</var> 的 <a>主体</a> 为 <var>options</var> 的
  <code>body</code>。

  <li><p>设置 <var>notification</var> 的 <a>tag</a> 为 <var>options</var> 的
  <code>tag</code>。

  <li><p>设 <var>baseURL</var> 为<a>入口设置对象</a>指定的 API 基础 URL。
  <span class=XXX>或现任？</span>

  <li><p>如果 <var>options</var> 存在 <code>icon</code>，使用 <var>baseURL</var>
  来<a lt="url parser">解析</a>之；解析无误时，设置 <var>notification</var> 的
  <a>icon URL</a> 为该解析值。（否则<a>图标 URL</a>未设置。）

  <li><p>如果 <var>options</var> 存在 <code>sound</code>，使用 <var>baseURL</var>
  <a lt="url parser">解析</a> 之； 解析无误时，设置 <var>notification</var> 的
  <a>sound URL</a> 为该解析值。（否则<a>声音 URL</a>未设置。）

  <li><p>如果 <var>options</var> 存在 <code>vibrate</code>，<a>验证并规范化</a>之，
  并设置 <var>notification</var> 的<a>振动模式</a>为该规范化值。
 （否则<a>振动模式</a>未设置。）

  <li><p>如果 <var>options</var> 的 <code>renotify</code> 为 true，设置
  <var>notification</var> 的<a>重通知偏好标志</a>。

  <li><p>如果 <var>options</var> 的 <code>silent</code> 为 true，设置
  <var>notification</var> 的<a>静音偏好标志</a>。

  <li><p>如果 <var>options</var> 的 <code>noscreen</code> 为 true，设置
  <var>notification</var> 的<a>屏幕关闭偏好标志</a>。

  <li><p>如果 <var>options</var> 的 <code>sticky</code> 为 true，设置
  <var>notification</var> 的<a>粘性偏好设置</a>。

  <li><p>返回 <var>notification</var>。
</ol>


<h3 id=lifetime-and-ui-integrations>Lifetime and UI integration</h3>

<p>用户代理必须保留一个由零或多个<a lt="concept notification">通知</a>组成的
<dfn>通知列表</dfn>。

<p>用户代理应该在创建<a>非持久通知</a>之后的几秒种内执行<a>关闭步骤</a>。

<p>用户代理不应该在平台的“通知中心”（如果有的话）显示<a>非持久通知</a>。

<p>用户代理应该保持<a>持久通知</a>，直至被移除出<a>通知列表</a>。

<p class=example>A <a>持久通知</a>可通过其 {{Notification}} 对象来调用
{{close()!!method}} 方法。

<p>用户代理应该在平台的“通知中心”（如果有的话）显示<a>持久通知</a>。


<h3 id=permission-model>许可模式</h3>

<p>当且仅当用户（或用户代理）授予<dfn>许可</dfn>时，才能显示
<a lt="concept notification">通知</a>。为给定<a>起源</a>显示
<a lt="concept notification">通知</a>的<a>许可</a>是下面三个字符串之一：

<dl>
  <dt>"<code>default</code>"
  <dd><p>相当于 "<code>denied</code>"，但用户没有作出明确的选择。

  <dt>"<code>denied</code>"
  <dd><p>意味着用户不希望被<a lt="concept notification">通知</a>。

  <dt>"<code>granted</code>"
  <dd><p>意味着可以显示<a lt="concept notification">通知</a>。
</dl>

<p class=note>"<code>default</code>"从不会等同于"<code>granted</code>"。如果那样
的话，"<code>granted</code>"会被滥用，应用程序再也不必请求<a>许可</a>。


<h3 id=direction>方向</h3>

<p>本节所使用的术语等同于 HTML 规范中渲染部分所使用的。[[!HTML]]

<!-- 保持同步：
     https://html.spec.whatwg.org/multipage/rendering.html#text-rendered-in-native-user-interfaces -->

<p>期望用户代理使用 Unicode 语义来解析<a lt="concept notification">通知</a>的
<a lt="concept title">标题</a>和<a>主题</a>中的文本。展示它们时，应视之为由双向
算法规则P1、P2和P3所定义的一个或多个双向算法段落组成的独立集合，例如包括支持换行
符 U+000A (LF) 带来的段落分割。对<a lt="concept title">标题</a>和<a>主题</a>中的
每一段，<a lt="concept notification">通知</a>的<a lt="concept direction">方向</a>
属性在其值非 "<code>auto</code>" 时，将覆盖双向算法P2和P3规则。 [[!BIDI]]


<h3 id=language>语言</h3>

<!-- 保持同步：
     https://html.spec.whatwg.org/multipage/dom.html#attr-lang -->

<p><a lt="concept notification">通知</a>的<a lt="concept language">语言</a>属性
指定了<a lt="concept notification">通知</a>的<a lt="concept title">标题</a>和
<a>主题</a>的主要语言。语言属性值要么是一个有效的 BCP 47 语言标记，要么是一个空
字符串。空字符串表示主要语言是未知的。 [[!LANG]]


<h3 id=resources>资源</h3>

<p>对给定<a lt="concept notification">通知</a> <var>notification</var>，其
<dfn>获取步骤/dfn>是：

<ol>
  <!-- XXX https://www.w3.org/Bugs/Public/show_bug.cgi?id=24055 -->
  <li><p>如果通知平台支持图标，并且通知设置了 <a>图标 URL</a>，则<a>获取</a>
  <var>notification</var> 的 <a>图标 URL</a>。

  <p>然后，<a>并行进行</a>：

  <ol>
    <li><p>等待<a>回应</a>。

    <li><p>如果<a>响应</a>的<a>内部反应</a>的<a lt="response type">类型</a>是
    <i>默认的</i>，试图作为图像解码该资源。

    <li><p>如果平台支持该图像格式，设置 <var>notification</var> 的<a>图标资源</a>
    为该解码后的资源。（否则 <var>notification</var> 没有 <a>图标资源</a>。）
  </ol>

  <li><p>如果通知平台支持声音，并且通知设置了<a>声音 URL</a>，则<a>获取</a>
  <var>notification</var> 的 <a>声音 URL</a>。

  <p>然后, <a>并行进行</a>：

  <ol>
    <li><p>等待<a>回应</a>。

    <li><p>如果<a>响应</a>的<a>内部反应</a>的<a lt="response type">类型</a>是
    <i>默认的</i>，试图作为声音解码该资源。
    <!-- XXX xref -->

    <li><p>如果平台支持该声音格式，设置 <var>notification</var> 的
    <a>声音资源</a> 为解码后的资源。（否则，<var>notification</var> 没有 
    <a>sound 声音资源</a>。）
  </ol>
</ol>


<h3 id=showing-a-notification>显示通知</h3>

<p>对给定<a lt="concept notification">通知</a> <var>notification</var>，其
<dfn>显示步骤</dfn>是：

<ol>
  <li><p>如果<a>通知列表</a>里存在某一<a lt="concept notification">通知</a>，
  其<a>标签</a>非空字符串且等于 <var>notification</var> 的<a>标签</a>，其
  <a lt="concept origin">起源</a>和 <var>notification</var> 的
  <a lt="concept origin">起源</a><a>同源</a> ，那么对该
  <a lt="concept notification">通知</a>和 <var>notification</var> 执行
  <a>更换步骤</a>，而后终止这些步骤。

  <li><p>否则，对 <var>notification</var> 执行<a>展示步骤</a>。
</ol>


<h3 id=activating-a-notification>激活通知</h3>

<p>当用户激活<a lt="concept notification">通知</a> <var>notification</var> 时，
假设底层通知平台支持激活，用户代理必须（除非另有规定）执行这些步骤：

<ol>
  <li><p>如果 <var>notification</var> 是 <a>持久通知</a>，执行这些子步骤：

  <ol>
    <li><p>设 <var>callback</var> 是 <var>global</var> 所调用的一种算法，对给定
    <var>global</var> 上的 <var>notification</var>
    <a lt="fire a service worker notification event named e">
    触发服务线程通知事件</a> <code>notificationclick</code>。

    <li><p>而后对 <var>notification</var> 的<a>服务线程注册</a>和
    <var>callback</var> 运行<a>处理功能事件</a>。
  </ol>

  <li><p>否则，<a>排队一个任务</a>来执行这些子步骤：

  <ol>
    <li><p>在表示 <var>notification</var> 的 {{Notification}} 对象上
    <a lt="concept event fire">触发事件</a> <code>click</code>，其
    <code><a lt="dom event cancelable">cancelable</a></code> 属性初始化为 true。

    <p class="note">鼓励用户代理在 <code>click</code> 事件监听器中使用 <code>
    <a lt="dom window focus">window.focus()</a></code>。

    <li><p>如果没有设置该<a lt="concept event">事件</a>的<a>取消标志</a>，用户
    代理应该聚焦 <var>notification</var> 相关的<a>浏览上下文</a>的视口。
  </ol>
</ol>

<p class="note">纵观整个网络平台，“激活”被故意名不副实地称为“点击”。


<h3 id=closing-a-notification>关闭通知</h3>

<p>不论是底层通知平台还是用户，在关闭<a lt="concept notification">通知</a>时，
都必须执行<a>关闭步骤</a>。

<p>对给定 <var>notification</var>，其<dfn>关闭步骤</dfn>是:

<ol>
  <li><p>如果 <var>notification</var> 不在<a>通知列表</a>中，终止这些步骤。

  <li><p>从<a>通知列表</a>中删除 <var>notification</var>。
</ol>


<h3 id=displaying-notification>展示通知</h3>

<p>对给定 <var>notification</var>，其<dfn>展示步骤</dfn>是：

<ol>
  <li><p>等待所有的<a lt="fetch">获取</a>完成，并且如果有的话，设置好
  <var>notification</var> 的 <a>图标资源</a>和<a>声音资源</a>。

  <li><p>在设备上展示 <var>notification</var> （例如通过调用相应的通知平台）。

  <p>同时，如果有的话，播放 <var>notification</var> 的<a>声音资源</a>，使用
  <var>notification</var> 的<a>震动模式</a>来<a>执行震动</a>。

  <li><p>追加 <var>notification</var> 到<a>通知列表</a>。
</ol>


<h3 id=replacing-a-notification>更换通知</h3>

<p>将<a lt="concept notification">通知</a> <var>old</var> 更换为 <var>new</var>
的<dfn>更换换步骤</dfn>是：

<ol>
  <li><p>等待所有的<a lt="fetch">获取</a>完成，并且如果有的话，设置好
  <var>notification</var> 的 <a>图标资源</a>和<a>声音资源</a>。

  <li><p>在<a>通知列表</a>相同的位置，将 <var>old</var> 更换为 <var>new</var>。

  <p>如果通知平台不支持更换要求，那么可对 <var>old</var> 运行<a>关闭步骤</a>，
  而后对 <var>new</var> 运行 <a>展示步骤</a>。

  <p class="note">强烈建议通知平台支持原生更换，它要好得多。
</ol>


<h2 id=api>API</h2>

<pre class=idl>
[Constructor(DOMString title, optional NotificationOptions options),
 Exposed=(Window,Worker)]
interface Notification : EventTarget {
  static readonly attribute NotificationPermission permission;
  [Exposed=Window] static void requestPermission(optional NotificationPermissionCallback callback);

  attribute EventHandler onclick;
  attribute EventHandler onerror;

  readonly attribute DOMString title;
  readonly attribute NotificationDirection dir;
  readonly attribute DOMString lang;
  readonly attribute DOMString body;
  readonly attribute DOMString tag;
  readonly attribute USVString icon;
  readonly attribute USVString sound;
  // 目前还没有暴露振动属性；见 bug 23682
  readonly attribute boolean renotify;
  readonly attribute boolean silent;
  readonly attribute boolean noscreen;
  readonly attribute boolean sticky;
  [SameObject] readonly attribute any data;

  void close();
};

dictionary NotificationOptions {
  NotificationDirection dir = "auto";
  DOMString lang = "";
  DOMString body = "";
  DOMString tag = "";
  USVString icon;
  USVString sound;
  VibratePattern vibrate;
  boolean renotify = false;
  boolean silent = false;
  boolean noscreen = false;
  boolean sticky = false;
  any data = null;
};

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

callback NotificationPermissionCallback = void (NotificationPermission permission);

enum NotificationDirection {
  "auto",
  "ltr",
  "rtl"
};
</pre>

<p>一个<a>非持久通知</a>由一个 {{Notification}} 对象来表示，并且可以通过
{{Notification}} 的<a href="#dom-notification-notification">构造函数</a>来创建。

<p>一个<a>持久通知</a>由零或多个 {{Notification}} 对象来表示，并且可以通过
{{ServiceWorkerRegistration/showNotification()}} 方法来创建。

<h3 id=garbage-collection>垃圾回收</h3>

<p>当 {{Notification}} 对象相对应的<a lt="concept notification">通知</a>在
<a>通知列表</a>时，该对象有一个<b>类型</b>为 <code>click</code> 或者 <code>error</code>
的<a lt="concept event listener">事件监听器</a>，那么该 {{Notification}} 对象
一定不能被垃圾回收。
 

<h3 id=constructors>构造函数</h3>

<p>当调用 <dfn constructor dfn-for=Notification><code>Notification(title, options)
</code></dfn> 购置函数时，必须（除非另有说明）执行这些步骤： 

<ol>
  <li><p>如果 <var>options</var> 存在 <code>sticky</code>，<a>抛出</a>
  <code>TypeError</code> 异常。

  <li><p>如果<a>入口设置对象</a>的<a>全局对象</a>是一 {{ServiceWorkerGlobalScope}}
  对象，<a>抛出</a> <code>TypeError</code> 异常。

  <li><p>设 <var>notification</var> 是给定 <var>title</var> 和 <var>options</var>
  所<a lt="create a notification">创建的通知</a>。重新抛出任何异常。

  <li><p>设 <var>n</var> 是与 <var>notification</var> 相关联的新 {{Notification}}
  对象。

  <li><a>并行</a>执行这些子步骤：

  <ol>
    <li><p>如果对 <var>notification</var> 的<a lt="concept origin">起源</a>
    的<a>许可</a>不是 "<code>granted</code>"，在 <var>n</var> 上<a>排队一个任务</a>
    来<a lt="concept event fire">触发事件</a> <code>error</code>，并终止浙西子步骤。

    <li><p>对 <var>notification</var> 执行<a>获取步骤</a>。

    <li><p>对 <var>notification</var> 执行<a>显示步骤</a>。
  </ol>

  <li><p>返回 <var>n</var>。
</ol>


<h3 id=static-members>静态成员</h3>

<p>获取静态属性 <dfn attribute dfn-for=Notification><code>permission</code></dfn>
的值必须返回对<a>入口设置对象</a><a>起源</a>的<a>许可</a>。

<p>当调用静态方法 <dfn method dfn-for=Notification><code>requestPermission(callback)
</code></dfn> 时，必须执行这些步骤：

<ol>
  <li><p>返回，但依然<a>并行</a>执行这些子步骤：

  <li><p>设 <var>permission</var> 是对<a>入口设置对象</a><a>起源</a>的<a>许可</a>。

  <li><p>如果 <var>permission</var> 是 "<code>default</code>"，询问用户对
  <a>入口设置对象</a><a>起源</a>进行显示通知是否可接受。如果可接受，设置许可为
  "<code>granted</code>"，否则设置许可为 "<code>denied</code>"。

  <li><p><a>排队一个任务</a>来设置 <var>permission</var> 为<a>入口设置对象</a>
  <a>起源</a>的<a>许可</a>，并且当存在 <var>callback</var> 时将 <var>permission</var>
  作为参数调用该 <var>callback</var>。如果有任何异常抛出，<a>报告异常</a>。
</ol>

<p class="warning">设计时，通知平台是迄今为止询问用户许可比较有意义的实例。其他 API
的规范没有必要使用该模式，相反可使用
<a href="http://robert.ocallahan.org/2011/06/permissions-for-web-applications_30.html">
更多合适的替代品</a>之一。

<h3 id=object-members>对象成员</h3>

<p>{{Notification}} 对象必须作为属性支持下列<a>事件处理程序</a>（及其相应的
<a>事件处理事件类型</a>）。

<table>
  <thead>
    <tr>
      <th><a>事件处理程序</a>
      <th><a>事件处理事件类型</a>
 <tbody>
  <tr>
   <td><dfn attribute dfn-for=Notification><code>onclick</code></dfn>
   <td><code>click</code>
  <tr>
   <td><dfn attribute dfn-for=Notification><code>onerror</code></dfn>
   <td><code>error</code>
</table>

<p>当调用 <dfn method dfn-for=Notification><code>close()</code></dfn> 方法时，
必须对<a lt="concept notification">通知</a>执行<a>关闭步骤</a>。

<p>获取 <dfn attribute dfn-for=Notification><code>title</code></dfn> 属性值必须
返回<a lt="concept notification">通知</a>的<a lt="concept title">标题</a>。

<p>获取 <dfn attribute dfn-for=Notification><code>dir</code></dfn> 属性值必须
返回<a lt="concept notification">通知</a>的<a lt="concept direction">方向</a>。

<p>获取 <dfn attribute dfn-for=Notification><code>lang</code></dfn> 属性值必须
返回<a lt="concept notification">通知</a>的<a lt="concept language">语言</a>。

<p>获取 <dfn attribute dfn-for=Notification><code>body</code></dfn> 属性值必须
返回<a lt="concept notification">通知</a>的<a>主题</a>。

<p>获取 <dfn attribute dfn-for=Notification><code>tag</code></dfn> 属性值必须
返回<a lt="concept notification">通知</a>的<a>标签</a>。

<p>获取 <dfn attribute dfn-for=Notification><code>icon</code></dfn> 属性值必须
返回<a lt="concept notification">通知</a>的<a lt="url serializer">序列化</a>的
<a>图标 URL</a>，或者当<a lt="concept notification">通知</a>没有<a>图标 URL</a>
时返回空字符串。

<p>获取 <dfn attribute dfn-for=Notification><code>sound</code></dfn> 属性值必须
返回<a lt="concept notification">通知</a>的<a lt="url serializer">序列化</a>的
<a>声音 URL</a>，或者当<a lt="concept notification">通知</a>的<a>声音 URL</a>时
返回空字符串。

<p>获取 <dfn attribute dfn-for=Notification><code>renotify</code></dfn>属性值必须
返回<a lt="concept notification">通知</a>的<a>重通知偏好标志</a>。

<p>获取 <dfn attribute dfn-for=Notification><code>silent</code></dfn> 属性值必须
返回<a lt="concept notification">通知</a>的<a>静音偏好标志</a>。

<p>获取 <dfn attribute dfn-for=Notification><code>noscreen</code></dfn>属性值必须
返回<a lt="concept notification">通知</a>的<a>屏幕关闭偏好标志</a>。

<p>获取 <dfn attribute dfn-for=Notification><code>sticky</code></dfn> 属性值必须
返回<a lt="concept notification">通知</a>的<a>粘性偏好设置</a>。

<p>获取 <dfn attribute dfn-for=Notification><code>data</code></dfn> 属性值必须
返回<a lt="concept notification">通知</a>的<a>数据</a>的<a>结构化克隆</a>。


<h3 id=examples>示例</h3>

<h4 id=using-events>使用事件</h4>

<p>开发者可以使用 {{Notification}} 对象在其生命周期内发出的事件来产生所需要的行为。

<p>当用户激活一个通知时会触发 <code>click</code> 事件。

<pre class=example>
var not = new Notification("Gebrünn Gebrünn by Paul Kalkbrenner", { icon: "newsong.svg", tag: "song" })
notification.onclick = function() { displaySong(this) }</pre>


<h4 id=tags-example>多实例使用 <code>tag</code> 成员</h4>

<p>Web 应用程序常常在多实例中进行并发操作，比如用户在多个浏览器标签中打开一个邮件
应用程序。由于桌面是一种共享资源，通知 API 通过 <code>tag</code> 成员提供一种很
容易协调的方式进行通知。

<p>表示相同概念的事件可以使用相同的标记，当两个通知同时显示时，用户只会收到一个通知。

<pre class=example>
实例 1                                       | 实例 2
                                             |
// 有个新邮件的通知实例                      |
new Notification("New mail from John Doe",   |
                 { tag: 'message1' });       |
                                             |
                                             |  // 稍后该实例通知有个新邮件
                                             |  new Notification("New mail from John Doe",
                                             |                   { tag: 'message1' });</pre>

<p>如果用户代理遵循这里的算法，这种情况的结果就是，用户收到
<strong>单一的</strong>通知 "New mail from John Doe"。


<h4 id=using-the-tag-member-for-a-single-instance>单实例使用 <code>tag</code> 成员</h4>

<p>单实例应用程序也可以使用 <code>tag</code> 成员来尽可能保持其通知的最新状态变化。

<p>例如，Alice 和 Bob 正在使用一个聊天应用程序，当 Alice 空闲时 Bob 发送了多条信息，
应用程序可能更倾向于 Alice 没有看到每个消息的通知界面。

<pre class=example>
// Bob 说 "Hi"
new Notification("Bob: Hi", { tag: 'chat_Bob' });

// Bob 说 "Are you free this afternoon?"
new Notification("Bob: Hi / Are you free this afternoon?", { tag: 'chat_Bob' });</pre>

<p>这种情况的结果就是<i>单一的</i>通知；第二条消息会替换第一条消息，因为它们具有
相同的标签。在该队列通知（先进先出）平台，使用标签允许通知保持其在队列中的位置。
在总是最先显示最新通知的平台里，也可以使用 {{close()}} 方法实现类似的结果。


<h2 id=service-worker-api>服务线程 API</h2>

<pre class=idl>
dictionary GetNotificationOptions {
  DOMString tag = "";
};

partial interface ServiceWorkerRegistration {
  Promise&lt;void> showNotification(DOMString title, optional NotificationOptions options);
  Promise&lt;sequence&lt;Notification>> getNotifications(optional GetNotificationOptions filter);
};

[Constructor(DOMString type, optional NotificationEventInit eventInitDict),
 Exposed=ServiceWorker]
interface NotificationEvent : ExtendableEvent {
  readonly attribute Notification notification;
};

dictionary NotificationEventInit : ExtendableEventInit {
  required Notification notification;
};

partial interface ServiceWorkerGlobalScope {
  attribute EventHandler onnotificationclick;
};
</pre>

<p>当调用 <dfn method dfn-for=ServiceWorkerRegistration><code>
showNotification(title, options)</code></dfn> 方法时，必须执行这些步骤：

<ol>
  <li><p>设 <var>promise</var> 是一新的先知。

  <li><p>设 <var>notification</var> 是给定 <var>title</var> 和 <var>options</var>
  所<a lt="create a notification">创建的通知</a>。重新抛出任何异常。

  <li><p>如果<a>上下文对象</a>的<a lt="dfn active worker">活跃线程</a>是 null，
  拒绝 <var>promise</var> 并抛出 <code>TypeError</code> 异常。

  <li><p>设置 <var>notification</var> 的<a>服务线程注册</a>为该<a>上下文对象</a>。

  <li><p><a>并行</a>执行这些子步骤：

  <ol>
    <li><p>如果对 <var>notification</var> 的<a lt="concept origin">起源</a>的
    <a>许可</a>不是 "<code>granted</code>"，拒绝 <var>promise</var> 并抛出
    <code>TypeError</code> 异常，而后终止这些子步骤。

    <li><p>否则，用 undefined 处理 <var>promise</var>。

    <li><p>对 <var>notification</var> 执行 <a>获取步骤</a>。

    <li><p>对 <var>notification</var> 执行 <a>显示步骤</a>。
  </ol>

  <li><p>返回 <var>promise</var>。
</ol>

<p>当调用 <dfn method dfn-for=ServiceWorkerRegistration><code>
getNotifications(filter)</code></dfn> 方法时，必须执行这些步骤：

<ol>
  <li><p>设 <var>promise</var> 是一新的先知。

  <li><p><a>并行</a>执行这些子步骤：

  <ol>
    <li><p>设 <var>tag</var> 是 <var>filter</var> 的 <code>tag</code>。

    <li><p>设 <var>notifications</var> 是所有那些在<a>通知列表</a>中，
    其<a lt="concept origin">起源</a>是<a>入口设置对象</a>的<a>起源</a>，
    其<a>服务线程注册</a>是<a>上下文对象</a>，并且如果 <var>tag</var> 非空字符串
    的话，其<a>标签</a>是 <var>tag</var>的<a lt="concept notification">通知</a>
    所组成的一个列表。

    <li><p>设 <var>objects</var> 是一空的 JavaScript 数组。

    <li><p>对 <var>notifications</var> 中每一个<a lt="concept notification">通知</a>，
    按照其创建的顺序，来创建 {{Notification}} 对象表示<a lt="concept notification">
    通知</a>并且将该对象压入 <var>objects</var>。

    <li><p>用 <var>objects</var> 处理 <var>promise</var>。
  </ol>

  <li><p>返回 <var>promise</var>。
</ol>

<p class=note>该方法返回零或多个新的 {{Notification}} 对象可能表示已然存在的相同
底层 {{Notification}} 对象的<a lt="concept notification">通知</a>。

<hr>

<p>为给定 <var>notification</var> <dfn>触发一个名为 <var>e</var> 的服务线程通知
事件</dfn>，使用 {{NotificationEvent/notification}} 属性初始化为新的 {{Notification}}
对象表示 <var>notification</var> 的 {{NotificationEvent}} 接口来
<a lt="concept event fire">触发一个名为 <var>e</var> 的服务线程通知
事件</a>。

<p>获取 {{NotificationEvent/notification}} 属性值必须返回其所初始化的值。

<p>{{ServiceWorkerGlobalScope}} 对象必须作为属性支持下列<a>事件处理程序</a>
（及其相应的<a>事件处理事件类型</a>）。

<table>
  <thead>
    <tr>
      <th><a>事件处理程序</a>
      <th><a>事件处理事件类型</a>
  <tbody>
    <tr>
      <td><dfn attribute dfn-for=ServiceWorkerGlobalScope><code>
      onnotificationclick</code></dfn>
      <td><code>notificationclick</code>
</table>


<h2 id=acknowledgments class=no-num>致谢</h2>

<p>感谢牛人：
Aharon (Vladimir) Lanin、
Alex Russell、
Arkadiusz Michalski、
Boris Zbarsky、
David Håsäther、
Doug Turner、
Drew Wilson、
Edward O'Connor、
Frederick Hirsch、
Ian Hickson、
Jake Archibald、
James Graham、
John Mellor、
Jon Lee、
Jonas Sicking、
Michael Cooper、
Michael Henretty、
Olli Pettay、
Peter Beverloo、
Reuben Morais、
Simon Pieters。

<p>本标准由
<a lang=nl href=//annevankesteren.nl/>Anne van Kesteren</a>
(<a href=//www.mozilla.org/>Mozilla</a>,
<a href=mailto:annevk@annevk.nl>annevk@annevk.nl</a>) 编写。
前几版由
John Gregg (<a href=//www.google.com/>Google</a>,
<a href=mailto:johnnyg@google.com>johnnyg@google.com</a>) 编写。

<p>根据 <a rel="license" href="//creativecommons.org/publicdomain/zero/1.0/">CC0</a>，
在法律允许的范围内，编辑们放弃所有版权及与之相关或邻接的权利。

<script>
document.addEventListener("DOMContentLoaded", function(event) {
  // 索引列表没有后向参考
  document.querySelector('.indexlist').classList.add('no-backref');

  // 文档载入后引入 dfn.js
  var script = document.createElement('script');
  script.setAttribute('id', 'head');
  script.setAttribute('src', 'https://resources.whatwg.org/dfn.js');
  document.body.appendChild(script);
});
</script>

<pre class="anchors">
urlPrefix: http://heycam.github.io/webidl/#dfn-; type: dfn
  text: throw
urlPrefix: https://html.spec.whatwg.org/multipage/
  urlPrefix: browsers.html; type: dfn
    text: browsing context
    text: origin
    text: same origin
  urlPrefix: browsers.html; type: interface
    text: Window
  urlPrefix: infrastructure.html; type: dfn
    text: in parallel
  urlPrefix: interaction.html; type: dfn
    text: dom window focus
    text: structured clone
  urlPrefix: webappapis.html; type: dfn
    text: entry settings object
    text: event handler event types
    text: event handlers
    text: global object
    text: queue a task
    text: report the exception
  urlPrefix: webappapis.html; type: interface
    text: EventHandler
urlPrefix: https://url.spec.whatwg.org/#concept-; type: dfn
  text: url parser
  text: url serializer
urlPrefix: https://fetch.spec.whatwg.org/#concept-; type: dfn
  text: fetch
  text: internal response
  text: response
  text: response type
urlPrefix: https://slightlyoff.github.io/ServiceWorker/spec/service_worker/; type: dfn
  text: handle functional event
  text: dfn active worker
urlPrefix: https://slightlyoff.github.io/ServiceWorker/spec/service_worker/; type: interface
  text: ExtendableEvent
  text: ExtendableEventInit
  text: ServiceWorker
  text: ServiceWorkerGlobalScope
  text: ServiceWorkerRegistration
urlPrefix: https://dom.spec.whatwg.org/; type: dfn
  text: canceled flag
  text: concept event
  text: concept event fire
  text: concept event listener
  text: context object
  text: dom event cancelable
urlPrefix: https://dom.spec.whatwg.org/; type: interface
  text: EventTarget
urlPrefix: http://www.w3.org/TR/vibration/
  urlPrefix: #dfn-; type: dfn
    text: perform vibration
    text: validate and normalize
  urlPrefix: #idl-def-; type: interface
    text: VibratePattern
</pre>

<pre class="biblio">
{
    "DOM": {
        "authors": [
            "Anne van Kesteren",
            "Aryeh Gregor",
            "Ms2ger"
        ],
        "href": "https://dom.spec.whatwg.org/",
        "title": "DOM",
        "publisher": "WHATWG"
    },
    "WEBIDL": {
        "authors": [
            "Cameron McCormack",
            "Jonas Sicking"
        ],
        "href": "http://heycam.github.io/webidl/",
        "title": "Web IDL",
        "publisher": "W3C"
    },
    "URL": {
        "authors": [
            "Anne van Kesteren",
            "Sam Ruby"
        ],
        "href": "https://url.spec.whatwg.org/",
        "title": "URL",
        "publisher": "WHATWG"
    },
    "LANG": {
        "authors": [
            "Addison Phillips",
            "Mark Davis"
        ],
        "href": "http://tools.ietf.org/html/bcp47",
        "title": "Tags for Identifying Languages; Matching of Language Tags",
        "publisher": "IETF"
    }
}
</pre>