diff options
| author | Peter Bengtsson <mail@peterbe.com> | 2020-12-08 14:43:23 -0500 |
|---|---|---|
| committer | Peter Bengtsson <mail@peterbe.com> | 2020-12-08 14:43:23 -0500 |
| commit | 218934fa2ed1c702a6d3923d2aa2cc6b43c48684 (patch) | |
| tree | a9ef8ac1e1b8fe4207b6d64d3841bfb8990b6fd0 /files/zh-tw/web/api/notifications_api | |
| parent | 074785cea106179cb3305637055ab0a009ca74f2 (diff) | |
| download | translated-content-218934fa2ed1c702a6d3923d2aa2cc6b43c48684.tar.gz translated-content-218934fa2ed1c702a6d3923d2aa2cc6b43c48684.tar.bz2 translated-content-218934fa2ed1c702a6d3923d2aa2cc6b43c48684.zip | |
initial commit
Diffstat (limited to 'files/zh-tw/web/api/notifications_api')
| -rw-r--r-- | files/zh-tw/web/api/notifications_api/index.html | 198 | ||||
| -rw-r--r-- | files/zh-tw/web/api/notifications_api/using_the_notifications_api/index.html | 236 |
2 files changed, 434 insertions, 0 deletions
diff --git a/files/zh-tw/web/api/notifications_api/index.html b/files/zh-tw/web/api/notifications_api/index.html new file mode 100644 index 0000000000..8cf3276371 --- /dev/null +++ b/files/zh-tw/web/api/notifications_api/index.html @@ -0,0 +1,198 @@ +--- +title: Notifications API +slug: Web/API/Notifications_API +translation_of: Web/API/Notifications_API +--- +<p>{{DefaultAPISidebar("Web Notifications")}}</p> + +<p class="summary"><span class="tlid-translation translation" lang="zh-TW"><span title="">Notifications API允許網頁控制向終端用戶顯示系統通知</span></span> — 它在網頁瀏覽器的視圖之外,因此使用者切換顯示卡或移至不同的應用程式也能顯示。此 API 設計為在相容於不同平台與現有的通知系統相容。</p> + +<h2 id="概念與使用方法">概念與使用方法</h2> + +<p><span class="tlid-translation translation" lang="zh-TW"><span title="">在受到支持的平台上,顯示系統通知通常涉及兩件事。</span></span> <span class="tlid-translation translation" lang="zh-TW"><span title="">首先,用戶需要授予當前的來源權限才能顯示系統通知,</span></span><span class="tlid-translation translation" lang="zh-TW"><span title="">通常在應用程式或網站初始化完成後</span></span>使用{{domxref("Notification.requestPermission()")}} 方法。</p> + +<pre class="brush: js">btn.addEventListener('click', function() { + let promise = Notification.requestPermission(); + // wait for permission +})</pre> + +<p>這不僅是最佳實踐 — <span class="tlid-translation translation" lang="zh-TW"><span title="">您不應向用戶發送他們不同意的通知,並且在未來瀏覽器將明確禁止沒有響應用戶請求允許通知對話框的通知。Firefox 72 開始已遵循這項約定。使用此方法將產生一個請求對話框,如下所示:</span></span></p> + +<p><img alt="" src="https://mdn.mozillademos.org/files/10819/notification-bubble.png" style="display: block; height: 205px; margin: 0 auto; width: 453px;"></p> + +<p><span class="tlid-translation translation" lang="zh-TW"><span title="">用戶可以從此處選擇允許、屏蔽來自此來源的通知,也可以不做選擇。</span> <span title="">一旦選定,該設置通常將在當前會話中保持不變。</span></span></p> + +<div class="note"> +<p><strong>注意</strong>: 從 Firefox 44 開始,Notifications 和 <a href="/en-US/docs/Web/API/Push_API">Push</a> 的權限已合併。如果授予通知權限則推送也將被啟用。</p> +</div> + +<p>下一步,使用 {{domxref("Notification.Notification","Notification()")}} 構造函數創建一個新通知。 這必須要傳遞一個標題參數(title),並且可以選擇性的傳遞選擇物件指定諸如文字方向、正文、圖標、撥放通知的聲音等等。</p> + +<p>{{AvailableInWorkers}}</p> + +<p><span class="tlid-translation translation" lang="zh-TW"><span title="">另外,Notifications API規範指定了</span></span> <a href="/en-US/docs/Web/API/ServiceWorker_API">ServiceWorker API</a> <span class="tlid-translation translation" lang="zh-TW"><span title="">的許多附加功能,以允許服務人員觸發通知。</span></span></p> + +<div class="note"> +<p><strong>注意</strong>: <span class="tlid-translation translation" lang="zh-TW"><span title="">要了解有關在自己的應用程序中使用通知的更多信息,請閱讀</span></span> <a href="/en-US/docs/Web/API/Notifications_API/Using_the_Notifications_API">Using the Notifications API</a>。</p> +</div> + +<h2 id="Notifications_介面">Notifications 介面</h2> + +<dl> + <dt>{{domxref("Notification")}}</dt> + <dd>定義一個通知物件。</dd> +</dl> + +<h3 id="Service_worker_附加功能">Service worker 附加功能</h3> + +<dl> + <dt>{{domxref("ServiceWorkerRegistration")}}</dt> + <dd>包含 {{domxref("ServiceWorkerRegistration.showNotification()")}} 和 {{domxref("ServiceWorkerRegistration.getNotifications()")}} <span class="tlid-translation translation" lang="zh-TW"><span title="">用於控制通知顯示的方法。</span></span></dd> + <dt>{{domxref("ServiceWorkerGlobalScope")}}</dt> + <dd>包含 {{domxref("ServiceWorkerGlobalScope.onnotificationclick")}} <span class="tlid-translation translation" lang="zh-TW"><span title="">點擊通知時觸發自定義函數的處理程序。</span></span></dd> + <dt>{{domxref("NotificationEvent")}}</dt> + <dd>基於 {{domxref("ExtendableEvent")}} <span class="tlid-translation translation" lang="zh-TW"><span title="">的特定類型的事件對象,它表示已觸發的通知。</span></span></dd> +</dl> + +<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>{{CompatGeckoDesktop("2.0")}}{{property_prefix("moz")}}<sup>[2]</sup><br> + {{CompatGeckoDesktop("22.0")}}</td> + <td>{{CompatNo}}</td> + <td>25</td> + <td>6<sup>[3]</sup></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>Service worker additions</td> + <td> + <p>{{CompatChrome(42.0)}}</p> + </td> + <td>{{CompatGeckoDesktop("42.0")}}<sup>[4]</sup></td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</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>{{CompatGeckoMobile(2.0)}}{{property_prefix("moz")}}<sup>[2]</sup><br> + {{CompatGeckoMobile(22.0)}}</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>Available in workers</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatGeckoMobile(41.0)}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + <tr> + <td>Service worker additions</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatGeckoMobile(42.0)}}<sup>[4]</sup></td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatChrome(42.0)}}</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. Before Chrome 32, {{domxref("Notification.permission")}} was not supported.</p> + +<p>[2] Prior to Firefox 22 (Firefox OS <1.2), the instantiation of a new notification was done with the {{domxref("window.navigator.mozNotification", "navigator.mozNotification")}} object through its <code>createNotification()</code> method. In addition, the Notification was displayed when calling the <code>show()</code> method and supported only the <code>click</code> and <code>close</code> events (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>[3] Safari started to support notification with Safari 6, but only on Mac OSX 10.8+ (Mountain Lion).</p> + +<p>[4] Firefox 42 has shipped with web notifications from Service Workers disabled.</p> + +<h2 id="Firefox_OS_permissions">Firefox OS permissions</h2> + +<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:</p> + +<pre class="brush: json">"permissions": { + "desktop-notification": {} +}</pre> + +<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> diff --git a/files/zh-tw/web/api/notifications_api/using_the_notifications_api/index.html b/files/zh-tw/web/api/notifications_api/using_the_notifications_api/index.html new file mode 100644 index 0000000000..1a970509c2 --- /dev/null +++ b/files/zh-tw/web/api/notifications_api/using_the_notifications_api/index.html @@ -0,0 +1,236 @@ +--- +title: 使用 Web Notifications +slug: Web/API/Notifications_API/Using_the_Notifications_API +translation_of: Web/API/Notifications_API/Using_the_Notifications_API +--- +<p>{{SeeCompatTable}}</p> + +<h2 id="摘要">摘要</h2> + +<p>Web Notifications API 可將通知傳送至頁面以外的系統層級並顯示通知。因此即使 Web Apps 處於閒置狀態,亦可傳送資訊予使用者。絕佳範例之一,就是在使用其他 Apps 時,Web Mail App 同樣可通知使用者已接收到新郵件。</p> + +<h2 id="要求權限">要求權限</h2> + +<h3 id="網頁內容">網頁內容</h3> + +<p>在 Apps 傳送通知之前,使用者必須先許可 Apps 的動作。只要 APIs 嘗試予網頁之外的東西互動,均必須先獲得使用者的授權。如此可避免濫發通知而影響使用經驗。</p> + +<p>透過 <a href="https://developer.mozilla.org/en-US/docs/Web/API/Notification.permission" title="The permission property indicates the current permission granted by the user about web notification for the current application."><code>Notification.permission</code></a> 唯讀屬性,要傳送通知的 Apps 將檢查目前的授權狀態。此屬性共有 3 組參數:</p> + +<ul> + <li><code>default:</code>使用者尚未給予任何權限 (因此不會顯示任何通知)</li> + <li><code>granted</code>:使用者允許接收到 Apps 的通知</li> + <li><code>denied</code><code>:使用者拒絕接收 </code>Apps 的通知</li> +</ul> + +<div class="note"> +<p><strong>注意:</strong>Chrome 與 Safari 尚未建構 <code>permission</code> 屬性。</p> +</div> + +<p>若使用者尚未給予權限,則 Apps 必須透過 <a href="https://developer.mozilla.org/en-US/docs/Web/API/Notification.requestPermission" title="The requestPermission static method is used to ask the user for his permission to display a Notification to him."><code>Notification.requestPermission()</code></a> 函式讓使用者選擇,接著由此函式接收 1 組回呼 (Callback) 函式作為參數;而該回呼函式則提供使用者是否授權的資訊。</p> + +<p>以下為啟動 Apps 時要求權限的常用範例:</p> + +<pre class="brush: js">window.addEventListener('load', function () { + Notification.requestPermission(function (status) { + // This allows to use Notification.permission with Chrome/Safari + if (Notification.permission !== status) { + Notification.permission = status; + } + }); +});</pre> + +<div class="note"> +<p><strong>注意:</strong>Chrome 不允許於載入事件中呼叫 <a href="https://developer.mozilla.org/en-US/docs/Web/API/Notification.requestPermission" title="The requestPermission static method is used to ask the user for his permission to display a Notification to him."><code>Notification.requestPermission()</code></a> (參閱 <a href="https://code.google.com/p/chromium/issues/detail?id=274284" title="https://code.google.com/p/chromium/issues/detail?id=274284">issue 274284</a>)。</p> +</div> + +<h3 id="已安裝的_Apps">已安裝的 Apps</h3> + +<p>在安裝 Apps 之後,若於 <a href="https://developer.mozilla.org/zh-TW/docs/%E6%87%89%E7%94%A8%E7%A8%8B%E5%BC%8F/Manifest-840092-dup" title="/en-US/docs/Web/Apps/Manifest">Apps 的 manifest 檔案</a>中直接添加權限,即可省去再次向使用者要求權限的動作。</p> + +<pre class="brush: json">permissions: { + "desktop-notification": { + "description: "Allows to display notifications on the user's desktop. + } +}</pre> + +<h2 id="建立通知">建立通知</h2> + +<p>透過 <a href="https://developer.mozilla.org/en-US/docs/Web/API/Notification" title="The Notification object is used to configure and display desktop notifications to the user."><code>Notification</code></a> 建構子 (Constructor) 即可建立通知。此建構子包含 1 組標題,可於通知內顯示;另有如 <a href="https://developer.mozilla.org/en-US/docs/Web/API/Notification.icon" title="The icon property indicates the URL of the icon to use with the notification."><code>icon</code></a> 或文字 <a href="https://developer.mozilla.org/en-US/docs/Web/API/Notification.body" title="The body property represents the text content of the body of the notification."><code>body</code></a><code> 等</code>數個選項,可強化通知的內容。</p> + +<p>在建立實體 (Instantiated) 之後,就會儘快顯示通知。若要追蹤通知的目前狀態,必須在 <a href="https://developer.mozilla.org/en-US/docs/Web/API/Notification" title="The Notification object is used to configure and display desktop notifications to the user."><code>Notification</code></a> 的實體階層觸發 4 個事件:</p> + +<ul> + <li><a href="https://developer.mozilla.org/en-US/docs/Web/Reference/Events/show" title="/en-US/docs/Web/Reference/Events/show">show</a>:對使用者顯示通知之後,隨即觸發</li> + <li><a href="https://developer.mozilla.org/en-US/docs/Web/Reference/Events/click" title="/en-US/docs/Web/Reference/Events/click">click</a>:使用者點擊通知之後,隨即觸發</li> + <li><a href="https://developer.mozilla.org/en-US/docs/Web/Reference/Events/close" title="/en-US/docs/Web/Reference/Events/close">close</a>:關閉通知之後,隨即觸發</li> + <li><a href="https://developer.mozilla.org/en-US/docs/Web/Reference/Events/error" title="/en-US/docs/Web/Reference/Events/error">error</a>:通知發生任何錯誤 (大多數是因為某種情況而未顯示通知),隨即觸發</li> +</ul> + +<p>而透過 <a href="https://developer.mozilla.org/en-US/docs/Web/API/Notification.onshow" title="Specifies an event listener to receive show events. These events occur when a Notification is displayed."><code>onshow</code></a>、<a href="https://developer.mozilla.org/en-US/docs/Web/API/Notification.onclick" title="Specifies an event listener to receive click events. These events occur when the user clicks on a displayed Notification."><code>onclick</code></a>、<a href="https://developer.mozilla.org/en-US/docs/Web/API/Notification.onclose" title="Specifies an event listener to receive close events. These events occur when a Notification is closed."><code>onclose</code></a>,或 <a href="https://developer.mozilla.org/en-US/docs/Web/API/Notification.onerror" title="Specifies an event listener to receive error events. These events occur when something goes wrong with a Notification (in many cases an error prevented the notification from being displayed)."><code>onerror</code></a> 等事件處理器 (Event handler),即可追蹤這些事件。由於 <a href="https://developer.mozilla.org/en-US/docs/Web/API/Notification" title="The Notification object is used to configure and display desktop notifications to the user."><code>Notification</code></a> 是繼承 <a href="https://developer.mozilla.org/en-US/docs/Web/API/EventTarget" title="EventTarget is a DOM interface implemented by objects that can receive DOM events and have listeners for them."><code>EventTarget</code></a> 而來,因此亦可使用 <a href="https://developer.mozilla.org/en-US/docs/Web/API/EventTarget.addEventListener" title="addEventListener() registers the specified listener on the EventTarget it's called on. The event target may be an Element in a document, the Document itself, a Window, or any other object that supports events (such as XMLHttpRequest)."><code>addEventListener()</code></a> 函式。</p> + +<div class="note"> +<p><strong>注意:</strong>Firefox 與 Safari 並未遵守 close 事件的規格。此規格雖然規定「僅限使用者能關閉通知」,但 Firefox 與 Safari 卻可於數分鐘後自動關閉通知。因此不一定是由使用者關閉通知。</p> + +<p>此規格並明確規定「應透過 <a href="https://developer.mozilla.org/en-US/docs/Web/API/Notification.close" title="The close method is used to close a Notification that has been displayed."><code>Notification.close()</code></a> 函式,於應用程式層級完成自動關閉通知」。範例程式碼如下:</p> + +<pre class="brush: js">var n = new Notification("Hi!"); +n.onshow = function () { + setTimeout(n.close, 5000); +} +</pre> +</div> + +<h3 id="簡易範例">簡易範例</h3> + +<p>先假設下列基本 HTML:</p> + +<pre class="brush: html"><button>Notify me!</button></pre> + +<p>則能以這種方法處理通知:</p> + +<pre class="brush: js">window.addEventListener('load', function () { + // At first, let's check if we have permission for notification + // If not, let's ask for it + if (Notification && Notification.permission !== "granted") { + Notification.requestPermission(function (status) { + if (Notification.permission !== status) { + Notification.permission = status; + } + }); + } + var button = document.getElementsByTagName('button')[0]; + button.addEventListener('click', function () { + // If the user agreed to get notified + if (Notification && Notification.permission === "granted") { + var n = new Notification("Hi!"); + } + // If the user hasn't told if he wants to be notified or not + // Note: because of Chrome, we are not sure the permission property + // is set, therefore it's unsafe to check for the "default" value. + else if (Notification && Notification.permission !== "denied") { + Notification.requestPermission(function (status) { + if (Notification.permission !== status) { + Notification.permission = status; + } + // If the user said okay + if (status === "granted") { + var n = new Notification("Hi!"); + } + // Otherwise, we can fallback to a regular modal alert + else { + alert("Hi!"); + } + }); + } + // If the user refuses to get notified + else { + // We can fallback to a regular modal alert + alert("Hi!"); + } + }); +});</pre> + +<h3 id="現場測試結果">現場測試結果</h3> + +<p>若無法顯示,可至本文右上角「Language」切換回英文原文觀看。</p> + +<p>{{ EmbedLiveSample('Simple_example', '100%', 30) }}</p> + +<h2 id="處理多筆通知">處理多筆通知</h2> + +<p>某些情況下 (如某個即時訊息 App 持續通知每一筆進來的訊息),使用者可能會接收大量的通知。為了避免太多非必要訊息擠爆使用者的桌面,則應該讓等待中的通知進入佇列。</p> + +<p>將標籤添加至任何新的通知,即可達到佇列效果。若通知擁有相同的標籤且尚未顯示,則新通知就會取代先前的通知;反之,若已顯示了相同標籤的通知,就會關閉先前的通知而顯示新通知。</p> + +<h3 id="標籤範例">標籤範例</h3> + +<p>先假設下列基本 HTML:</p> + +<pre class="brush: html"><button>Notify me!</button></pre> + +<p>則能以下列方式處理多筆通知:</p> + +<pre class="brush: js">window.addEventListener('load', function () { + // At first, let's check if we have permission for notification + // If not, let's ask for it + if (Notification && Notification.permission !== "granted") { + Notification.requestPermission(function (status) { + if (Notification.permission !== status) { + Notification.permission = status; + } + }); + } + var button = document.getElementsByTagName('button')[0]; + button.addEventListener('click', function () { + // If the user agreed to get notified + // Let's try to send ten notifications + if (Notification && Notification.permission === "granted") { + for (var i = 0; i < 10; i++) { + // Thanks to the tag, we should only see the "Hi! 10" notification + var n = new Notification("Hi! " + i, {tag: 'soManyNotification'}); + } + } + // If the user hasn't told if he wants to be notified or not + // Note: because of Chrome, we are not sure the permission property + // is set, therefore it's unsafe to check for the "default" value. + else if (Notification && Notification.permission !== "denied") { + Notification.requestPermission(function (status) { + if (Notification.permission !== status) { + Notification.permission = status; + } + // If the user said okay + if (status === "granted") { + for (var i = 0; i < 10; i++) { + // Thanks to the tag, we should only see the "Hi! 10" notification + var n = new Notification("Hi! " + i, {tag: 'soManyNotification'}); + } + } + // Otherwise, we can fallback to a regular modal alert + else { + alert(Hi!"); + } + }); + } + // If the user refuses to get notified + else { + // We can fallback to a regular modal alert + alert(Hi!"); + } + }); +});</pre> + +<h3 id="現場測試結果_2">現場測試結果</h3> + +<p>若無法顯示,可至本文右上角「Language」切換回英文原文觀看。</p> + +<p>{{ EmbedLiveSample('Tag_example', '100%', 30) }}</p> + +<h2 id="規格">規格</h2> + +<table class="standard-table"> + <thead> + <tr> + <th scope="col">Specification</th> + <th scope="col">Status</th> + <th scope="col">Comment</th> + </tr> + </thead> + <tbody> + <tr> + <td>{{SpecName('Web Notifications')}}</td> + <td>{{Spec2('Web Notifications')}}</td> + <td>Initial specification.</td> + </tr> + </tbody> +</table> + +<h2 id="瀏覽器相容性">瀏覽器相容性</h2> + +<p>{{page("/en-US/Web/API/Notification","Browser compatibility")}}</p> + +<h2 id="另可參閱">另可參閱</h2> + +<ul> + <li>{{ domxref("Notification") }}</li> +</ul> |
