chrome.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，且主要用於支援資訊站實作。 這個類別的方法包括 restart() 和 restartAfterDelay()。

未封裝的擴充功能行為

當「未封裝」擴充功能重新載入時，系統會將其視為更新。這表示 chrome.runtime.onInstalled 事件將會觸發，原因為 "update"。這包括使用 chrome.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 = chrome.runtime.getURL('logo.png');
  document.body.append(img);
}

將資料從內容指令碼傳送至服務工作站

擴充功能的內容指令碼往往需要擴充功能的其他部分 (例如服務工作站) 管理的資料。與開啟同一個網頁的兩個瀏覽器視窗非常相似，這兩種結構定義無法直接存取彼此的值。因此，擴充功能可以使用訊息傳遞功能協調這些不同情境。

在本例中，內容指令碼需要擴充功能 Service Worker 中的部分資料，才能初始化其 UI。為了取得這項資料，它會將開發人員定義的 get-user-data 訊息傳送至服務工作站，然後以使用者資訊的副本回應。

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);
});

service-worker.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');
  }
});

示例

如需更多執行階段 API 範例，請參閱Manifest V3 - 網頁可存取資源示範。

類型

ContextFilter

Chrome 114 以上版本

用於比對特定擴充功能內容的篩選器。相符內容必須與所有指定的篩選器相符；如未指定任何篩選器，則會與所有可用的背景資訊相符。因此，「{}」的篩選器會比對所有可用的背景資訊。

屬性

• contextIds

  string[] 選填

• contextTypes

  ContextType[] 選用

• documentIds

  string[] 選填

• documentOrigins

  string[] 選填

• documentUrls

  string[] 選填

• frameIds

  number[] 選填

• 無痕模式

  布林值 (選用)

• tabIds

  number[] 選填

• windowIds

  number[] 選填

ContextType

Chrome 114 以上版本

列舉

"TAB"
將結構定義類型指定為分頁

"POPUP"
將結構定義類型指定為擴充功能彈出式視窗

"BACKGROUND"
將結構定義類型指定為 Service Worker。

"OFFSCREEN_DOCUMENT"
將結構定義類型指定為畫面外的文件。

"SIDE_PANEL"
將結構定義類型指定為側邊面板。

ExtensionContext

Chrome 114 以上版本

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

屬性

• contextId

  字串

  情境的專屬 ID

• contextType

  ContextType

  對應的背景資訊類型。

• documentId

  字串 選用

  與這個結構定義相關聯的文件的 UUID；如果這個結構定義不在文件中，則為「未定義」。

• documentOrigin

  字串 選用

  與這個結構定義相關聯的文件來源；如果結構定義不在文件中，則為未定義。

• documentUrl

  字串 選用

  與這個結構定義相關聯的文件網址；如果結構定義不在文件中，則為未定義。

• frameId

  號碼

  此結構定義的影格 ID；如果這個內容未在頁框中代管，則為 -1。

• 無痕模式

  boolean

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

• tabId

  號碼

  此內容的分頁 ID；如果這項內容並非由分頁代管，則為 -1。

• windowId

  號碼

  此結構定義的視窗 ID；如果這個內容未在視窗中代管，則為 -1。

MessageSender

這個物件包含傳送訊息或要求的指令碼內容相關資訊。

屬性

• documentId

  字串 選用

  Chrome 106 以上版本

  開啟連線的文件 UUID。

• documentLifecycle

  字串 選用

  Chrome 106 以上版本

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

• frameId

  數字 選填

  開啟連結的框架。0 代表頂層頁框，對子頁框而言為正。只有在已設定 tab 時，才能設定這個屬性。

• id

  字串 選用

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

• nativeApplication

  字串 選用

  Chrome 74 以上版本

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

• 發跡地

  字串 選用

  Chrome 80 以上版本

  開啟連線的網頁或頁框來源。這個值可能與網址屬性不同 (例如 about:blank)，也可能是不透明 (例如沙箱 iframe)。如果我們無法立即從網址判斷來源是否可信任，這個方法就能派上用場。

• 分頁

  Tab 選用

  開啟連線的 tabs.Tab (如果有的話)。這項屬性「只有」在透過分頁 (包括內容指令碼) 開啟時才會顯示，而且「只有」接收器為擴充功能，而非應用程式。

• tlsChannelId

  字串 選用

  開啟連線的網頁或頁框的 TLS 頻道 ID (如果擴充功能要求的話，以及如果有)。

• 網址

  字串 選用

  開啟連線的網頁或頁框網址。如果寄件者位於 iframe 中，則會顯示 iframe 的網址，而非代管該檔案的網頁網址。

OnInstalledReason

Chrome 44 以上版本

傳送這個事件的原因。

列舉

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

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

"chrome_update"
指出 Chrome 更新的事件原因。

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

OnRestartRequiredReason

Chrome 44 以上版本

傳送事件的原因。由於應用程式已更新為新版本，因此需要重新啟動時，系統會使用「app_update」。由於瀏覽器/OS 已更新到較新版本，因此需要重新啟動時，系統會使用「os_update」。如果系統執行的運作時間超過企業政策中設定的運作時間上限，系統就會使用「週期」。

列舉

"app_update"
指出應用程式更新內容的事件原因。

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

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

PlatformArch

Chrome 44 以上版本

機器的處理器架構。

列舉

"arm"
將程序器架構指定為實驗組。

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

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

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

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

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

PlatformInfo

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

屬性

• 拱形物

  PlatformArch

  機器的處理器架構。

• nacl_arch

  PlatformNaclArch

  原生用戶端架構。這可能與某些平台的架構不同。

• os

  PlatformOs

  Chrome 執行的作業系統。

PlatformNaclArch

Chrome 44 以上版本

原生用戶端架構。這可能與某些平台的架構不同。

列舉

"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 作業系統。

"fuchsia"
指定 Fuchsia 作業系統。

Port

允許與其他網頁雙向通訊的物件。詳情請參閱「長期連線」。

屬性

• 名稱

  字串

  通訊埠名稱，如 runtime.connect 呼叫中指定的名稱。

• onDisconnect

  事件<functionvoidvoid>

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

  onDisconnect.addListener 函式如下所示：

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

  • 回呼

    功能

    callback 參數如下所示：

    (port: Port)=>void

    • 通訊埠

      連接埠

• onMessage

  事件<functionvoidvoid>

  通訊埠的另一端呼叫 postMessage 時，會引發此事件。

  onMessage.addListener 函式如下所示：

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

  • 回呼

    功能

    callback 參數如下所示：

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

    • 訊息

      不限

    • 通訊埠

      連接埠

• 寄件者

  MessageSender 選用

  這項屬性只會顯示在傳遞至 onConnect / onConnectExternal / onConnectNative 事件監聽器的通訊埠上。

• 取消連結

  void

  立即拔除連接埠。在已中斷連線的通訊埠上呼叫 disconnect() 不會產生任何效果。如果通訊埠中斷連線，系統就不會將新事件分派到這個通訊埠。

  disconnect 函式如下所示：

  ()=> {...}

• postMessage

  void

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

  postMessage 函式如下所示：

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

  • 訊息

    不限

    Chrome 52 以上版本

    要傳送的訊息。這個物件應為 JSON 可建立狀態。

RequestUpdateCheckStatus

Chrome 44 以上版本

更新檢查的結果。

列舉

「節流"」
用於表示狀態檢查已經過節流。如果系統在短時間內反覆檢查，就會發生這種情況。

"no_update"
表示沒有可安裝的更新。

"update_available"
表示有可安裝的更新。

屬性

id

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

類型

字串

lastError

如果呼叫 API 函式失敗，系統會顯示錯誤訊息；否則會填入錯誤訊息。這只會在該函式的回呼範圍內定義。如果產生錯誤，但回呼中並未存取 runtime.lastError，系統會在主控台中記錄一項訊息，列出產生錯誤的 API 函式。傳回承諾的 API 函式不會設定這個屬性。

類型

物件

屬性

• 訊息

  字串 選用

  錯誤發生詳情。

方法

connect()

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

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

參數

• extensionId

  字串 選用

  要連結的擴充功能 ID。如果省略，系統會嘗試使用您自己的擴充功能連線。如果從網路訊息網頁傳送訊息，則為必要欄位。

• connectInfo

  物件選用

  • includeTlsChannelId

    布林值 (選用)

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

  • 名稱

    字串 選用

    將會傳入 onConnect，以便監聽連線事件的程序。

傳回

• 連接埠

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

connectNative()

chrome.runtime.connectNative(
  application: string,
)

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

參數

• 調度應用程式資源

  字串

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

傳回

• 連接埠

  可透過應用程式收發訊息的通訊埠

getBackgroundPage()

Promise (僅限前景)

chrome.runtime.getBackgroundPage(
  callback?: function,
)

針對目前擴充功能/應用程式內部執行的背景網頁擷取 JavaScript「視窗」物件。如果背景網頁是事件網頁，系統會先確保載入網頁，再呼叫回呼。如果沒有背景頁面，便會設定錯誤。

參數

• 回呼

  函式選用

  callback 參數如下所示：

  (backgroundPage?: Window)=>void

  • backgroundPage

    視窗 選用

    背景網頁的 JavaScript「視窗」物件。

傳回

• 承諾<視窗|未定義>

  Chrome 99 以上版本

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

getContexts()

Promise Chrome 116 以上版本 MV3 以上版本

chrome.runtime.getContexts(
  filter: ContextFilter,
  callback?: function,
)

擷取與這個擴充功能相關聯的有效結構定義資訊

參數

• 過濾器

  ContextFilter

  用於尋找相符背景資訊的篩選器。如果結構定義與篩選器中的所有指定欄位相符，就會視為相符。篩選器中的任何未指定欄位都會比對所有背景資訊。

• 回呼

  函式選用

  callback 參數如下所示：

  (contexts: ExtensionContext[])=>void

  • 情境

    ExtensionContext[]

    相符的背景資訊 (如果有的話)。

傳回

• Promise<ExtensionContext[]>

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

getManifest()

chrome.runtime.getManifest()

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

傳回

• 物件

  資訊清單詳細資料。

getPackageDirectoryEntry()

Promise (僅限前景)

chrome.runtime.getPackageDirectoryEntry(
  callback?: function,
)

傳回套件目錄的 DirectoryEntry。

參數

• 回呼

  函式選用

  callback 參數如下所示：

  (directoryEntry: DirectoryEntry)=>void

  • directoryEntry

    DirectoryEntry

傳回

• Promise<DirectoryEntry>

  Chrome 122 以上版本

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

getPlatformInfo()

Promise

chrome.runtime.getPlatformInfo(
  callback?: function,
)

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

參數

• 回呼

  函式選用

  callback 參數如下所示：

  (platformInfo: PlatformInfo)=>void

  • platformInfo

    PlatformInfo

傳回

• Promise<PlatformInfo>

  Chrome 99 以上版本

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

getURL()

chrome.runtime.getURL(
  path: string,
)

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

參數

• path

  字串

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

傳回

• 字串

  資源的完整網址。

openOptionsPage()

Promise

chrome.runtime.openOptionsPage(
  callback?: function,
)

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

該功能的確切行為可能取決於資訊清單的 [options_ui](https://developer.chrome.com/docs/extensions/develop/ui/options-page#embedded_options) 或 [options_page](https://developer.chrome.com/docs/extensions/develop/ui/options-page#full_page) 鍵，或 Chrome 當下支援的項目。舉例來說，使用者可能會在新分頁中開啟網頁、在 chrome://extensions 中、應用程式內，或者只是開啟開啟的選項網頁。而且絕不會導致呼叫者頁面重新載入。

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

參數

• 回呼

  函式選用

  callback 參數如下所示：

  ()=>void

傳回

• Promise<void>

  Chrome 99 以上版本

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

reload()

chrome.runtime.reload()

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

requestUpdateCheck()

Promise

chrome.runtime.requestUpdateCheck(
  callback?: function,
)

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

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

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

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

參數

• 回呼

  函式選用

  callback 參數如下所示：

  (result: object)=>void

  • 結果

    物件

    Chrome 109 以上版本

    保留更新檢查狀態的 RequestUpdateCheckResult 物件和所有結果的詳細資訊 (如有更新)

    • status

      RequestUpdateCheckStatus

      更新檢查的結果。

    • version

      字串 選用

      如果有可用的更新，這將包含可用的更新版本。

傳回

• Promise<object>

  Chrome 109 以上版本

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

restart()

chrome.runtime.restart()

當應用程式以資訊站模式執行時，重新啟動 ChromeOS 裝置。否則不是免人工管理。

restartAfterDelay()

Promise Chrome 53 以上版本

chrome.runtime.restartAfterDelay(
  seconds: number,
  callback?: function,
)

在指定秒數後，當應用程式以資訊站模式執行時，重新啟動 ChromeOS 裝置。如果在時間結束前再次呼叫，裝置將延遲重新啟動。如果呼叫的值為 -1，系統會取消重新啟動。這是非 Kiosk 模式的免人工管理。只有第一個擴充功能可以重複呼叫這個 API，藉此叫用這個 API。

參數

• 秒

  號碼

  等待裝置 (以秒為單位) 再重新啟動，或按 -1 取消排定的重新啟動作業。

• 回呼

  函式選用

  callback 參數如下所示：

  ()=>void

傳回

• Promise<void>

  Chrome 99 以上版本

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

sendMessage()

Promise

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

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

參數

• extensionId

  字串 選用

  訊息接收對象的擴充功能 ID。如果省略，系統會將訊息傳送到您的擴充功能/應用程式。如要透過網頁傳送訊息，則必須提供網路訊息。

• 訊息

  不限

  要傳送的訊息。這則訊息應為 JSON 可匯入的物件。

• 選項

  物件選用

  • includeTlsChannelId

    布林值 (選用)

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

• 回呼

  函式選用

  Chrome 99 以上版本

  callback 參數如下所示：

  (response: any)=>void

  • 則回應

    不限

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

傳回

• 承諾<任何>

  Chrome 99 以上版本

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

sendNativeMessage()

Promise

chrome.runtime.sendNativeMessage(
  application: string,
  message: object,
  callback?: function,
)

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

參數

• 調度應用程式資源

  字串

  內建訊息傳遞主機的名稱。

• 訊息

  物件

  將傳遞給內建訊息傳遞主機的訊息。

• 回呼

  函式選用

  Chrome 99 以上版本

  callback 參數如下所示：

  (response: any)=>void

  • 則回應

    不限

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

傳回

• 承諾<任何>

  Chrome 99 以上版本

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

setUninstallURL()

Promise

chrome.runtime.setUninstallURL(
  url: string,
  callback?: function,
)

設定解除安裝時要造訪的網址。可用來清除伺服器端資料、進行分析及導入問卷調查。長度上限為 1023 個半形字元。

參數

• 網址

  字串

  解除安裝擴充功能後要開啟的網址。此網址必須具有 http: 或 https: 配置。設定空白字串，不要在解除安裝時開啟新分頁。

• 回呼

  函式選用

  Chrome 45 以上版本

  callback 參數如下所示：

  ()=>void

傳回

• Promise<void>

  Chrome 99 以上版本

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

活動

onBrowserUpdateAvailable

已淘汰

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

請使用 runtime.onRestartRequired。

有可用的 Chrome 更新時觸發，但因為需要重新啟動瀏覽器，而未立即安裝。

參數

• 回呼

  功能

  callback 參數如下所示：

  ()=>void

onConnect

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

透過擴充功能程序或內容指令碼 (由 runtime.connect 執行) 建立連線時觸發。

參數

• 回呼

  功能

  callback 參數如下所示：

  (port: Port)=>void

  • 通訊埠

    連接埠

onConnectExternal

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

透過其他擴充功能 (由 runtime.connect) 或外部連線網站建立連線時觸發。

參數

• 回呼

  功能

  callback 參數如下所示：

  (port: Port)=>void

  • 通訊埠

    連接埠

onConnectNative

Chrome 76 以上版本

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

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

參數

• 回呼

  功能

  callback 參數如下所示：

  (port: Port)=>void

  • 通訊埠

    連接埠

onInstalled

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

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

參數

• 回呼

  功能

  callback 參數如下所示：

  (details: object)=>void

  • 詳細資料

    物件

    • id

      字串 選用

      指出所更新共用模組擴充功能的 ID。只有在「reason」是「shared_module_update」時，才會顯示這個資料欄。

    • previousVersion

      字串 選用

      指出剛更新的舊版擴充功能。只有在「reason」為「update」時才會顯示這個狀態。

    • 原因

      OnInstalledReason

      傳送這個事件的原因。

onMessage

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

透過擴充功能程序 (由 runtime.sendMessage) 或內容指令碼 (由 tabs.sendMessage 傳送) 傳送訊息時觸發。

參數

• 回呼

  功能

  callback 參數如下所示：

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

  • 訊息

    不限

  • 寄件者

    MessageSender

  • sendResponse

    功能

    sendResponse 參數如下所示：

    ()=>void

  • returns

    boolean|undefined

onMessageExternal

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

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

參數

• 回呼

  功能

  callback 參數如下所示：

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

  • 訊息

    不限

  • 寄件者

    MessageSender

  • sendResponse

    功能

    sendResponse 參數如下所示：

    ()=>void

  • returns

    boolean|undefined

onRestartRequired

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

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

參數

• 回呼

  功能

  callback 參數如下所示：

  (reason: OnRestartRequiredReason)=>void

  • 原因

    OnRestartRequiredReason

onStartup

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

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

參數

• 回呼

  功能

  callback 參數如下所示：

  ()=>void

onSuspend

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

在卸載前傳送到活動頁面。這樣擴充功能就能進行一些清除作業。請注意，由於網頁正在卸載，因此處理此事件時啟動的任何非同步作業，都不一定能完成。如果活動頁面在卸載前發生更多活動，系統會傳送暫停的「Suspended」事件，而且該頁面不會卸載。

參數

• 回呼

  功能

  callback 參數如下所示：

  ()=>void

onSuspendCanceled

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

在暫停後傳送，表示應用程式將不會卸載。

參數

• 回呼

  功能

  callback 參數如下所示：

  ()=>void

onUpdateAvailable

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

有可用的更新時觸發，但因應用程式目前正在執行而未立即安裝。如果你不採取任何行動，系統就會在背景網頁卸載時安裝更新；如果想更快完成安裝，你可以明確呼叫 chrome.runtime.reload()。如果擴充功能使用永久背景頁面，則課程背景網頁永遠不會卸載，因此除非你手動呼叫 chrome.runtime.reload() 回應這項事件，否則更新作業必須等到 Chrome 重新啟動後才會安裝。如果沒有任何處理常式監聽這個事件，且你的擴充功能具有永久性背景頁面，系統就會假設該事件為呼叫 chrome.runtime.reload() 來回應這個事件。

參數

• 回呼

  功能

  callback 參數如下所示：

  (details: object)=>void

  • 詳細資料

    物件

    • version

      字串

      可用更新的版本編號。

onUserScriptConnect

Chrome 115 以上版本 MV3 以上版本

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

透過這個擴充功能的使用者指令碼建立連線時觸發。

參數

• 回呼

  功能

  callback 參數如下所示：

  (port: Port)=>void

  • 通訊埠

    連接埠

onUserScriptMessage

Chrome 115 以上版本 MV3 以上版本

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

透過與相同擴充功能相關聯的使用者指令碼傳送訊息時觸發。

參數

• 回呼

  功能

  callback 參數如下所示：

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

  • 訊息

    不限

  • 寄件者

    MessageSender

  • sendResponse

    功能

    sendResponse 參數如下所示：

    ()=>void

  • returns

    boolean|undefined