chrome.runtime

說明

使用 chrome.runtime API 擷取服務工作者、傳回資訊清單的詳細資料，以及監聽並回應擴充功能生命週期中的事件。您也可以使用這個 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);
}

將內容指令碼中的資料傳送至服務工作者

擴充功能的內容指令碼通常需要由擴充功能的其他部分 (例如服務工作者) 管理的資料。就像兩個瀏覽器視窗開啟至同一個網頁一樣，這兩個情境無法直接存取彼此的值。相反地，擴充功能可以使用訊息傳遞功能，在這些不同情境中進行協調。

在這個範例中，內容指令碼需要擴充功能的服務工作者提供的部分資料，才能初始化 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 範例，請參閱 資訊清單 V3 - 可透過網頁存取的資源 示範。

類型

ContextFilter

Chrome 114 以上版本

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

屬性

  • contextIds

    string[] 選填

  • contextTypes

    ContextType[] 選填

  • documentIds

    string[] 選填

  • documentOrigins

    string[] 選填

  • documentUrls

    string[] 選填

  • frameIds

    number[] 選填

  • 無痕模式

    boolean 選填

  • tabIds

    number[] 選填

  • windowIds

    number[] 選填

ContextType

Chrome 114 以上版本

列舉

"TAB"
指定上下文類型為分頁

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

"BACKGROUND"
指定內容類型為服務工作者。

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

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

"DEVELOPER_TOOLS"
指定內容類型為開發人員工具。

ExtensionContext

Chrome 114 以上版本

代管擴充功能內容的內容。

屬性

  • contextId

    字串

    這個情境的專屬 ID

  • contextType

    ContextType

    這個值對應的上下文類型。

  • documentId

    string 選填

    與此內容相關聯的文件 UUID，如果此內容並未代管在文件中，則為未定義。

  • documentOrigin

    string 選填

    與這個上下文相關聯的文件來源，如果上下文未在文件中代管，則為 undefined。

  • documentUrl

    string 選填

    與此內容相關聯的文件網址，如果內容未在文件中代管，則為未定義。

  • frameId

    數字

    這個情境的框架 ID，如果這個情境未在框架中代管，則為 -1。

  • 無痕模式

    布林值

    指出內容是否與無痕模式設定檔相關聯。

  • tabId

    數字

    這個情境的分頁 ID，如果這個情境未在分頁中代管，則為 -1。

  • windowId

    數字

    這個情境的視窗 ID，如果這個情境未在視窗中代管，則為 -1。

MessageSender

物件，其中包含傳送訊息或要求的腳本內容相關資訊。

屬性

  • documentId

    string 選填

    Chrome 106 以上版本

    開啟連線的文件 UUID。

  • documentLifecycle

    string 選填

    Chrome 106 以上版本

    建立端口時，開啟連線的文件所處的生命週期。請注意，自建立轉譯後，文件的生命週期狀態可能已變更。

  • frameId

    號碼 選填

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

  • id

    string 選填

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

  • nativeApplication

    string 選填

    Chrome 74 以上版本

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

  • 起源

    string 選填

    Chrome 80 以上版本

    開啟連線的網頁或框架來源。這可能與 url 屬性不同 (例如 about:blank)，也可能不透明 (例如沙箱 iframe)。如果我們無法立即從網址判斷來源是否可信，這項功能就非常實用。

  • 分頁

    分頁 選填

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

  • tlsChannelId

    string 選填

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

  • 網址

    string 選填

    開啟連線的網頁或框架網址。如果寄件者位於 iframe 中，則會是 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"
指定事件原因為作業系統更新。

「定期」
指定事件原因為應用程式的定期重新啟動。

PlatformArch

Chrome 44 以上版本

機器的處理器架構。

列舉

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

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

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

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

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

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

PlatformInfo

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

屬性

  • 機器的處理器架構。

  • nacl_arch

    PlatformNaclArch

    原生用戶端架構。這可能與部分平台上的 arch 不同。

  • Chrome 執行的作業系統。

PlatformNaclArch

Chrome 44 以上版本

原生用戶端架構。這可能與部分平台上的 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 作業系統。

"fuchsia"
指定 Fuchsia 作業系統。

Port

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

屬性

  • 名稱

    字串

    在呼叫 runtime.connect 時指定的通訊埠名稱。

  • onDisconnect

    Event<functionvoidvoid>

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

    onDisconnect.addListener 函式如下所示： 

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

    • 回呼

      函式

      callback 參數如下所示： 

      (port: Port) => void

  • onMessage

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

更新檢查結果。

列舉

"throttled"
指定狀態檢查已受到節流。在短時間內重複檢查後，可能會發生這種情況。

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

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

屬性

id

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

類型

字串

lastError

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

類型

物件

屬性

  • 訊息

    string 選填

    發生錯誤的詳細資料。

方法

connect()

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

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

參數

  • extensionId

    string 選填

    要連結的擴充功能 ID。如果省略，系統會嘗試使用您自己的擴充功能進行連線。如果您要透過網頁傳送網頁訊息，就必須使用這個屬性。

  • connectInfo

    物件 選填

    • includeTlsChannelId

      boolean 選填

      是否會將 TLS 管道 ID 傳遞至 onConnectExternal，以便監聽連線事件的程序。

    • 名稱

      string 選填

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

傳回

  • 可用於傳送及接收訊息的通訊埠。如果擴充功能不存在，系統會觸發端口的 onDisconnect 事件。

connectNative()

chrome.runtime.connectNative(
  application: string,
)

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

參數

  • 調度應用程式資源

    字串

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

傳回

  • 應用程式可透過此端口收發訊息

getBackgroundPage()

Promise 僅限前景 
chrome.runtime.getBackgroundPage(
  callback?: function,
)

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

參數

  • 回呼

    函式 選填

    callback 參數如下所示： 

    (backgroundPage?: Window) => void

    • backgroundPage

      視窗 (選用)

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

傳回

  • Promise<Window | undefined>

    Chrome 99 以上版本

    承諾在資訊清單 3 以上版本中受支援，但回呼則是為了回溯相容性而提供。您無法在同一個函式呼叫中同時使用這兩種方法。承諾會以傳遞至回呼的相同類型解析。

getContexts()

Promise Chrome 116 以上版本 MV3 以上版本 
chrome.runtime.getContexts(
  filter: ContextFilter,
  callback?: function,
)

擷取與此擴充功能相關聯的有效內容

參數

  • 篩選器

    ContextFilter

    用於尋找相符內容的篩選器。如果上下文符合篩選器中所有指定欄位，就會進行比對。篩選器中的任何未指定欄位都會與所有情境相符。

  • 回呼

    函式 選填

    callback 參數如下所示： 

    (contexts: ExtensionContext[]) => void

傳回

  • Promise<ExtensionContext[]>

    承諾在資訊清單 3 以上版本中受支援，但回呼則是為了回溯相容性而提供。您無法在同一個函式呼叫中同時使用這兩種方法。承諾會以傳遞至回呼的相同類型解析。

getManifest()

chrome.runtime.getManifest()

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

傳回

  • 物件

    資訊清單詳細資料。

getPackageDirectoryEntry()

Promise 僅限前景 
chrome.runtime.getPackageDirectoryEntry(
  callback?: function,
)

傳回套件目錄的 DirectoryEntry。

參數

  • 回呼

    函式 選填

    callback 參數如下所示： 

    (directoryEntry: DirectoryEntry) => void

    • directoryEntry

      DirectoryEntry

傳回

  • Promise<DirectoryEntry>

    Chrome 122 以上版本

    承諾在資訊清單 3 以上版本中受支援，但回呼則是為了回溯相容性而提供。您無法在同一個函式呼叫中同時使用這兩種方法。承諾會以傳遞至回呼的相同類型解析。

getPlatformInfo()

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

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

參數

  • 回呼

    函式 選填

    callback 參數如下所示： 

    (platformInfo: PlatformInfo) => void

傳回

  • Promise<PlatformInfo>

    Chrome 99 以上版本

    承諾在資訊清單 3 以上版本中受支援，但回呼則是為了回溯相容性而提供。您無法在同一個函式呼叫中同時使用這兩種方法。承諾會以傳遞至回呼的相同類型解析。

getURL()

chrome.runtime.getURL(
  path: string,
)

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

參數

  • 路徑

    字串

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

傳回

  • 字串

    資源的完整網址。

openOptionsPage()

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

盡可能開啟擴充功能的選項頁面。

具體行為可能取決於資訊清單的 options_ui 或 options_page 鍵，或是 Chrome 當時支援的功能。舉例來說，您可以選擇在新的分頁、chrome://extensions 或應用程式中開啟網頁，也可以只將焦點放在已開啟的選項頁面。不會導致呼叫端網頁重新載入。

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

參數

  • 回呼

    函式 選填

    callback 參數如下所示： 

    () => void

傳回

  • Promise<void>

    Chrome 99 以上版本

    承諾在資訊清單 3 以上版本中受支援，但回呼則是為了回溯相容性而提供。您無法在同一個函式呼叫中同時使用這兩種方法。承諾會以傳遞至回呼的相同類型解析。

reload()

chrome.runtime.reload()

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

requestUpdateCheck()

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

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

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

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

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

參數

  • 回呼

    函式 選填

    callback 參數如下所示： 

    (result: object) => void

    • 結果

      物件

      Chrome 109 以上版本

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

      • 更新檢查結果。

      • 版本

        string 選填

        如果有可用的更新，這個值會包含可用更新的版本。

傳回

  • Promise<object>

    Chrome 109 以上版本

    承諾在資訊清單 3 以上版本中受支援，但回呼則是為了回溯相容性而提供。您無法在同一個函式呼叫中同時使用這兩種方法。承諾會以傳遞至回呼的相同類型解析。

restart()

chrome.runtime.restart()

在應用程式以 Kiosk 模式執行時，重新啟動 ChromeOS 裝置。否則，則為無操作。

restartAfterDelay()

Promise Chrome 53 以上版本 
chrome.runtime.restartAfterDelay(
  seconds: number,
  callback?: function,
)

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

參數

  • 秒

    數字

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

  • 回呼

    函式 選填

    callback 參數如下所示： 

    () => void

傳回

  • Promise<void>

    Chrome 99 以上版本

    承諾在資訊清單 3 以上版本中受支援，但回呼則是為了回溯相容性而提供。您無法在同一個函式呼叫中同時使用這兩種方法。承諾會以傳遞至回呼的相同類型解析。

sendMessage()

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

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

參數

  • extensionId

    string 選填

    要傳送訊息的擴充功能 ID。如果省略，系統會將訊息傳送至您自己的擴充功能/應用程式。如果您要透過網頁傳送網頁訊息，則必須提供此值。

  • 訊息

    不限

    要傳送的訊息。此訊息應為可 JSON 化物件。

  • 選項

    物件 選填

    • includeTlsChannelId

      boolean 選填

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

  • 回呼

    函式 選填

    Chrome 99 以上版本

    callback 參數如下所示： 

    (response: any) => void

    • 回應

      不限

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

傳回

  • Promise<any>

    Chrome 99 以上版本

    承諾在資訊清單 3 以上版本中受支援，但回呼則是為了回溯相容性而提供。您無法在同一個函式呼叫中同時使用這兩種方法。承諾會以傳遞至回呼的相同類型解析。

sendNativeMessage()

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

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

參數

  • 調度應用程式資源

    字串

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

  • 訊息

    物件

    將傳遞至原生訊息主機的訊息。

  • 回呼

    函式 選填

    Chrome 99 以上版本

    callback 參數如下所示： 

    (response: any) => void

    • 回應

      不限

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

傳回

  • Promise<any>

    Chrome 99 以上版本

    承諾在資訊清單 3 以上版本中受支援，但回呼則是為了回溯相容性而提供。您無法在同一個函式呼叫中同時使用這兩種方法。承諾會以傳遞至回呼的相同類型解析。

setUninstallURL()

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

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

參數

  • 網址

    字串

    解除安裝擴充功能後要開啟的網址。此網址必須採用 http: 或 https: 架構。設定空字串，即可在解除安裝時不開啟新分頁。

  • 回呼

    函式 選填

    Chrome 45 以上版本

    callback 參數如下所示： 

    () => void

傳回

  • Promise<void>

    Chrome 99 以上版本

    承諾在資訊清單 3 以上版本中受支援，但回呼則是為了回溯相容性而提供。您無法在同一個函式呼叫中同時使用這兩種方法。承諾會以傳遞至回呼的相同類型解析。

活動

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" 權限。這項功能僅支援 Chrome OS。

參數

  • 回呼

    函式

    callback 參數如下所示： 

    (port: Port) => void

onInstalled

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

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

參數

  • 回呼

    函式

    callback 參數如下所示： 

    (details: object) => void

    • 詳細資料

      物件

      • id

        string 選填

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

      • previousVersion

        string 選填

        指出剛更新的延伸模組舊版本。只有在「reason」為「update」時，才會出現這個值。

      • 觸發事件的理由。

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

      布林值 | 未定義

onMessageExternal

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

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

參數

  • 回呼

    函式

    callback 參數如下所示： 

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

    • 訊息

      不限

    • 寄件者

      MessageSender

    • sendResponse

      函式

      sendResponse 參數如下所示： 

      () => void

    • returns

      布林值 | 未定義

onRestartRequired

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

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

參數

onStartup

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

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

參數

  • 回呼

    函式

    callback 參數如下所示： 

    () => void

onSuspend

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

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

參數

  • 回呼

    函式

    callback 參數如下所示： 

    () => void

onSuspendCanceled

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

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

參數

  • 回呼

    函式

    callback 參數如下所示： 

    () => void

onUpdateAvailable

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

當有可用的更新，但因應用程式目前正在執行而未立即安裝時觸發。如果您沒有採取任何行動，更新會在下次背景頁面卸載時安裝。如果您想提早安裝更新，可以明確呼叫 chrome.runtime.reload()。如果擴充功能使用的是永久背景頁面，背景頁面當然不會卸載，因此除非您手動呼叫 chrome.runtime.reload() 以回應此事件，否則更新會在下次 Chrome 重新啟動時才會安裝。如果沒有處理常式會監聽這個事件，且擴充功能有持續性的背景頁面，則會以呼叫 chrome.runtime.reload() 回應這個事件的形式運作。

參數

  • 回呼

    函式

    callback 參數如下所示： 

    (details: object) => void

    • 詳細資料

      物件

      • 版本

        字串

        可用更新的版本號碼。

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

      布林值 | 未定義