chrome.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

    號碼 選填

    與通知相關的時間戳記，以紀元後毫秒為單位 (例如 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 是最高優先順序。預設值為零。在不支援通知中心的平台 (Windows、Linux 和 Mac) 上，如果優先順序為 -2 和 -1，系統會傳回錯誤，因為這類通知完全不會顯示。

  • 進度

    號碼 選填

    目前進度範圍為 0 到 100。

  • requireInteraction

    布林值 選填

    Chrome 50 以上版本

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

  • 靜音

    布林值 選填

    Chrome 70 以上版本

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

  • title

    字串 選填

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

    **注意：**如為 notifications.create() 方法，則此為必要值。

  • 類型

    TemplateType 選用

    要顯示的通知類型。notifications.create 方法需要此參數。

PermissionLevel

列舉

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

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

TemplateType

列舉

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

「image」
包含圖示、標題、訊息、expandedMessage、圖片，以及最多兩個按鈕。

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

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

方法

clear()

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

清除指定通知。

參數

傳回

  • Promise<boolean>

    Chrome 116 以上版本

create()

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

建立並顯示通知。

參數

  • notificationId

    字串 選填

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

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

  • 通知內容。

傳回

  • Promise<string>

    Chrome 116 以上版本

getAll()

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

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

傳回

  • Promise<object>

    Chrome 116 以上版本

getPermissionLevel()

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

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

傳回

update()

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

更新現有通知。

參數

傳回

  • Promise<boolean>

    Chrome 116 以上版本

事件

onButtonClicked

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

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

參數

  • callback

    函式

    callback 參數如下： 

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

    • notificationId

      字串

    • buttonIndex

      數字

onClicked

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

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

參數

  • callback

    函式

    callback 參數如下： 

    (notificationId: string) => void

    • notificationId

      字串

onClosed

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

通知已關閉 (由系統或使用者關閉)。

參數

  • callback

    函式

    callback 參數如下： 

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

    • notificationId

      字串

    • byUser

      布林值

onPermissionLevelChanged

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

使用者變更權限等級。自 Chrome 47 起，只有 ChromeOS 具有可傳送這項事件的使用者介面。

參數

onShowSettings

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

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

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

參數

  • callback

    函式

    callback 參數如下： 

    () => void