本頁面由 Cloud Translation API 翻譯而成。

應用程式圖示徽章

應用程式徽章 API 可讓已安裝的網頁應用程式在應用程式圖示上設定應用程式全域徽章。

Pete LePage

什麼是 App Badging API？

範例：Twitter 有八則通知，另一個應用程式則顯示旗幟類型的徽章。 — Twitter 有八則通知，另一個應用程式則顯示旗幟類型的徽章。

應用程式徽章 API 可讓已安裝的網頁應用程式設定應用程式全域徽章，並顯示在與應用程式相關聯的作業系統特定位置 (例如書架或主畫面)。

使用徽章，您就能輕鬆地向使用者通知有需要注意的新活動，或是顯示少量資訊 (例如未讀數量)。

徽章比通知更友善，而且不會打斷使用者，因此可以更頻繁地更新。而且，由於不會中斷使用者操作，因此不需要使用者同意。

可能的用途

以下是可能會使用此 API 的應用程式範例：

即時通訊、電子郵件和社群媒體應用程式，用於顯示新訊息或未讀項目數量。
工作效率應用程式，用於指出長時間執行的背景工作 (例如算繪圖片或影片) 已完成。
遊戲，用於表示需要玩家採取行動 (例如在西洋棋中，當輪到玩家時)。

支援

應用程式徽章 API 適用於 Windows 和 macOS 的 Chrome 81 和 Edge 81 以上版本。我們正在開發 ChromeOS 支援功能，並會在日後的版本中推出。Android 不支援 Badging API。相反地，當安裝的網頁應用程式有未讀通知時，Android 會自動在應用程式圖示上顯示徽章，就像 Android 應用程式一樣。

立即試用

開啟 App Badging API 示範。
系統提示時，請按一下「安裝」安裝應用程式，或使用 Chrome 選單安裝應用程式。
以已安裝的 PWA 形式開啟。請注意，它必須以已安裝的 PWA 形式執行 (在工作列或 Dock 中)。
按一下「Set」或「Clear」按鈕，即可在應用程式圖示上設定或清除徽章。您也可以為徽章值提供數字。

如何使用 App Badging API

如要使用應用程式徽章 API，您的網頁應用程式必須符合 Chrome 的安裝可行性標準，且使用者必須將應用程式新增至主畫面。

Badge API 包含 navigator 上的兩種方法：

setAppBadge(number)：設定應用程式的徽章。如果提供值，請將徽章設為提供的值；否則，請顯示純白色圓點 (或其他適合平台的標記)。將 number 設為 0，就等同於呼叫 clearAppBadge()。
clearAppBadge()：移除應用程式的徽章。

兩者都會傳回空白承諾，可用於錯誤處理。

徽章可以從目前的網頁或已註冊的 Service Worker 設定。如要在前景頁面或服務工作站中設定或清除徽章，請呼叫：

// Set the badge
const unreadCount = 24;
navigator.setAppBadge(unreadCount).catch((error) => {
  //Do something with the error.
});

// Clear the badge
navigator.clearAppBadge().catch((error) => {
  // Do something with the error.
});

在某些情況下，作業系統可能無法正確顯示徽章。在這種情況下，瀏覽器會嘗試為該裝置提供最佳呈現方式。舉例來說，由於 Android 不支援 Badging API，因此 Android 只會顯示圓點，而非數值。

請勿對使用者代理程式顯示徽章的方式做出任何假設。部分使用者代理程式可能會將「4000」這類數字重寫為「99+」。如果您自行將徽章設為飽和狀態 (例如將其設為「99」)，則「+」就不會顯示。無論實際數字為何，只要呼叫 setAppBadge(unreadCount)，讓使用者代理程式處理顯示方式即可。

雖然 Chrome 中的應用程式徽章 API 需要已安裝的應用程式，但您不應根據安裝狀態呼叫徽章 API。只要在 API 存在時呼叫 API，因為其他瀏覽器可能會在其他位置顯示徽章。如果方法奏效，那就放心去做；否則就不會。

透過服務工作者在背景設定及清除徽章

您也可以使用服務工作者，在背景設定應用程式徽章。您可以透過定期在背景同步處理、Push API，或兩者結合的方式進行這項操作。

定期在背景同步處理

定期在背景同步處理可讓服務工作者定期輪詢伺服器，以便取得更新狀態並呼叫 navigator.setAppBadge()。

不過，呼叫同步作業的頻率並非完全可靠，而是由瀏覽器自行決定。

Web Push API

Push API 可讓伺服器將訊息傳送至服務工作者，即使沒有前景頁面執行，服務工作者也能執行 JavaScript 程式碼。因此，伺服器推送可透過呼叫 navigator.setAppBadge() 更新徽章。

不過，Chrome 等大多數瀏覽器都會在收到推播訊息時顯示通知。這在某些用途上沒問題 (例如在更新徽章時顯示通知)，但如果不顯示通知，就無法巧妙地更新徽章。

此外，使用者必須授予網站通知權限，才能接收推送訊息。

兩者皆有

雖然不完美，但 Push API 和定期背景同步功能搭配使用，可提供不錯的解決方案。系統會透過 Push API 傳送高優先順序資訊，顯示通知並更新徽章。而較低優先順序的資訊則是透過更新徽章來提供，無論是在網頁開啟時，或是透過定期的背景同步處理作業。

意見回饋

Chrome 團隊希望瞭解你使用 App Badging API 的體驗。

請告訴我們 API 設計

API 中是否有任何功能無法正常運作？或者，您是否缺少實作想法所需的方法或屬性？您對安全性模型有任何疑問或意見嗎？

在 Badging API GitHub 存放區中提出規格問題，或在現有問題中加入您的想法。

回報實作問題

你是否發現 Chrome 實作項目有錯誤？還是實作方式與規格不同？

請前往 https://new.crbug.com 提交錯誤。請務必盡可能提供詳細資訊，提供重現問題的簡單操作說明，並將「元件」設為 UI>Browser>WebAppInstalls。Glitch 可讓你輕鬆快速地分享重現內容。

顯示對 API 的支援

是否打算在網站上使用 App Badging API？您的公開支援內容有助於 Chrome 團隊決定功能優先順序，並向其他瀏覽器供應商顯示支援這些功能的重要性。

使用主題標記 #BadgingAPI 發送推文給 @ChromiumDev，告訴我們你在何處使用這項功能，以及使用方式。

實用連結

主頁相片來源：Prateek Katyal 在 Unsplash 上提供