使用通知 API

您可以使用 browser.notifications API 透過範本建立通知,並在使用者系統匣中向使用者顯示這些通知:

系統使用者匣中的通知

外觀

複合式通知有四種不同類型:基本、圖片、清單和進度。所有通知都包含標題、訊息、顯示在通知訊息左側的小圖示,以及 contextMessage 欄位,這個欄位會以較淺的字型顏色顯示為第三個文字欄位。

基本通知:

基本通知

清單通知會顯示任意數量的清單項目:

清單通知

圖片通知會顯示圖片預覽畫面:

圖片通知

進度通知會顯示進度列:

進度通知

行為方式

在 ChromeOS 中,通知會顯示在使用者系統匣,並保留在系統匣中,直到使用者關閉為止。系統匣會統計所有新通知的數量。使用者在系統匣中看到通知後,計數就會重設為零。

通知的優先順序可設為 -2 到 2 之間。優先順序小於 0 的通知會顯示在 ChromeOS 通知中心,並在其他平台產生錯誤。預設優先順序為 0。優先順序大於 0 時,通知顯示時間會增加,且系統匣中可顯示更多高優先順序通知。

priority 設定不會影響 macOS 上的通知順序。

除了顯示資訊外,所有通知類型最多可包含兩項動作項目。 使用者點選動作項目時,擴充功能可以回應適當的動作。舉例來說,使用者點選「回覆」時,系統會開啟電子郵件應用程式,讓使用者完成回覆:

通知中的動作

如何開發這些功能

如要使用這個 API,請呼叫 notifications.create() 方法,並使用 options 參數傳遞通知詳細資料:

await browser.notifications.create(id, options);

notifications.NotificationOptions 必須包含 notifications.TemplateType,用於定義可用的通知詳細資料,以及這些詳細資料的顯示方式。

建立基本通知

所有範本類型 (basic、image、list 和 progress) 都必須包含通知 title 和 message,以及 iconUrl,這是小型圖示的連結,會顯示在通知訊息左側。

以下是 basic 範本的範例:

var opt = {
  type: "basic",
  title: "Primary Title",
  message: "Primary message to display",
  iconUrl: "url_to_small_icon"
}

使用現有圖片

image 範本類型也包含 imageUrl,這是通知中預覽圖片的連結。請注意,圖片不會向 macOS 使用者顯示。

var opt = {
  type: "image",
  title: "Primary Title",
  message: "Primary message to display",
  iconUrl: "url_to_small_icon",
  imageUrl: "url_to_preview_image"
}

建立清單通知

list 範本會以清單格式顯示 items。請注意,macOS 使用者只會看到第一個項目。

var opt = {
  type: "list",
  title: "Primary Title",
  message: "Primary message to display",
  iconUrl: "url_to_small_icon",
  items: [{ title: "Item1", message: "This is item 1."},
          { title: "Item2", message: "This is item 2."},
          { title: "Item3", message: "This is item 3."}]
}```

### Create progress notification {: #progress }

The `progress` template displays a progress bar where current progress ranges from 0 to 100. On macOS the progress bar displays as a percentage value in the notification title instead of in the progress bar.

```js
var opt = {
  type: "progress",
  title: "Primary Title",
  message: "Primary message to display",
  iconUrl: "url_to_small_icon",
  progress: 42
}

監聽及回應事件

所有通知都可以包含事件監聽器和事件處理常式,用來回應使用者動作 (請參閱 browser.events)。舉例來說,您可以編寫事件處理常式來回應 notifications.onButtonClicked 事件。

事件監聽器:

browser.notifications.onButtonClicked.addListener(replyBtnClick);

事件處理常式:

function replyBtnClick {
    //Write function to respond to user action.
}

建議在 Service Worker 中加入事件監聽器和處理常式,這樣即使擴充功能未執行,通知也能彈出。