browser.runtime

說明

使用 chrome.runtime API 擷取 Service Worker、傳回資訊清單的詳細資料，以及監聽和回應擴充功能生命週期中的事件。您也可以使用這個 API，將網址的相對路徑轉換為完整網址。

這個 API 的大多數成員都不需要任何權限。connectNative()、sendNativeMessage() 和 onNativeConnect 需要這項權限。

以下範例說明如何在資訊清單中宣告 "nativeMessaging" 權限：

manifest.json:

{
  "name": "My extension",
  ...
  "permissions": [
    "nativeMessaging"
  ],
  ...
}

概念和用途

Runtime API 提供的方法可支援擴充功能使用的多個領域：

訊息傳遞

擴充功能可以使用下列方法和事件，與擴充功能內的不同情境通訊，也可以與其他擴充功能通訊： connect()、 onConnect、 onConnectExternal、 sendMessage()、 onMessage 和 onMessageExternal。 此外，擴充功能可以使用 connectNative() 和 sendNativeMessage()，將訊息傳遞至使用者裝置上的原生應用程式。

注意：如需主題總覽，請參閱「訊息傳遞」。

存取擴充功能和平台中繼資料

這些方法可讓您擷取擴充功能和平台的幾項特定中繼資料。這個類別的方法包括 getManifest() 和 getPlatformInfo()。

管理擴充功能生命週期和選項

這些屬性可讓您對擴充功能執行一些中繼作業，並顯示選項頁面。這個類別的方法和事件包括 onInstalled、onStartup、openOptionsPage()、reload()、requestUpdateCheck() 和 setUninstallURL()。

輔助公用程式

這些方法提供實用功能，例如將內部資源表示法轉換為外部格式。這個類別的方法包括 getURL()。

Kiosk 模式公用程式

這些方法僅適用於 ChromeOS，主要用於支援 Kiosk 模式。 這類方法包括 restart() 和 restartAfterDelay()。

未封裝擴充功能的行為

重新載入未封裝的擴充功能時，系統會將其視為更新。這表示 browser.runtime.onInstalled 事件會以 "update" 原因觸發。包括使用 browser.runtime.reload() 重新載入擴充功能時。

用途

在網頁中新增圖片

如要讓網頁存取其他網域託管的素材資源，必須指定資源的完整網址 (例如 <img src="https://example.com/logo.png">)。如要在網頁中加入擴充功能素材資源，也必須這麼做。兩者的差異在於，擴充功能的素材資源必須公開為可透過網路存取的資源，且通常由內容指令碼負責插入擴充功能素材資源。

在這個範例中，擴充功能會使用 runtime.getURL() 建立完整網址，將 logo.png 新增至插入內容指令碼的頁面。但首先，必須在資訊清單中將素材資源宣告為可透過網路存取的資源。

manifest.json:

{
  ...
  "web_accessible_resources": [
    {
      "resources": [ "logo.png" ],
      "matches": [ "https://*/*" ]
    }
  ],
  ...
}

content.js:

{ // Block used to avoid setting global variables
  const img = document.createElement('img');
  img.src = browser.runtime.getURL('logo.png');
  document.body.append(img);
}

將資料從內容指令碼傳送至 Service Worker

擴充功能的內容指令碼通常需要由擴充功能其他部分 (例如 Service Worker) 管理的資料。就像兩個瀏覽器視窗開啟同一個網頁一樣，這兩個情境無法直接存取彼此的值。擴充功能可改用訊息傳遞，在這些不同情境之間協調。

在這個範例中，內容指令碼需要擴充功能 Service Worker 的部分資料，才能初始化 UI。為取得這項資料，系統會將開發人員定義的 get-user-data 訊息傳遞給 Service Worker，並以使用者資訊副本回應。

content.js:

// 1. Send a message to the service worker requesting the user's data
browser.runtime.sendMessage('get-user-data', (response) => {
  // 3. Got an asynchronous response with the data from the service worker
  console.log('received user data', response);
  initializeUI(response);
});

service-worker.js：

// Example of a simple user data object
const user = {
  username: 'demo-user'
};

browser.runtime.onMessage.addListener((message, sender, sendResponse) => {
  // 2. A page requested user data, respond with a copy of `user`
  if (message === 'get-user-data') {
    sendResponse(user);
  }
});

收集解除安裝意見

許多擴充功能會使用解除安裝後問卷調查，瞭解如何改善擴充功能，為使用者提供更優質的服務，並提高留存率。以下範例說明如何新增這項功能。

background.js:

browser.runtime.onInstalled.addListener(details => {
  if (details.reason === browser.runtime.OnInstalledReason.INSTALL) {
    browser.runtime.setUninstallURL('https://example.com/extension-survey');
  }
});

範例

如需更多 Runtime API 範例，請參閱 Manifest V3 - Web Accessible Resources 示範。

類型

ContextFilter

Chrome 114 以上版本 Chrome 148 以上版本為 browser.*

用於比對特定擴充功能情境的篩選器。比對情境必須符合所有指定篩選條件；未指定的篩選條件則會比對所有可用情境。因此，篩選器 `{}` 會比對所有可用的情境。

屬性

• contextIds

  string[] 選填

• contextTypes

  ContextType[] 選填

• documentIds

  string[] 選填

• documentOrigins

  string[] 選填

• documentUrls

  string[] 選填

• frameIds

  number[] 選填

• incognito

  布林值 選填

• tabIds

  number[] 選填

• windowIds

  number[] 選填

ContextType

Chrome 114 以上版本 Chrome 148 以上版本為 browser.*

列舉

"TAB"
將情境類型指定為分頁

"POPUP"
將內容類型指定為擴充功能彈出式視窗

"BACKGROUND"
將背景類型指定為 Service Worker。

"OFFSCREEN_DOCUMENT"
將內容類型指定為螢幕外文件。

"SIDE_PANEL"
將內容類型指定為側邊面板。

"DEVELOPER_TOOLS"
將情境類型指定為開發人員工具。

ExtensionContext

Chrome 114 以上版本 Chrome 148 以上版本為 browser.*

託管擴充功能內容的結構定義。

屬性

• contextId

  字串

  這個情境的專屬 ID

• contextType

  ContextType

  這對應的背景資訊類型。

• documentId

  字串 選填

  與這個情境相關聯的文件 UUID，如果這個情境並非託管於文件中，則為未定義。

• documentOrigin

  字串 選填

  與這個情境相關聯的文件來源，如果情境並非託管於文件中，則為未定義。

• documentUrl

  字串 選填

  與這個內容相關聯的文件網址，如果內容並非託管於文件中，則為未定義。

• frameId

  數字

  這個情境的頁框 ID，如果情境並非託管於頁框中，則為 -1。

• incognito

  布林值

  背景資訊是否與無痕模式設定檔相關聯。

• tabId

  數字

  這個情境的分頁 ID，如果情境並非託管於分頁中，則為 -1。

• windowId

  數字

  這個情境的視窗 ID，如果這個情境並非託管於視窗中，則為 -1。

ExtensionLoadDetails

Chrome 157 以上版本

擴充功能載入事件的詳細資料。

屬性

• previousVersion

  字串 選填

  指出擴充功能的舊版本。只有在「reason」為「update」或「enable」時，才會顯示這個欄位。如果「reason」是「update」，則代表這是擴充功能更新前的版本。如果「reason」為「enable」，則這是擴充功能的目前版本。

• reason

  OnLoadedReason

  調度這項事件的原因。

MessageSender

這個物件包含傳送訊息或要求的指令碼背景資訊。

屬性

• documentId

  字串 選填

  Chrome 106 以上版本 Chrome 148 起為 browser.*

  開啟連線的文件 UUID。

• documentLifecycle

  字串 選填

  Chrome 106 以上版本 Chrome 148 起為 browser.*

  建立通訊埠時，開啟連線的文件所處的生命週期。請注意，文件的生命週期狀態可能在建立通訊埠後有所變更。

• frameId

  數字 選填

  開啟連線的框架。頂層頁框為 0，子頁框為正數。只有在設定 tab 時，才會設定這個值。

• id

  字串 選填

  開啟連線的擴充功能 ID (如果有的話)。

• nativeApplication

  字串 選填

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

  開啟連線的原生應用程式名稱 (如有)。

• origin

  字串 選填

  Chrome 80 以上版本 瀏覽器 (自 Chrome 148 起)

  開啟連線的網頁或框架來源。可能與網址屬性不同 (例如 about:blank)，也可能不透明 (例如沙箱 iframe)。如果無法立即從網址判斷來源是否可信，這項資訊就很有幫助。

• Tab 鍵

  分頁 選填

  開啟連線的 tabs.Tab (如果有的話)。只有在連線是從分頁 (包括內容指令碼) 開啟，且接收端是擴充功能而非應用程式時，系統才會顯示這個屬性。

• tlsChannelId

  字串 選填

  開啟連線的頁面或頁框的 TLS 頻道 ID (如果擴充功能要求，且可用)。

• 網址

  字串 選填

  開啟連線的網頁或框架網址。如果傳送者位於 iframe 中，則會是 iframe 的網址，而非託管該 iframe 的網頁網址。

OnInstalledReason

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

調度這項事件的原因。

列舉

"install"
將事件原因指定為安裝。

"update"
將事件原因指定為擴充功能更新。

"chrome_update"
指定事件原因為 Chrome 更新。

"shared_module_update"
指定事件原因為共用模組更新。

OnLoadedReason

Chrome 157 以上版本

調度這項事件的原因。

列舉

"install"
新安裝的擴充功能。

"update"
擴充功能在更新後重新載入。

"browser_update"
瀏覽器已更新至新版本。

"enable"
擴充功能已從停用狀態重新啟用。

"startup"
在瀏覽器啟動期間載入擴充功能。

"reload"
擴充功能已重新載入 (例如透過 chrome.runtime.reload() 或使用者手動重新載入擴充功能)。

OnRestartRequiredReason

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

調度事件的原因。「app_update」用於應用程式更新至新版本後需要重新啟動的情況。「os_update」：瀏覽器/OS 更新至新版本，因此需要重新啟動。如果系統執行時間超過企業政策設定的允許時間，就會使用「periodic」。

列舉

"app_update"
指定事件原因為應用程式更新。

"os_update"
指定事件原因為作業系統更新。

"periodic"
將事件原因指定為定期重新啟動應用程式。

PlatformArch

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

機器的處理器架構。

列舉

"arm"
將處理器架構指定為 arm。

"arm64"
將處理器架構指定為 arm64。

"x86-32"
將處理器架構指定為 x86-32。

"x86-64"
將處理器架構指定為 x86-64。

"mips"
將處理器架構指定為 mips。

"mips64"
將處理器架構指定為 mips64。

"riscv64"
將處理器架構指定為 riscv64。

PlatformInfo

包含目前平台資訊的物件。

屬性

• arch

  PlatformArch

  機器的處理器架構。

• nacl_arch

  PlatformNaclArch 選用

  自 Chrome 149 起淘汰

  Native Client 已完全移除，因此這項屬性已淘汰。

  原生用戶端架構。在某些平台上，這可能與 arch 不同。

• os

  PlatformOs

  執行 Chrome 的作業系統。

PlatformNaclArch

Chrome 44 以上版本 Chrome 148 起為 browser.* Chrome 149 起淘汰

Native Client 已完全移除，因此這個列舉已淘汰。

原生用戶端架構。在某些平台上，這可能與 arch 不同。

列舉

"arm"
將原生用戶端架構指定為 arm。

"x86-32"
將原生用戶端架構指定為 x86-32。

"x86-64"
將原生用戶端架構指定為 x86-64。

"mips"
將原生用戶端架構指定為 mips。

"mips64"
將原生用戶端架構指定為 mips64。

PlatformOs

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

執行 Chrome 的作業系統。

列舉

"mac"
指定 MacOS 作業系統。

"win"
指定 Windows 作業系統。

"android"
指定 Android 作業系統。

"cros"
指定 Chrome 作業系統。

"linux"
指定 Linux 作業系統。

"openbsd"
指定 OpenBSD 作業系統。

Port

這個物件可與其他網頁進行雙向通訊。詳情請參閱「長期連線」。

屬性

• 名稱

  字串

  通訊埠名稱，如呼叫 runtime.connect 時所指定。

• onDisconnect

  Event<functionvoidvoid>

  當通訊埠與另一端中斷連線時，系統會觸發這個事件。如果通訊埠因錯誤而中斷連線，系統可能會設定 runtime.lastError。如果通訊埠是透過 disconnect 關閉，則這個事件「只會」在另一端觸發。這個事件最多只會觸發一次 (另請參閱「通訊埠生命週期」)。

  onDisconnect.addListener 函式如下所示：

  (callback: function) => {...}

  • callback

    函式

    callback 參數如下：

    (port: Port) => void

    • 通訊埠

      通訊埠

• onMessage

  Event<functionvoidvoid>

  當通訊埠的另一端呼叫 postMessage 時，就會觸發這個事件。

  onMessage.addListener 函式如下所示：

  (callback: function) => {...}

  • callback

    函式

    callback 參數如下：

    (message: any, port: Port) => void

    • 訊息

      任何

    • 通訊埠

      通訊埠

• sender

  MessageSender 選填

  這個屬性只會出現在傳遞至 onConnect/onConnectExternal/onConnectNative 監聽器的通訊埠上。

• 中斷連線

  void

  立即中斷連接埠。對已中斷連線的通訊埠呼叫 disconnect() 不會有任何作用。中斷連線後，系統就不會再將新事件調度至該通訊埠。

  disconnect 函式如下所示：

  () => {...}

• postMessage

  void

  傳送訊息至通訊埠的另一端。如果通訊埠中斷連線，系統會擲回錯誤。

  postMessage 函式如下所示：

  (message: any) => {...}

  • 訊息

    任何

    Chrome 52 以上版本 Chrome 148 以上版本中的 browser.*

    要傳送的訊息。這個物件應可轉換為 JSON。

RequestUpdateCheckStatus

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

更新檢查結果。

列舉

「throttled」
表示狀態檢查已受到限制。如果短時間內重複檢查，就可能發生這種情況。

"no_update"
指定沒有可安裝的更新。

"update_available"
指定有可安裝的更新。

屬性

id

擴充功能/應用程式的 ID。

類型

字串

lastError

如果呼叫 API 函式失敗，則會填入錯誤訊息，否則未定義。這項設定僅在該函式的回呼範圍內定義。如果發生錯誤，但回呼中未存取 runtime.lastError，系統會將訊息記錄到控制台，列出產生錯誤的 API 函式。傳回 Promise 的 API 函式不會設定這項屬性。

類型

物件

屬性

• 訊息

  字串 選填

  發生錯誤的詳細資料。

方法

connect()

browser.runtime.connect(
  extensionId?: string,
  connectInfo?: object,
): Port

嘗試連結擴充功能 (例如背景頁面) 或其他擴充功能/應用程式中的事件監聽器。這項功能適用於連線至擴充功能程序的內容指令碼、應用程式/擴充功能間通訊，以及網頁訊息。請注意，這不會連線至內容指令碼中的任何事件監聽器。擴充功能可透過 tabs.connect 連線至分頁中嵌入的內容指令碼。

參數

• extensionId

  字串 選填

  要連結的擴充功能 ID。如果省略，系統會嘗試與您自己的擴充功能建立連線。如果從網頁訊息的網頁傳送訊息，則必須提供這個欄位。

• connectInfo

  物件 選填

  • includeTlsChannelId

    布林值 選填

    是否要將 TLS 管道 ID 傳遞至 onConnectExternal，用於監聽連線事件的程序。

  • 名稱

    字串 選填

    會傳遞至 onConnect，用於監聽連線事件的程序。

傳回

• 通訊埠

  可收發訊息的通訊埠。如果擴充功能不存在，系統會觸發通訊埠的 onDisconnect 事件。

connectNative()

browser.runtime.connectNative(
  application: string,
): Port

連線至主機中的原生應用程式。這個方法需要 "nativeMessaging" 權限。詳情請參閱「原生訊息」。

參數

• 調度應用程式資源

  字串

  要連線的已註冊應用程式名稱。

傳回

• 通訊埠

  應用程式收發訊息的通訊埠

getBackgroundPage()

僅限前景 自 Chrome 133 起淘汰

browser.runtime.getBackgroundPage(): Promise<Window | undefined>

MV3 擴充功能沒有背景頁面。

擷取目前擴充功能/應用程式中執行的背景網頁 JavaScript「window」物件。如果背景網頁是事件網頁，系統會確保在呼叫回呼前載入該網頁。如果沒有背景頁面，系統會設定錯誤。

傳回

• Promise<Window | undefined>

  Chrome 99 以上版本 瀏覽器 (自 Chrome 148 起)

getContexts()

Chrome 116+ Chrome 148 起為 browser.* MV3+

browser.runtime.getContexts(
  filter: ContextFilter,
): Promise<ExtensionContext[]>

擷取與這個擴充功能相關聯的有效情境資訊

參數

• 篩選器

  ContextFilter

  用於尋找相符情境的篩選器。如果情境符合篩選器中所有指定欄位，即視為相符。篩選器中任何未指定的欄位都會比對所有情境。

傳回

• <ExtensionContext[]> 的 Promise

  Promise 會解析相符的情境 (如有)。

getManifest()

browser.runtime.getManifest(): object

傳回資訊清單中的應用程式或擴充功能詳細資料。傳回的物件是完整資訊清單檔案的序列化。

傳回

• 物件

  資訊清單詳細資料。

getPackageDirectoryEntry()

僅限前景

browser.runtime.getPackageDirectoryEntry(): Promise<DirectoryEntry>

傳回套件目錄的 DirectoryEntry。

傳回

• Promise<DirectoryEntry>

  Chrome 122 以上版本 Chrome 148 以上版本的瀏覽器.*

getPlatformInfo()

browser.runtime.getPlatformInfo(): Promise<PlatformInfo>

傳回目前平台的相關資訊。

傳回

• Promise<PlatformInfo>

  Chrome 99 以上版本 瀏覽器 (自 Chrome 148 起)

  Promise，可解析目前平台的相關資訊。

getURL()

browser.runtime.getURL(
  path: string,
): string

將應用程式/擴充功能安裝目錄中的相對路徑轉換為完整網址。

參數

• 路徑

  字串

  應用程式/擴充功能中資源的路徑，相對於其安裝目錄。

傳回

• 字串

  資源的完整網址。

getVersion()

Chrome 143 以上版本 Chrome 148 起為 browser.*

browser.runtime.getVersion(): string

傳回資訊清單中宣告的擴充功能版本。

傳回

• 字串

  擴充功能版本。

openOptionsPage()

browser.runtime.openOptionsPage(): Promise<void>

如果可以，請開啟擴充功能的選項頁面。

確切行為可能取決於資訊清單的 options_ui 或 options_page 鍵，或 Chrome 當時支援的功能。例如，頁面可能會在新分頁、chrome://extensions、應用程式中開啟，或只是聚焦於開啟的選項頁面。絕不會導致呼叫端網頁重新載入。

如果擴充功能未宣告選項頁面，或 Chrome 因其他原因無法建立選項頁面，回呼會設定 lastError。

傳回

• 承諾<void>

  Chrome 99 以上版本 瀏覽器 (自 Chrome 148 起)

reload()

browser.runtime.reload(): void

重新載入應用程式或擴充功能。Kiosk 模式不支援這個方法。如要使用 Kiosk 模式，請使用 chrome.runtime.restart() 方法。

requestUpdateCheck()

browser.runtime.requestUpdateCheck(): Promise<object>

要求立即檢查這個應用程式/擴充功能是否有更新。

重要事項：大多數擴充功能/應用程式不應使用這個方法，因為 Chrome 每隔幾小時就會自動檢查，而且您可以監聽 runtime.onUpdateAvailable 事件，不必呼叫 requestUpdateCheck。

這個方法只適合在極少數情況下呼叫，例如擴充功能與後端服務通訊，而後端服務判定用戶端擴充功能版本過舊，您想提示使用者更新。requestUpdateCheck 的其他多數用途 (例如根據重複計時器無條件呼叫)，可能只會浪費用戶端、網路和伺服器資源。

注意：使用回呼呼叫時，這個函式不會傳回物件，而是將這兩個屬性做為個別引數傳回給回呼。

傳回

• Promise<object>

  Chrome 109+ Chrome 148 起為 browser.*

restart()

browser.runtime.restart(): void

在 Kiosk 模式下執行應用程式時，重新啟動 ChromeOS 裝置。否則，系統不會執行任何操作。

restartAfterDelay()

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

browser.runtime.restartAfterDelay(
  seconds: number,
): Promise<void>

在指定秒數後，當應用程式以 Kiosk 模式執行時，重新啟動 ChromeOS 裝置。如果在時間結束前再次呼叫，重新啟動作業就會延遲。如果呼叫時的值為 -1，系統會取消重新啟動。在非 Kiosk 模式下，這項操作不會執行任何動作。只有第一個叫用這個 API 的擴充功能，才能重複呼叫。

參數

• 秒

  數字

  重新啟動裝置前的等待時間 (以秒為單位)，或輸入 -1 取消排定的重新啟動作業。

傳回

• 承諾<void>

  Chrome 99 以上版本 瀏覽器 (自 Chrome 148 起)

  在重新排定重新啟動要求時，會解析的 Promise。

sendMessage()

browser.runtime.sendMessage(
  extensionId?: string,
  message: any,
  options?: object,
): Promise<any>

將單一訊息傳送至擴充功能或其他擴充功能/應用程式中的事件監聽器。與 runtime.connect 類似，但只會傳送單一訊息，並可選擇是否回覆。如果傳送至擴充功能，系統會在擴充功能的每個頁框 (傳送者的頁框除外) 觸發 runtime.onMessage 事件，如果是其他擴充功能，則會觸發 runtime.onMessageExternal。請注意，擴充功能無法使用這個方法傳送訊息給內容指令碼。如要將訊息傳送至內容指令碼，請使用 tabs.sendMessage。

參數

• extensionId

  字串 選填

  要接收訊息的擴充功能 ID。如省略，訊息會傳送至您自己的擴充功能/應用程式。如要從網頁傳送網頁訊息，則必須提供。

• 訊息

  任何

  要傳送的訊息。這則訊息應為可轉換成 JSON 的物件。

• 選項

  物件 選填

  • includeTlsChannelId

    布林值 選填

    是否要將 TLS 管道 ID 傳遞至 onMessageExternal，用於監聽連線事件的程序。

傳回

• Promise<any>

  Chrome 99 以上版本 瀏覽器 (自 Chrome 148 起)

  Chrome 99 為擴充功能環境新增了 Promise 支援。從網頁與擴充功能通訊時，Chrome 118 起支援 Promise。

sendNativeMessage()

browser.runtime.sendNativeMessage(
  application: string,
  message: object,
): Promise<any>

傳送單一訊息至原生應用程式。這個方法需要 "nativeMessaging" 權限。

參數

• 調度應用程式資源

  字串

  內建訊息傳遞主機的名稱或目標詳細資料。

• 訊息

  物件

  要傳遞至內建訊息傳遞主機的訊息。

傳回

• Promise<any>

  Chrome 99 以上版本 瀏覽器 (自 Chrome 148 起)

setUninstallURL()

browser.runtime.setUninstallURL(
  url: string,
): Promise<void>

設定解除安裝時要造訪的網址。這項功能可用於清理伺服器端資料、進行分析及實施問卷調查。最多 1023 個字元。

參數

• 網址

  字串

  解除安裝擴充功能後要開啟的網址。這個網址必須採用 http: 或 https: 配置。如果設為空白字串，就不會在解除安裝時開啟新分頁。

傳回

• 承諾<void>

  Chrome 99 以上版本 瀏覽器 (自 Chrome 148 起)

  設定解除安裝網址時解析的 Promise。如果提供的網址無效，系統會拒絕承諾。

事件

onBrowserUpdateAvailable

已淘汰

browser.runtime.onBrowserUpdateAvailable.addListener(
  callback: function,
)

請使用 runtime.onRestartRequired。

Chrome 有可用的更新，但需要重新啟動瀏覽器才能安裝時，就會觸發這個事件。

參數

• callback

  函式

  callback 參數如下：

  () => void

onConnect

browser.runtime.onConnect.addListener(
  callback: function,
)

當連線來自擴充功能程序或內容指令碼 (由 runtime.connect 建立) 時，就會觸發這個事件。

參數

• callback

  函式

  callback 參數如下：

  (port: Port) => void

  • 通訊埠

    通訊埠

onConnectExternal

browser.runtime.onConnectExternal.addListener(
  callback: function,
)

當另一個擴充功能 (透過 runtime.connect) 或可從外部連線的網站建立連線時，就會觸發這個事件。

參數

• callback

  函式

  callback 參數如下：

  (port: Port) => void

  • 通訊埠

    通訊埠

onConnectNative

Chrome 76 以上版本 瀏覽器 (自 Chrome 148 起)

browser.runtime.onConnectNative.addListener(
  callback: function,
)

從原生應用程式建立連線時觸發。這項事件需要 "nativeMessaging" 權限。僅適用於 ChromeOS。

參數

• callback

  函式

  callback 參數如下：

  (port: Port) => void

  • 通訊埠

    通訊埠

onEnabled

Chrome 155 以上版本

browser.runtime.onEnabled.addListener(
  callback: function,
)

當擴充功能從停用狀態變更為啟用狀態時，系統會觸發這個事件。

參數

• callback

  函式

  callback 參數如下：

  () => void

onExtensionLoaded

Chrome 157 以上版本

browser.runtime.onExtensionLoaded.addListener(
  callback: function,
)

擴充功能新增至使用中擴充功能組合時，系統會觸發這個事件。這可能發生在多種情況下：首次安裝擴充功能、更新至新版本、停用後重新啟用、重新載入、在瀏覽器啟動時載入，或在瀏覽器更新至新版本時載入。

參數

• callback

  函式

  callback 參數如下：

  (details: ExtensionLoadDetails) => void

  • 詳細資料

    ExtensionLoadDetails

onInstalled

browser.runtime.onInstalled.addListener(
  callback: function,
)

在擴充功能首次安裝、更新至新版本，以及 Chrome 更新至新版本時觸發。

參數

• callback

  函式

  callback 參數如下：

  (details: object) => void

  • 詳細資料

    物件

    • id

      字串 選填

      指出已更新的匯入共用模組擴充功能 ID。只有在「reason」為「shared_module_update」時，才會顯示這個欄位。

    • previousVersion

      字串 選填

      指出剛更新的擴充功能先前版本。只有在「reason」為「update」時，才會顯示這個欄位。

    • reason

      OnInstalledReason

      調度這項事件的原因。

onMessage

browser.runtime.onMessage.addListener(
  callback: function,
)

從 runtime.sendMessage 或 tabs.sendMessage 傳送訊息時觸發。

參數

• callback

  函式

  callback 參數如下：

  (message: any, sender: MessageSender, sendResponse: function) => boolean | Promise<any> | undefined

  • 訊息

    任何

  • sender

    MessageSender

  • sendResponse

    函式

    sendResponse 參數如下：

    (response?: any) => void

    • 回應

      任意 選填

      要傳回給訊息傳送者的回應。

  • returns

    boolean | Promise<any> | undefined

onMessageExternal

browser.runtime.onMessageExternal.addListener(
  callback: function,
)

當其他擴充功能 (透過 runtime.sendMessage) 傳送訊息時觸發。無法在內容指令碼中使用。

參數

• callback

  函式

  callback 參數如下：

  (message: any, sender: MessageSender, sendResponse: function) => boolean | Promise<any> | undefined

  • 訊息

    任何

  • sender

    MessageSender

  • sendResponse

    函式

    sendResponse 參數如下：

    (response?: any) => void

    • 回應

      任意 選填

      要傳回給訊息傳送者的回應。

  • returns

    boolean | Promise<any> | undefined

onRestartRequired

browser.runtime.onRestartRequired.addListener(
  callback: function,
)

當應用程式或執行應用程式的裝置需要重新啟動時，系統會觸發這個事件。應用程式應盡快關閉所有視窗，以便重新啟動。如果應用程式未採取任何行動，系統會在 24 小時寬限期過後強制重新啟動。目前，這個事件只會針對 ChromeOS 資訊站應用程式觸發。

參數

• callback

  函式

  callback 參數如下：

  (reason: OnRestartRequiredReason) => void

  • reason

    OnRestartRequiredReason

onStartup

browser.runtime.onStartup.addListener(
  callback: function,
)

在已安裝這個擴充功能的設定檔首次啟動時觸發。即使這項擴充功能在「分割」無痕模式下運作，系統也不會在無痕設定檔啟動時觸發這個事件。

參數

• callback

  函式

  callback 參數如下：

  () => void

onSuspend

browser.runtime.onSuspend.addListener(
  callback: function,
)

在事件頁面卸載前傳送。讓擴充功能有機會進行清理。請注意，由於網頁正在卸載，因此無法保證在處理這個事件時啟動的任何非同步作業都能完成。如果事件頁面在卸載前有更多活動，系統會傳送 onSuspendCanceled 事件，且不會卸載頁面。

參數

• callback

  函式

  callback 參數如下：

  () => void

onSuspendCanceled

browser.runtime.onSuspendCanceled.addListener(
  callback: function,
)

在 onSuspend 之後傳送，表示應用程式不會卸載。

參數

• callback

  函式

  callback 參數如下：

  () => void

onUpdateAvailable

browser.runtime.onUpdateAvailable.addListener(
  callback: function,
)

有可用更新，但因應用程式正在執行而未立即安裝時，就會觸發這個事件。如果您不採取任何行動，系統會在下次卸載背景頁面時安裝更新。如要盡快安裝，可以明確呼叫 chrome.runtime.reload()。如果擴充功能使用永久背景頁面，背景頁面當然不會卸載，因此除非您手動呼叫 chrome.runtime.reload() 來回應此事件，否則系統要到下次 Chrome 重新啟動時才會安裝更新。如果沒有處理常式監聽這個事件，且擴充功能有永久背景頁面，則會像呼叫 chrome.runtime.reload() 來回應這個事件一樣。

參數

• callback

  函式

  callback 參數如下：

  (details: object) => void

  • 詳細資料

    物件

    • 版本

      字串

      可用更新的版本號碼。

onUserScriptConnect

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

browser.runtime.onUserScriptConnect.addListener(
  callback: function,
)

當這個擴充功能的使用者指令碼建立連線時，就會觸發這個事件。

參數

• callback

  函式

  callback 參數如下：

  (port: Port) => void

  • 通訊埠

    通訊埠

onUserScriptMessage

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

browser.runtime.onUserScriptMessage.addListener(
  callback: function,
)

當與相同擴充功能相關聯的使用者指令碼傳送訊息時，就會觸發這個事件。

參數

• callback

  函式

  callback 參數如下：

  (message: any, sender: MessageSender, sendResponse: function) => boolean | undefined

  • 訊息

    任何

  • sender

    MessageSender

  • sendResponse

    函式

    sendResponse 參數如下：

    (response?: any) => void

    • 回應

      任意 選填

      要傳回給訊息傳送者的回應。

  • returns

    boolean | undefined