chrome.runtime

refresh date: 2026-09-25 robots: noindex

說明

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

總覽

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

訊息傳遞

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

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

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

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

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

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

輔助公用程式

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

Kiosk 模式公用程式

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

權限

Runtime API 的大多數方法都不需要任何權限，但 sendNativeMessage 和 connectNative 需要 nativeMessaging 權限。

資訊清單

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

manifest.json:

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

用途

在網頁中新增圖片

如要讓網頁存取其他網域託管的素材資源，必須指定資源的完整網址 (例如 <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 = chrome.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
chrome.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);
});

background.js:

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

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

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

擴充功能範例

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

類型

ContextFilter

Chrome 114 以上版本

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

屬性

• contextIds

  string[] 選填

• contextTypes

  ContextType[] 選填

• documentIds

  string[] 選填

• documentOrigins

  string[] 選填

• documentUrls

  string[] 選填

• frameIds

  number[] 選填

• incognito

  布林值 選填

• tabIds

  number[] 選填

• windowIds

  number[] 選填

ContextType

Chrome 114 以上版本

列舉

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

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

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

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

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

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

ExtensionContext

Chrome 114 以上版本

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

屬性

• 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 以上版本

  開啟連線的文件 UUID。

• documentLifecycle

  字串 選填

  Chrome 106 以上版本

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

• frameId

  數字 選填

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

• id

  字串 選填

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

• nativeApplication

  字串 選填

  Chrome 74 以上版本

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

• origin

  字串 選填

  Chrome 80 以上版本

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

• Tab 鍵

  分頁 選填

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

• tlsChannelId

  字串 選填

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

• 網址

  字串 選填

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

OnInstalledReason

Chrome 44 以上版本

調度這項事件的原因。

列舉

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

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

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

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

OnLoadedReason

Chrome 157 以上版本

調度這項事件的原因。

列舉

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

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

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

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

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

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

OnRestartRequiredReason

Chrome 44 以上版本

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

列舉

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

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

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

PlatformArch

Chrome 44 以上版本

機器的處理器架構。

列舉

"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 149 起淘汰

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

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

列舉

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

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

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

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

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

PlatformOs

Chrome 44 以上版本

執行 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 以上版本

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

RequestUpdateCheckStatus

Chrome 44 以上版本

更新檢查結果。

列舉

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

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

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

屬性

id

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

類型

字串

lastError

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

類型

物件

屬性

• 訊息

  字串 選填

  發生錯誤的詳細資料。

方法

connect()

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

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

參數

• extensionId

  字串 選填

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

• connectInfo

  物件 選填

  • includeTlsChannelId

    布林值 選填

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

  • 名稱

    字串 選填

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

傳回

• 通訊埠

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

connectNative()

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

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

參數

• 調度應用程式資源

  字串

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

傳回

• 通訊埠

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

getBackgroundPage()

Promise 僅限前景 自 Chrome 133 起淘汰

chrome.runtime.getBackgroundPage(
  callback?: function,
): Promise<Window | undefined>

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

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

參數

• callback

  函式 選填

  callback 參數如下：

  (backgroundPage?: Window) => void

  • backgroundPage

    視窗 選填

    背景網頁的 JavaScript「window」物件。

傳回

• Promise<Window | undefined>

  Chrome 99 以上版本

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

getManifest()

chrome.runtime.getManifest(): object

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

傳回

• 物件

  資訊清單詳細資料。

getPackageDirectoryEntry()

Promise 僅限前景

chrome.runtime.getPackageDirectoryEntry(
  callback?: function,
): Promise<DirectoryEntry>

傳回套件目錄的 DirectoryEntry。

參數

• callback

  函式 選填

  callback 參數如下：

  (directoryEntry: DirectoryEntry) => void

  • directoryEntry

    DirectoryEntry

傳回

• Promise<DirectoryEntry>

  Chrome 122 以上版本

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

getPlatformInfo()

Promise

chrome.runtime.getPlatformInfo(
  callback?: function,
): Promise<PlatformInfo>

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

參數

• callback

  函式 選填

  callback 參數如下：

  (platformInfo: PlatformInfo) => void

  • platformInfo

    PlatformInfo

傳回

• Promise<PlatformInfo>

  Chrome 99 以上版本

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

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

getURL()

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

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

參數

• 路徑

  字串

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

傳回

• 字串

  資源的完整網址。

getVersion()

Chrome 143 以上版本

chrome.runtime.getVersion(): string

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

傳回

• 字串

  擴充功能版本。

openOptionsPage()

Promise

chrome.runtime.openOptionsPage(
  callback?: function,
): Promise<void>

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

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

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

參數

• callback

  函式 選填

  callback 參數如下：

  () => void

傳回

• 承諾<void>

  Chrome 99 以上版本

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

reload()

chrome.runtime.reload(): void

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

requestUpdateCheck()

Promise

chrome.runtime.requestUpdateCheck(
  callback?: function,
): Promise<object>

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

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

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

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

參數

• callback

  函式 選填

  callback 參數如下：

  (result: object) => void

  • 結果

    物件

    Chrome 109 以上版本

    RequestUpdateCheckResult 物件，用於保存更新檢查狀態，以及任何結果詳細資料 (如有可用更新)

    • 狀態

      RequestUpdateCheckStatus

      更新檢查結果。

    • 版本

      字串 選填

      如有可用更新，這裡會顯示可用更新的版本。

傳回

• Promise<object>

  Chrome 109 以上版本

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

restart()

chrome.runtime.restart(): void

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

restartAfterDelay()

Promise Chrome 53 以上版本

chrome.runtime.restartAfterDelay(
  seconds: number,
  callback?: function,
): Promise<void>

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

參數

• 秒

  數字

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

• callback

  函式 選填

  callback 參數如下：

  () => void

傳回

• 承諾<void>

  Chrome 99 以上版本

  重新排定重新啟動要求後，Promise 會解析。

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

sendMessage()

Promise

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

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

參數

• extensionId

  字串 選填

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

• 訊息

  任何

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

• 選項

  物件 選填

  • includeTlsChannelId

    布林值 選填

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

• callback

  函式 選填

  Chrome 99 以上版本

  callback 參數如下：

  (response: any) => void

  • 回應

    任何

    訊息處理常式傳送的 JSON 回應物件。如果連線至擴充功能時發生錯誤，系統會呼叫回呼，但不提供引數，並將 runtime.lastError 設為錯誤訊息。

傳回

• Promise<any>

  Chrome 99 以上版本

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

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

sendNativeMessage()

Promise

chrome.runtime.sendNativeMessage(
  application: string,
  message: object,
  callback?: function,
): Promise<any>

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

參數

• 調度應用程式資源

  字串

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

• 訊息

  物件

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

• callback

  函式 選填

  Chrome 99 以上版本

  callback 參數如下：

  (response: any) => void

  • 回應

    任何

    內建訊息傳遞主機傳送的回應訊息。如果連線至內建訊息傳遞主機時發生錯誤，系統會呼叫回呼，但不提供引數，並將 runtime.lastError 設為錯誤訊息。

傳回

• Promise<any>

  Chrome 99 以上版本

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

setUninstallURL()

Promise

chrome.runtime.setUninstallURL(
  url: string,
  callback?: function,
): Promise<void>

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

參數

• 網址

  字串

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

• callback

  函式 選填

  Chrome 45 以上版本

  callback 參數如下：

  () => void

傳回

• 承諾<void>

  Chrome 99 以上版本

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

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

事件

onBrowserUpdateAvailable

已淘汰

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

請使用 runtime.onRestartRequired。

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

參數

• callback

  函式

  callback 參數如下：

  () => void

onConnect

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

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

參數

• callback

  函式

  callback 參數如下：

  (port: Port) => void

  • 通訊埠

    通訊埠

onConnectExternal

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

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

參數

• callback

  函式

  callback 參數如下：

  (port: Port) => void

  • 通訊埠

    通訊埠

onConnectNative

Chrome 76 以上版本

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

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

參數

• callback

  函式

  callback 參數如下：

  (port: Port) => void

  • 通訊埠

    通訊埠

onEnabled

Chrome 155 以上版本

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

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

參數

• callback

  函式

  callback 參數如下：

  () => void

onExtensionLoaded

Chrome 157 以上版本

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

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

參數

• callback

  函式

  callback 參數如下：

  (details: ExtensionLoadDetails) => void

  • 詳細資料

    ExtensionLoadDetails

onInstalled

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

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

參數

• callback

  函式

  callback 參數如下：

  (details: object) => void

  • 詳細資料

    物件

    • id

      字串 選填

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

    • previousVersion

      字串 選填

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

    • reason

      OnInstalledReason

      調度這項事件的原因。

onMessage

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

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

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

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

參數

• callback

  函式

  callback 參數如下：

  (reason: OnRestartRequiredReason) => void

  • reason

    OnRestartRequiredReason

onStartup

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

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

參數

• callback

  函式

  callback 參數如下：

  () => void

onSuspend

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

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

參數

• callback

  函式

  callback 參數如下：

  () => void

onSuspendCanceled

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

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

參數

• callback

  函式

  callback 參數如下：

  () => void

onUpdateAvailable

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

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

參數

• callback

  函式

  callback 參數如下：

  (details: object) => void

  • 詳細資料

    物件

    • 版本

      字串

      可用更新的版本號碼。