path: root/files/zh-tw/web/api/notification/index.html

---
title: Notification
slug: Web/API/notification
tags:
  - 待翻譯
translation_of: Web/API/Notification
---
<p>{{APIRef("Web Notifications")}}</p>

<p><a href="/zh-TW/docs/Web/API/Notifications_API">Notifications API</a> 的 <code>Notification</code> interface 是用來設置及顯示「桌面通知」給使用。</p>

<p>{{AvailableInWorkers}}</p>

<h2 id="Constructor">Constructor</h2>

<dl>
 <dt>{{domxref("Notification.Notification", "Notification()")}}</dt>
 <dd>建立一個新的 {{domxref('Notification')}} 實例。</dd>
</dl>

<h2 id="Properties">Properties</h2>

<h3 id="靜態屬性">靜態屬性</h3>

<p>以下的屬性僅適用於 <code>Notification</code> 實例。</p>

<dl>
 <dt>{{domxref("Notification.permission")}} {{readonlyinline}}</dt>
 <dd>一個表示允許通知顯示與否的權限的 string。可能的值有：「denied」(使用者不允許顯示 Notification )、「granted」(使用者允許顯示 Notification )，或者是「default」(還不知道使用者允許與否，預設行為與 denied 一致)。</dd>
</dl>

<h3 id="實例屬性">實例屬性</h3>

<p>以下屬應僅適用於 <code>Notification</code> 實例。</p>

<dl>
 <dt>{{domxref("Notification.title")}} {{readonlyinline}}</dt>
 <dd>在建構子的 options 參數中指定的 Notification 的標題。</dd>
 <dt>{{domxref("Notification.dir")}} {{readonlyinline}}</dt>
 <dd>在建構子的 options 參數中指定的 Notification 的文字顯示方向。</dd>
 <dt>{{domxref("Notification.lang")}} {{readonlyinline}}</dt>
 <dd>在建構子的 options 參數中指定的 Notification 的語言代號。</dd>
 <dt>{{domxref("Notification.body")}} {{readonlyinline}}</dt>
 <dd>在建構子的 options 參數中指定的 Notification 的內容。</dd>
 <dt>{{domxref("Notification.tag")}} {{readonlyinline}}</dt>
 <dd>The ID of the notification (if any) as specified in the options parameter of the constructor.</dd>
 <dt>{{domxref("Notification.icon")}} {{readonlyinline}}</dt>
 <dd>在建構子的 options 參數中指定的 Notification 的 icon 的網址。</dd>
 <dt>{{domxref("Notification.data")}} {{readonlyinline}}</dt>
 <dd>回傳結構化的 Notification 的資料。</dd>
 <dt>{{domxref("Notification.requireInteraction")}} {{readonlyinline}}</dt>
 <dd>一個 {{jsxref("Boolean")}} 指示在有充足大小的螢幕上的時候，Notfication 實例是否會持續顯示直到使用者點擊它或者 dismisses it。</dd>
 <dt>{{domxref("Notification.silent")}} {{readonlyinline}}</dt>
 <dd>表示 Notfication 是否設定要以較低調的方式呈現(比如不撥放通知音效、不震動)。這個設定與裝置本身的設定無關。</dd>
</dl>

<dl>
 <dt>{{domxref("Notification.timestamp")}} {{readonlyinline}}</dt>
 <dd>表示 Notification 的建立時間、或者可啟動的時間 (可能是過去、現在或未來)。</dd>
</dl>

<dl>
 <dt>{{domxref("Notification.vibrate")}} {{readonlyinline}}</dt>
 <dd>表示在可震動的裝置上的震動模式。</dd>
</dl>

<h4 id="尚未支援的屬性">尚未支援的屬性</h4>

<p>The following properties are listed in the most up-to-date spec, but are not supported in any browsers yet. It is advisable to keep checking back regularly to see if the status of these has updated, and let us know if you find any out of date information.</p>

<dl>
 <dt>{{domxref("Notification.noscreen")}} {{readonlyinline}}</dt>
 <dd>表示 Notification 顯示時是否要打開裝置的螢幕。</dd>
 <dt>{{domxref("Notification.renotify")}} {{readonlyinline}}</dt>
 <dd>表示使用者是否會在舊的 Notification 被新的 Notification 替換掉時通知。</dd>
 <dt>{{domxref("Notification.sound")}} {{readonlyinline}}</dt>
 <dd>表示當 Notification 顯示時要用來代替系統預設音效撥放的音訊資源。</dd>
 <dt>{{domxref("Notification.sticky")}} {{readonlyinline}}</dt>
 <dd>表示 Notification 是否「sticky」(比如使用者不太容易清除它)。</dd>
</dl>

<h4 id="事件處理器">事件處理器</h4>

<dl>
 <dt>{{domxref("Notification.onclick")}}</dt>
 <dd>一個 {{event("click")}} 事件的 handler。每次使用者點擊 Notification 都會被觸發。</dd>
 <dt>{{domxref("Notification.onerror")}}</dt>
 <dd>一個 {{event("error")}} 事件的 handler. 每次 Notification 發生 Error 都會被觸發。</dd>
</dl>

<h4 id="停止支援的事件處理器">停止支援的事件處理器</h4>

<p>底下這些列在 {{anch("browser compatibility")}} 中的 event handlers 雖然還有支援，但已經從近期的 spec 中移除了。因為瀏覽器會在未來的版本逐漸停止支援，最好還是不要使用它們。</p>

<dl>
 <dt>{{domxref("Notification.onclose")}}</dt>
 <dd>A handler for the {{event("close")}} event. It is triggered when the user closes the notification.</dd>
 <dt>{{domxref("Notification.onshow")}}</dt>
 <dd>A handler for the {{event("show")}} event. It is triggered when the notification is displayed.</dd>
</dl>

<h2 id="方法">方法</h2>

<h3 id="靜態方法">靜態方法</h3>

<p>這些方法只能在<code> Notification 實例上使用。</code></p>

<dl>
 <dt>{{domxref("Notification.requestPermission()")}}</dt>
 <dd>向使用者詢問是否開放顯示 Notification 的權限。</dd>
</dl>

<h3 id="實例方法">實例方法</h3>

<p>These properties are available only on an instance of the <code>Notification</code> object or through its <a href="/en-US/docs/Web/JavaScript/Guide/Inheritance_and_the_prototype_chain"><code>prototype</code></a>. The <code>Notification</code> object also inherits from the {{domxref("EventTarget")}} interface.</p>

<dl>
 <dt>{{domxref("Notification.close()")}}</dt>
 <dd>透過這個方法關閉 Notification 。</dd>
</dl>

<h2 id="範例">範例</h2>

<p>先看這段基本的 HTML：</p>

<pre class="brush: html">&lt;button onclick="notifyMe()"&gt;Notify me!&lt;/button&gt;</pre>

<p>用下面的程式碼我們可以送出通知： 底下的程式碼雖然略嫌冗長，但完整的示範了如何在送出通知之前，事先檢查了瀏覽器是否支援 Notification、使用者是否授權這個網域的網頁送出通知，以及在需要的時候向使用者詢問是否開放權限。</p>

<pre class="brush: js">function notifyMe() {
  // 首先讓我們確定瀏覽器支援 Notification
  if (!("Notification" in window)) {
    alert("這個瀏覽器不支援 Notification");
  }

  // 再檢查使用者是否已經授權執行 Notification
  else if (Notification.permission === "granted") {
    // 如果已經授權就可以直接新增 Notification 了!
    var notification = new Notification("安安你好!");
  }

  // 否則，我們會需要詢問使用者是否開放權限
  else if (Notification.permission !== 'denied') {
    Notification.requestPermission(function (permission) {
      // 如果使用者同意了就來新增一個 Notification 打聲招呼吧
      if (permission === "granted") {
        var notification = new Notification("安安~");
      }
    });
  }

  // 如果使用者還是不同意授權執行 Notification
  // 最好還是進行適當的處理以避免繼續打擾使用者
}</pre>

<p>{{EmbedLiveSample('範例', '100%', 30)}}</p>

<p>在很多時候，你應該不會想要這麼冗長的程式碼。 比如說，在我們的 <a href="http://mdn.github.io/emogotchi/">Emogotchi demo</a> (<a href="https://github.com/mdn/emogotchi">see source code</a>)  之中，我們只寫了 {{domxref("Notification.requestPermission")}} 而不用進一步檢查是否已經獲得了權限：</p>

<pre class="brush: js">Notification.requestPermission();</pre>

<p>然後我們只需要在要新增 Notfication 時執行這個 <code>spawnNotification()</code>  — 透過傳入指定的 body、icon、title，然後它就會產生我們所需的 options 參數並透過 {{domxref("Notification.Notification","Notification()")}} 建構子發送 Notification.</p>

<pre class="brush: js">function spawnNotification(theBody,theIcon,theTitle) {
  var options = {
      body: theBody,
      icon: theIcon
  }
  var n = new Notification(theTitle,options);
}</pre>

<h2 id="規格">規格</h2>

<table class="standard-table">
 <tbody>
  <tr>
   <th scope="col">Specification</th>
   <th scope="col">Status</th>
   <th scope="col">Comment</th>
  </tr>
  <tr>
   <td>{{SpecName('Web Notifications')}}</td>
   <td>{{Spec2('Web Notifications')}}</td>
   <td>Living standard</td>
  </tr>
 </tbody>
</table>

<h2 id="瀏覽器支援度">瀏覽器支援度</h2>

<p>{{CompatibilityTable}}</p>

<div id="compat-desktop">
<table class="compat-table">
 <tbody>
  <tr>
   <th>Feature</th>
   <th>Chrome</th>
   <th>Firefox (Gecko)</th>
   <th>Internet Explorer</th>
   <th>Opera</th>
   <th>Safari</th>
  </tr>
  <tr>
   <td>Basic support</td>
   <td>5{{property_prefix("webkit")}}<sup>[1]</sup><br>
    22</td>
   <td>4.0 {{property_prefix("moz")}}<sup>[2]</sup><br>
    22</td>
   <td>{{CompatNo}}</td>
   <td>25</td>
   <td>6<sup>[3]</sup></td>
  </tr>
  <tr>
   <td><code>icon</code></td>
   <td>5{{property_prefix("webkit")}}<sup>[1]</sup><br>
    22</td>
   <td>4.0 {{property_prefix("moz")}}<sup>[2]</sup><br>
    22</td>
   <td>{{CompatNo}}</td>
   <td>25</td>
   <td>{{CompatNo}}</td>
  </tr>
  <tr>
   <td>Available in workers</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatGeckoDesktop("41.0")}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
  </tr>
  <tr>
   <td><code>silent</code></td>
   <td>{{CompatChrome(43.0)}}</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatNo}}</td>
  </tr>
  <tr>
   <td><code>noscreen</code>, <code>renotify</code>, <code>sound</code>, <code>sticky</code></td>
   <td>{{CompatNo}}</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatNo}}</td>
  </tr>
 </tbody>
</table>
</div>

<div id="compat-mobile">
<table class="compat-table">
 <tbody>
  <tr>
   <th>Feature</th>
   <th>Android</th>
   <th>Android Webview</th>
   <th>Firefox Mobile (Gecko)</th>
   <th>Firefox OS</th>
   <th>IE Mobile</th>
   <th>Opera Mobile</th>
   <th>Safari Mobile</th>
   <th>Chrome for Android</th>
  </tr>
  <tr>
   <td>Basic support</td>
   <td>{{CompatUnknown}}</td>
   <td>
    <p>{{CompatVersionUnknown}}</p>
   </td>
   <td>4.0{{property_prefix("moz")}}<sup>[2]</sup><br>
    22</td>
   <td>1.0.1{{property_prefix("moz")}}<sup>[2]</sup><br>
    1.2</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatNo}}</td>
   <td>
    <p>{{CompatVersionUnknown}}</p>
   </td>
  </tr>
  <tr>
   <td><code>icon</code></td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatVersionUnknown}}</td>
   <td>4.0{{property_prefix("moz")}}<sup>[2]</sup><br>
    22</td>
   <td>1.0.1{{property_prefix("moz")}}<sup>[2]</sup><br>
    1.2</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatVersionUnknown}}</td>
  </tr>
  <tr>
   <td>Available in workers</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatGeckoMobile("41.0")}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
  </tr>
  <tr>
   <td><code>silent</code></td>
   <td>{{CompatNo}}</td>
   <td>{{CompatChrome(43.0)}}</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatChrome(43.0)}}</td>
  </tr>
  <tr>
   <td><code>noscreen</code>, <code>renotify</code>, <code>sound</code>, <code>sticky</code></td>
   <td>{{CompatNo}}</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatNo}}</td>
  </tr>
 </tbody>
</table>
</div>

<p>[1] Before Chrome 22, the support for notification followed an <a href="http://www.chromium.org/developers/design-documents/desktop-notifications/api-specification">old prefixed version of the specification</a> and used the {{domxref("window.navigator.webkitNotifications","navigator.webkitNotifications")}} object to instantiate a new notification.</p>

<p>Before Chrome 32, {{domxref("Notification.permission")}} was not supported.</p>

<p>Before Chrome 42, service worker additions were not supported.</p>

<p>[2] Prior to Firefox 22 (Firefox OS &lt;1.2), the instantiation of a new notification must be done with the {{domxref("window.navigator.mozNotification", "navigator.mozNotification")}} object through its <code>createNotification</code> method.</p>

<p>Prior to Firefox 22 (Firefox OS &lt;1.2), the Notification was displayed when calling the <code>show</code> method and supported only the <code>click</code> and <code>close</code> events.</p>

<p>Nick Desaulniers wrote a <a href="https://github.com/nickdesaulniers/fxos-irc/blob/master/js/notification.js">Notification shim</a> to cover both newer and older implementations.</p>

<p>One particular Firefox OS issue is that you can <a href="https://github.com/nickdesaulniers/fxos-irc/blob/0160cf6c3a2b5c9fe33822aaf6bcba3b7e846da9/my.js#L171">pass a path to an icon</a> to use in the notification, but if the app is packaged you cannot use a relative path like <code>/my_icon.png</code>. You also can't use <code>window.location.origin + "/my_icon.png"</code> because <code>window.location.origin</code> is null in packaged apps. The <a href="https://developer.mozilla.org/en-US/Apps/Developing/Manifest#origin">manifest origin field</a> fixes this, but it is only available in Firefox OS 1.1+. A potential solution for supporting Firefox OS &lt;1.1 is to <a href="https://github.com/nickdesaulniers/fxos-irc/blob/0160cf6c3a2b5c9fe33822aaf6bcba3b7e846da9/my.js#L168">pass an absolute URL to an externally hosted version of the icon</a>. This is less than ideal as the notification is displayed immediately without the icon, then the icon is fetched, but it works on all versions of Firefox OS.</p>

<p>When using notifications  in a Firefox OS app, be sure to add the <code>desktop-notification</code> permission in your manifest file. Notifications can be used at any permission level, hosted or above: <code>"permissions": { "desktop-notification": {} }</code></p>

<p>[3] Safari started to support notification with Safari 6, but only on Mac OSX 10.8+ (Mountain Lion).</p>

<h2 id="延伸閱讀">延伸閱讀</h2>

<ul>
 <li><a href="/en-US/docs/Web/API/Notifications_API/Using_the_Notifications_API">Using the Notifications API</a></li>
</ul>