browser.notifications

說明

使用 chrome.notifications API，透過範本建立豐富的通知，並在系統匣中向使用者顯示這些通知。

權限

notifications

類型

NotificationBitmap

NotificationButton

屬性

• iconUrl

  字串 選填

  自 Chrome 59 起淘汰

  Mac OS X 使用者看不到按鈕圖示。

• title

  字串

NotificationItem

屬性

• 訊息

  字串

  這個項目的其他詳細資料。

• title

  字串

  清單通知中某個項目的標題。

NotificationOptions

屬性

• appIconMaskUrl

  字串 選填

  自 Chrome 59 起淘汰

  Mac OS X 使用者看不到應用程式圖示遮罩。

  應用程式圖示遮罩的網址。網址的限制與 iconUrl 相同。

  應用程式圖示遮罩應位於 Alpha 色版，因為系統只會考量圖片的 Alpha 色版。

• 按鈕

  NotificationButton[] 選用

  最多兩個通知動作按鈕的文字和圖示。

• contextMessage

  字串 選填

  通知內容改用較細的字型。

• eventTime

  數字 選填

  與通知相關聯的時間戳記，以 Epoch 紀元時間算起的毫秒數表示 (例如 Date.now() + n)。

• iconUrl

  字串 選填

  寄件者顯示圖片、應用程式圖示或圖片通知縮圖的網址。

  網址可以是資料網址、blob 網址，或與這項擴充功能 .crx 檔案中資源相關的網址

  **注意：**notifications.create() 方法必須提供這個值。

• imageUrl

  字串 選填

  自 Chrome 59 起淘汰

  Mac OS X 使用者不會看到這張圖片。

  圖片類型通知的圖片縮圖網址。網址的限制與 iconUrl 相同。

• isClickable

  布林值 選填

  Chrome 67 起已淘汰

  自 Chrome 67 起，系統會忽略這個 UI 提示

• 項目

  NotificationItem[] 選用

  多項目通知的項目。Mac OS X 使用者只會看到第一個項目。

• 訊息

  字串 選填

  主要通知內容。

  **注意：**notifications.create() 方法必須提供這個值。

• 優先順序

  數字 選填

  優先順序範圍為 -2 到 2。-2 是最低優先順序。2 為最高。預設值為 0。在不支援通知中心的平台上 (Windows、Linux 和 Mac)，-2 和 -1 會導致錯誤，因為系統完全不會顯示這些優先順序的通知。

• 進度

  數字 選填

  目前進度介於 0 到 100 之間。

• requireInteraction

  布林值 選填

  Chrome 50 以上版本 Chrome 148 以上版本的 browser.*

  表示通知應持續顯示在畫面上，直到使用者啟用或關閉通知為止。預設值為 false。

• 靜音

  布林值 選填

  Chrome 70 以上版本 瀏覽器。*自 Chrome 148 起

  表示顯示通知時不應發出任何音效或震動。預設值為 false。

• title

  字串 選填

  通知標題 (例如電子郵件寄件者名稱)。

  **注意：**notifications.create() 方法必須提供這個值。

• 類型

  TemplateType 選填

  要顯示的通知類型。notifications.create 方法的必要項目。

PermissionLevel

列舉

"granted"
指定使用者已選擇顯示應用程式或擴充功能的通知。這是安裝時的預設值。

"denied"
指定使用者選擇不顯示應用程式或擴充功能的通知。

TemplateType

列舉

「basic」
包含圖示、標題、訊息、expandedMessage 和最多兩個按鈕。

"image"
包含圖示、標題、訊息、expandedMessage、圖片和最多兩個按鈕。

「list」
包含圖示、標題、訊息、項目和最多兩個按鈕。Mac OS X 使用者只會看到第一個項目。

「progress」
包含圖示、標題、訊息、進度，以及最多兩個按鈕。

方法

clear()

browser.notifications.clear(
  notificationId: string,
): Promise<boolean>

清除指定通知。

參數

• notificationId

  字串

  要清除的通知 ID。這個值由 notifications.create 方法傳回。

傳回

• Promise<boolean>

  Chrome 116 以上版本 Chrome 148 以上版本支援 browser.*

  傳回 Promise，解析後會指出是否有相符的通知。

create()

browser.notifications.create(
  notificationId?: string,
  options: NotificationOptions,
): Promise<string>

建立並顯示通知。

參數

• notificationId

  字串 選填

  通知 ID。如果未設定或留空，系統會自動產生 ID。如果與現有通知相符，這個方法會先清除該通知，再繼續執行建立作業。ID 長度不得超過 500 個半形字元。

  Chrome 42 之前必須使用 notificationId 參數。

• 選項

  NotificationOptions

  通知內容。

傳回

• Promise<string>

  Chrome 116 以上版本 Chrome 148 以上版本支援 browser.*

  傳回 Promise，其會解析為代表已建立通知的通知 ID (提供或產生)。

getAll()

browser.notifications.getAll(): Promise<object>

擷取這個應用程式或擴充功能的所有通知。

傳回

• Promise<object>

  Chrome 116 以上版本 Chrome 148 以上版本支援 browser.*

  傳回 Promise，其中包含系統目前的一組 notification_id。

getPermissionLevel()

browser.notifications.getPermissionLevel(): Promise<PermissionLevel>

擷取使用者是否已啟用這個應用程式或擴充功能的通知。

傳回

• Promise<PermissionLevel>

  Chrome 116 以上版本 Chrome 148 以上版本支援 browser.*

  傳回 Promise，並解析為目前的權限等級。

update()

browser.notifications.update(
  notificationId: string,
  options: NotificationOptions,
): Promise<boolean>

更新現有通知。

參數

• notificationId

  字串

  要更新的通知 ID。這個值由 notifications.create 方法傳回。

• 選項

  NotificationOptions

  要更新的通知內容。

傳回

• Promise<boolean>

  Chrome 116 以上版本 Chrome 148 以上版本支援 browser.*

  傳回 Promise，解析後會指出是否有相符的通知。

事件

onButtonClicked

browser.notifications.onButtonClicked.addListener(
  callback: function,
)

使用者按下通知中的按鈕。

參數

• callback

  函式

  callback 參數如下：

  (notificationId: string, buttonIndex: number) => void

  • notificationId

    字串

  • buttonIndex

    數字

onClicked

browser.notifications.onClicked.addListener(
  callback: function,
)

使用者點選通知的非按鈕區域。

參數

• callback

  函式

  callback 參數如下：

  (notificationId: string) => void

  • notificationId

    字串

onClosed

browser.notifications.onClosed.addListener(
  callback: function,
)

通知已關閉 (由系統或使用者動作觸發)。

參數

• callback

  函式

  callback 參數如下：

  (notificationId: string, byUser: boolean) => void

  • notificationId

    字串

  • byUser

    布林值

onPermissionLevelChanged

browser.notifications.onPermissionLevelChanged.addListener(
  callback: function,
)

使用者變更權限等級。自 Chrome 47 起，只有 ChromeOS 的使用者介面會調度這項事件。

參數

• callback

  函式

  callback 參數如下：

  (level: PermissionLevel) => void

  • 等級

    PermissionLevel

onShowSettings

自 Chrome 65 起淘汰

browser.notifications.onShowSettings.addListener(
  callback: function,
)

系統不再支援自訂通知設定按鈕。

使用者點選應用程式通知設定的連結。自 Chrome 47 起，只有 ChromeOS 的 UI 會調度這個事件。自 Chrome 65 起，ChromeOS 也移除了該使用者介面。

參數

• callback

  函式

  callback 參數如下：

  () => void