chrome.runtime

說明

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

權限

執行階段 API 中的大多數方法不需要任何權限，但 sendNativeMessage 和 connectNative 例外，這兩個方法需要 nativeMessaging 權限。

資訊清單

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

manifest.json:

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

用途

在網頁中加入圖片

網頁要存取其他網域上代管的素材資源，就必須指定資源的完整網址 (例如 <img src="https://example.com/logo.png">)。在網頁上加入擴充功能素材資源時，也必須遵循相同的做法。這兩個差異在於擴充功能的資產必須以 web 的形式公開 存取資源，且一般的內容指令碼負責 額外資訊素材資源

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

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 訊息傳遞至 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');
  }
});

擴充功能範例

如需更多執行階段 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"
將結構定義類型指定為 Service Worker。

"OFFSCREEN_DOCUMENT"
將結構定義類型指定為螢幕外文件。

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

"DEVELOPER_TOOLS"
將結構定義類型指定為開發人員工具。

ExtensionContext

Chrome 114 以上版本

內容代管擴充功能內容。

屬性

  • contextId

    字串

    這個情境的專屬 ID

  • contextType

    ContextType

    與此值對應的背景資訊類型。

  • documentId

    string 選填

    此結構定義相關文件的 UUID；如果這個結構定義並非由文件代管，則為未定義。

  • documentOrigin

    string optional

    與此內容相關聯的文件來源，如果內容未在文件中代管，則為 undefined。

  • documentUrl

    string 選填

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

  • frameId

    數字

    這個背景資訊的影格 ID；如果這個結構定義並非由影格代管，則為 -1。

  • 無痕模式

    布林值

    上下文是否與無痕模式設定檔相關聯。

  • tabId

    數字

    此結構定義的分頁 ID；如果這項內容不是由分頁中代管，則為 -1。

  • windowId

    數字

    這個結構定義的視窗 ID；如果這個結構定義並非由視窗代管，則為 -1。

MessageSender

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

屬性

  • documentId

    string optional

    Chrome 106 以上版本

    開啟連線的文件的 UUID。

  • documentLifecycle

    string 選填

    Chrome 106 以上版本

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

  • frameId

    編號 選填

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

  • id

    string optional

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

  • nativeApplication

    string 選填

    Chrome 74 以上版本

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

  • 起源

    string optional

    Chrome 80 以上版本

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

  • 分頁

    Tab 鍵 選用

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

  • tlsChannelId

    string optional

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

  • 網址

    string 選填

    開啟連線的網頁或頁框網址。如果寄件者是在 iframe 中，則寄件者將會是 iframe 的網址，而不是代管該寄件者的網頁網址。

OnInstalledReason

Chrome 44 以上版本

觸發事件的理由。

列舉

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

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

&quot;chrome_update&quot;
指明 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

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

  • Chrome 正在執行 Chrome 作業系統。

PlatformNaclArch

Chrome 44 以上版本

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

列舉

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

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

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

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

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

PlatformOs

Chrome 44 以上版本

Chrome 正在執行 Chrome 作業系統。

列舉

"mac"
指定 MacOS 作業系統。

"win"
指定 Windows 作業系統。

"android"
指定 Android 作業系統。

"cros"
指定 Chrome 作業系統。

"linux"
指定 Linux 作業系統。

"openbsd"
指定 OpenBSD 作業系統。

"fuchsia"
指定 Fuchsia 作業系統。

Port

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

屬性

  • 名稱

    字串

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

  • onDisconnect

    Event<function void void>

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

    onDisconnect.addListener 函式如下所示： 

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

    • 回呼

      函式

      callback 參數如下所示： 

      (port: Port) => void

  • onMessage

    Event<function void void>

    當端口的另一端呼叫 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 函式。傳回 Promise 的 API 函式不會設定這個屬性。

類型

物件

屬性

  • 訊息

    string 選填

    發生錯誤的詳細資料。

方法

connect()

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

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

參數

  • extensionId

    string optional

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

  • connectInfo

    物件 選填

    • includeTlsChannelId

      布林值 選填

      是否會將 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

      Window 選用

      JavaScript 的「視窗」將物件用於背景頁面

傳回

  • Promise<Window | undefined>

    Chrome 99 以上版本

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

getContexts()

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

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

參數

  • 篩選器

    ContextFilter

    用於尋找相符內容的篩選器。背景資訊會與篩選器中的所有指定欄位相符。篩選器中未指定的任何欄位都符合所有背景資訊。

  • 回呼

    函式 選用

    callback 參數如下所示： 

    (contexts: ExtensionContext[]) => void

傳回

  • Promise<ExtensionContext[]>

    承諾僅支援資訊清單 V3 以上版本，其他平台則需要使用回呼。

getManifest()

chrome.runtime.getManifest()

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

傳回

  • 物件

    資訊清單詳細資料。

getPackageDirectoryEntry()

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

傳回套件目錄的 DirectoryEntry。

參數

  • 回呼

    函式 選用

    callback 參數如下所示： 

    (directoryEntry: DirectoryEntry) => void

    • directoryEntry

      DirectoryEntry

傳回

  • Promise<DirectoryEntry>

    Chrome 122 以上版本

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

getPlatformInfo()

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

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

參數

傳回

  • Promise<PlatformInfo>

    Chrome 99 以上版本

    承諾僅支援資訊清單 V3 以上版本，其他平台則需要使用回呼。

getURL()

chrome.runtime.getURL(
  path: string,
)

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

參數

  • 路徑

    字串

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

傳回

  • 字串

    資源的完整網址。

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

    承諾僅支援資訊清單 V3 以上版本，其他平台則需要使用回呼。

reload()

chrome.runtime.reload()

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

requestUpdateCheck()

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

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

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

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

注意： 透過回呼呼叫時，此函式會傳回兩個屬性，做為傳遞至回呼的個別引數，而不是傳回物件。

參數

  • 回呼

    函式 選用

    callback 參數如下所示： 

    (result: object) => void

    • 結果

      物件

      Chrome 109 以上版本

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

      • 更新檢查結果。

      • 版本

        string optional

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

傳回

  • Promise<object>

    Chrome 109 以上版本

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

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

    承諾僅支援資訊清單 V3 以上版本，其他平台則需要使用回呼。

sendMessage()

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

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

參數

  • extensionId

    string optional

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

  • 訊息

    不限

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

  • 選項

    物件 選填

    • includeTlsChannelId

      boolean 選填

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

  • 回呼

    函式 選填

    Chrome 99 以上版本

    callback 參數如下所示： 

    (response: any) => void

    • 回應

      不限

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

傳回

  • 承諾<任何>

    Chrome 99 以上版本

    承諾僅支援資訊清單 V3 以上版本，其他平台則需要使用回呼。

sendNativeMessage()

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

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

參數

  • 調度應用程式資源

    字串

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

  • 訊息

    物件

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

  • 回呼

    函式 選填

    Chrome 99 以上版本

    callback 參數如下所示： 

    (response: any) => void

    • 回應

      不限

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

傳回

  • 承諾<任何>

    Chrome 99 以上版本

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

setUninstallURL()

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

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

參數

  • 網址

    字串

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

  • 回呼

    函式 選填

    Chrome 45 以上版本

    callback 參數如下所示： 

    () => void

傳回

  • Promise<void>

    Chrome 99 以上版本

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

活動

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

        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 小時的寬限期過後強制重新啟動。目前，只有 Chrome 作業系統資訊站應用程式會觸發此事件。

參數

onStartup

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

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

參數

  • 回呼

    函式

    callback 參數如下所示： 

    () => void

onSuspend

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

在事件頁面卸載前傳送。讓擴充功能可以做一些清理工作。請注意，由於網頁會卸載，因此在處理這個事件時開始的非同步作業，不保證會完成。如果事件頁面在卸載「已停權」事件前發生更多活動，系統將傳送「已停權」事件，且不會卸載頁面。

參數

  • 回呼

    函式

    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

    • 詳細資料

      物件

      • 版本

        字串

        可用更新的版本號碼。

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

      布林值 | 未定義