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 提示

  • items

    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"
包含圖示、標題、訊息、已展開訊息和最多兩個按鈕。

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

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

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

方法

clear()

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

清除指定通知。

參數

  • notificationId

    字串

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

  • 回呼

    函式選用

    callback 參數如下所示： 

    (wasCleared: boolean)=>void

    • wasCleared

      boolean

傳回

  • Promise<boolean>

    Chrome 116 以上版本

    Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

create()

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

建立並顯示通知。

參數

  • notificationId

    字串 選用

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

    在 Chrome 42 以下版本中必須使用 notificationId 參數。

  • 通知的內容。

  • 回呼

    函式選用

    callback 參數如下所示： 

    (notificationId: string)=>void

    • notificationId

      字串

傳回

  • Promise<string>

    Chrome 116 以上版本

    Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

getAll()

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

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

參數

  • 回呼

    函式選用

    callback 參數如下所示： 

    (notifications: object)=>void

    • 通知

      物件

傳回

  • Promise<object>

    Chrome 116 以上版本

    Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

getPermissionLevel()

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

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

參數

傳回

  • Promise<PermissionLevel>

    Chrome 116 以上版本

    Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

update()

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

更新現有通知。

參數

  • notificationId

    字串

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

  • 要更新的通知內容。

  • 回呼

    函式選用

    callback 參數如下所示： 

    (wasUpdated: boolean)=>void

    • wasUpdated

      boolean

傳回

  • Promise<boolean>

    Chrome 116 以上版本

    Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

活動

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

      boolean

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 版起，該 UI 也已從 ChromeOS 中移除。

參數

  • 回呼

    功能

    callback 參數如下所示： 

    ()=>void