chrome.notifications

說明

使用 chrome.notifications API 即可利用範本建立複合式通知，並在系統匣中向使用者顯示這些通知。

權限

notifications

類型

NotificationBitmap

NotificationButton

屬性

  • iconUrl

    string optional

    自 Chrome 59 版起已淘汰

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

  • title

    字串

NotificationItem

屬性

  • 訊息

    字串

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

  • title

    字串

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

NotificationOptions

屬性

  • appIconMaskUrl

    string optional

    自 Chrome 59 版起已淘汰

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

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

    應用程式圖示遮罩應採用 Alpha 通道，因為系統只會考慮圖片的 Alpha 通道。

  • 按鈕

    NotificationButton[] 選用

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

  • contextMessage

    string optional

    使用較低字型的替代通知內容。

  • eventTime

    編號 選填

    與通知相關聯的時間戳記，以 Epoch 紀元時間計算的毫秒為單位 (例如 Date.now() + n)。

  • iconUrl

    string optional

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

    網址可以是資料網址、blob 網址或此擴充功能 .crx 檔案中資源相對的網址

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

  • imageUrl

    string optional

    自 Chrome 59 版起已淘汰

    Mac OS X 使用者無法看到這張圖片。

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

  • isClickable

    布林值 選填

    自 Chrome 67 版起已淘汰

    自 Chrome 67 版起會忽略這個 UI 提示

  • items

    NotificationItem[] 選用

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

  • 訊息

    string optional

    主要通知內容。

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

  • 優先順序

    編號 選填

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

  • 進度

    編號 選填

    目前進度範圍為 0 到 100。

  • requireInteraction

    布林值 選填

    Chrome 50 以上版本

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

  • 靜音

    布林值 選填

    Chrome 70 以上版本

    表示當通知顯示時，不得發出音效或震動。預設值為 false。

  • title

    string optional

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

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

  • 類型

    TemplateType 選用

    要顯示的通知類型。以 notifications.create 方法來說，此為必要屬性。

PermissionLevel

列舉

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

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

TemplateType

列舉

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

「image」
包含圖示、標題、訊息、展開訊息、圖片和最多兩個按鈕。

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

"progress"
包含圖示、標題、訊息、進度和最多兩個按鈕。

方法

clear()

Promise 
chrome.notifications.clear(
  notificationId: string,
  callback?: function,
)

清除指定通知。

參數

  • notificationId

    字串

    要清除通知的 ID。notifications.create 方法會傳回此方法。

  • 回呼

    函式 選用

    callback 參數如下所示： 

    (wasCleared: boolean) => void

    • wasCleared

      布林值

傳回

  • Promise<boolean>

    Chrome 116 以上版本

    Promise 僅適用於 Manifest V3 及以上版本，其他平台需要使用回呼。

create()

Promise 
chrome.notifications.create(
  notificationId?: string,
  options: NotificationOptions,
  callback?: function,
)

建立並顯示通知。

參數

  • notificationId

    string optional

    通知的 ID。如未設定或留空，系統會自動產生 ID。如果與現有通知相符，這個方法會先清除該通知，然後再繼續建立作業。識別碼不得超過 500 個字元。

    notificationId 是 Chrome 42 之前的版本之一。

  • 通知的內容。

  • 回呼

    函式 選用

    callback 參數如下所示： 

    (notificationId: string) => void

    • notificationId

      字串

傳回

  • 承諾<字串>

    Chrome 116 以上版本

    Promise 僅適用於 Manifest V3 及以上版本，其他平台需要使用回呼。

getAll()

Promise 
chrome.notifications.getAll(
  callback?: function,
)

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

參數

  • 回呼

    函式 選用

    callback 參數如下所示： 

    (notifications: object) => void

    • 通知

      物件

傳回

  • Promise&lt;object&gt;

    Chrome 116 以上版本

    Promise 僅適用於 Manifest V3 及以上版本，其他平台需要使用回呼。

getPermissionLevel()

Promise 
chrome.notifications.getPermissionLevel(
  callback?: function,
)

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

參數

傳回

  • Promise&lt;PermissionLevel&gt;

    Chrome 116 以上版本

    Promise 僅適用於 Manifest V3 及以上版本，其他平台需要使用回呼。

update()

Promise 
chrome.notifications.update(
  notificationId: string,
  options: NotificationOptions,
  callback?: function,
)

更新現有的通知。

參數

  • notificationId

    字串

    要更新的通知 ID。notifications.create 方法會傳回此方法。

  • 要更新的通知內容。

  • 回呼

    函式 選用

    callback 參數如下所示： 

    (wasUpdated: boolean) => void

    • wasUpdated

      布林值

傳回

  • Promise&lt;boolean&gt;

    Chrome 116 以上版本

    Promise 僅適用於 Manifest V3 及以上版本，其他平台需要使用回呼。

活動

onButtonClicked

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

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

參數

  • 回呼

    函式

    callback 參數如下所示： 

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

    • notificationId

      字串

    • buttonIndex

      數字

onClicked

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

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

參數

  • 回呼

    函式

    callback 參數如下所示： 

    (notificationId: string) => void

    • notificationId

      字串

onClosed

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

系統或使用者動作關閉通知。

參數

  • 回呼

    函式

    callback 參數如下所示： 

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

    • notificationId

      字串

    • byUser

      布林值

onPermissionLevelChanged

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

使用者變更了權限層級。在 Chrome 47 中，只有 ChromeOS 的 UI 會分派這個事件。

參數

onShowSettings

自 Chrome 65 版起已淘汰
chrome.notifications.onShowSettings.addListener(
  callback: function,
)

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

使用者點選應用程式通知設定的連結。在 Chrome 47 中，只有 ChromeOS 的 UI 會分派這個事件。自 Chrome 65 起，這類使用者介面已從 ChromeOS 中移除。

參數

  • 回呼

    函式

    callback 參數如下所示： 

    () => void