MDN wants to talk to developers like you: https://qsurvey.mozilla.com/s3/a3e7b5301fea

翻譯不完整。請協助 翻譯此英文文件

Notifications API 的 Notification interface 是用來設置及顯示「桌面通知」給使用。

註: This feature is available in Web Workers.

Constructor

Notification()
建立一個新的 Notification 實例。

Properties

靜態屬性

以下的屬性僅適用於 Notification 實例。

Notification.permission Read only
一個表示允許通知顯示與否的權限的 string。可能的值有:「denied」(使用者不允許顯示 Notification )、「granted」(使用者允許顯示 Notification ),或者是「default」(還不知道使用者允許與否,預設行為與 denied 一致)。

實例屬性

以下屬應僅適用於 Notification 實例。

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

尚未支援的屬性

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.

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

事件處理器

Notification.onclick
一個 click 事件的 handler。每次使用者點擊 Notification 都會被觸發。
Notification.onerror
一個 error 事件的 handler. 每次 Notification 發生 Error 都會被觸發。

停止支援的事件處理器

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

Notification.onclose
A handler for the close event. It is triggered when the user closes the notification.
Notification.onshow
A handler for the show event. It is triggered when the notification is displayed.

方法

靜態方法

這些方法只能在 Notification 實例上使用。

Notification.requestPermission()
向使用者詢問是否開放顯示 Notification 的權限。

實例方法

These properties are available only on an instance of the Notification object or through its prototype. The Notification object also inherits from the EventTarget interface.

Notification.close()
透過這個方法關閉 Notification 。

範例

先看這段基本的 HTML:

<button onclick="notifyMe()">Notify me!</button>

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

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
  // 最好還是進行適當的處理以避免繼續打擾使用者
}

在很多時候,你應該不會想要這麼冗長的程式碼。 比如說,在我們的 Emogotchi demo (see source code)  之中,我們只寫了 Notification.requestPermission 而不用進一步檢查是否已經獲得了權限:

Notification.requestPermission();

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

function spawnNotification(theBody,theIcon,theTitle) {
  var options = {
      body: theBody,
      icon: theIcon
  }
  var n = new Notification(theTitle,options);
}

規格

Specification Status Comment
Notifications API Living Standard Living standard

瀏覽器支援度

Feature Chrome Firefox (Gecko) Internet Explorer Opera Safari
Basic support 5webkit[1]
22
4.0 moz[2]
22
No support 25 6[3]
icon 5webkit[1]
22
4.0 moz[2]
22
No support 25 No support
Available in workers ? 41.0 (41.0) ? ? ?
silent 43.0 No support No support No support No support
noscreen, renotify, sound, sticky No support No support No support No support No support
Feature Android Android Webview Firefox Mobile (Gecko) Firefox OS IE Mobile Opera Mobile Safari Mobile Chrome for Android
Basic support ?

(Yes)

4.0moz[2]
22
1.0.1moz[2]
1.2
No support ? No support

(Yes)

icon ? (Yes) 4.0moz[2]
22
1.0.1moz[2]
1.2
No support ? No support (Yes)
Available in workers ? ? 41.0 (41.0) ? ? ? ? ?
silent No support 43.0 No support No support No support No support No support 43.0
noscreen, renotify, sound, sticky No support No support No support No support No support No support No support No support

[1] Before Chrome 22, the support for notification followed an old prefixed version of the specification and used the navigator.webkitNotifications object to instantiate a new notification.

Before Chrome 32, Notification.permission was not supported.

Before Chrome 42, service worker additions were not supported.

[2] Prior to Firefox 22 (Firefox OS <1.2), the instantiation of a new notification must be done with the navigator.mozNotification object through its createNotification method.

Prior to Firefox 22 (Firefox OS <1.2), the Notification was displayed when calling the show method and supported only the click and close events.

Nick Desaulniers wrote a Notification shim to cover both newer and older implementations.

One particular Firefox OS issue is that you can pass a path to an icon to use in the notification, but if the app is packaged you cannot use a relative path like /my_icon.png. You also can't use window.location.origin + "/my_icon.png" because window.location.origin is null in packaged apps. The manifest origin field fixes this, but it is only available in Firefox OS 1.1+. A potential solution for supporting Firefox OS <1.1 is to pass an absolute URL to an externally hosted version of the icon. 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.

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

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

延伸閱讀

文件標籤與貢獻者

標籤: 
 此頁面的貢獻者: bros0215, SphinxKnight, Shiyou
 最近更新: bros0215,