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">)。附加額外資訊素材資源也是一樣 網頁。這兩個差異在於擴充功能的資產必須以 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

擴充功能的內容指令碼往往需要由擴充功能的其他部分管理的資料。 例如 Service Worker與開啟相同網頁的兩個瀏覽器視窗類似 兩個情境無法直接存取彼此的值。而是可以使用 message 傳遞，藉此相互協調不同結構定義。

在這個範例中，內容指令碼需要擴充功能的 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 以上版本

列舉

「分頁」
將結構定義類型指定為分頁

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

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

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

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

ExtensionContext

Chrome 114 以上版本

內容代管擴充功能內容。

屬性

  • contextId

    字串

    此內容的專屬 ID

  • contextType

    ContextType

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

  • documentId

    string optional

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

  • documentOrigin

    string optional

    與這個情境相關聯的文件來源；如果內容並非由文件代管，則為未定義。

  • documentUrl

    string optional

    與上下文相關的文件網址；如果內容並非由文件代管，則為未定義。

  • frameId

    數字

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

  • 無痕模式

    布林值

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

  • tabId

    數字

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

  • windowId

    數字

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

MessageSender

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

屬性

  • documentId

    string optional

    Chrome 106 以上版本

    開啟連線的文件的 UUID。

  • documentLifecycle

    string optional

    Chrome 106 以上版本

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

  • frameId

    編號 選填

    開啟連線的影格。0 代表頂層影格；如果是子影格，則為正值。這個項目只有在已設定 tab 時才會設定。

  • id

    string optional

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

  • nativeApplication

    string optional

    Chrome 74 以上版本

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

  • 起源

    string optional

    Chrome 80 以上版本

    開啟連線的網頁或頁框來源。可能與網址資源不同 (例如 about:blank) 或不透明 (例如採用沙箱機制的 iframe)。如果我們無法立即從網址得知來源是否可信任，這項資訊就能派上用場。

  • 分頁

    Tab 鍵 選用

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

  • tlsChannelId

    string optional

    開啟連線的網頁或頁框的傳輸層安全標準 (TLS) 管道 ID (如果擴充功能要求的話，以及如果有的話)。

  • 網址

    string optional

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

OnInstalledReason

Chrome 44 以上版本

傳送這個事件的原因。

列舉

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

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

&quot;chrome_update&quot;
指明 Chrome 更新事件的原因。

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

OnRestartRequiredReason

Chrome 44 以上版本

傳送事件的原因。「app_update」由於應用程式已更新到較新的版本，所以需要重新啟動時，就會使用這個數字。os_update當瀏覽器/OS 更新為新版本時，就會使用需要重新啟動的時間。「週期」當系統執行的時間超過企業政策中設定的許可運作時間時，就會使用這個值。

列舉

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

&quot;os_update&quot;
將事件原因指明為作業系統更新。

"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"
將原生用戶端架構指定為實驗組。

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

&quot;openbsd&quot;
指定 OpenBSD 作業系統。

"fuchsia"
指定 Fuchsia 作業系統。

Port

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

屬性

  • 名稱

    字串

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

  • onDisconnect

    事件<functionvoid>

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

    onDisconnect.addListener 函式如下所示： 

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

    • 回呼

      函式

      callback 參數如下所示： 

      (port: Port) => void

  • onMessage

    事件<functionvoid>

    當通訊埠的另一端呼叫 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 optional

    發生錯誤的詳細資料。

方法

connect()

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

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

參數

  • extensionId

    string optional

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

  • connectInfo

    物件 optional

    • includeTlsChannelId

      布林值 選填

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

    • 名稱

      string optional

      將傳遞至 onConnect，供監聽連線事件的程序。

傳回

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

connectNative()

chrome.runtime.connectNative(
  application: string,
)

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

參數

  • 調度應用程式資源

    字串

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

傳回

  • 可以與應用程式傳送及接收訊息的通訊埠

getBackgroundPage()

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

擷取 JavaScript 的「視窗」用於目前擴充功能/應用程式內部執行的背景頁面物件。如果背景頁面是事件頁面，系統會在呼叫回呼前確保頁面已載入。如果沒有背景頁面，則會發生錯誤。

參數

  • 回呼

    函式 選用

    callback 參數如下所示： 

    (backgroundPage?: Window) => void

    • backgroundPage

      Window 選用

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

傳回

  • Promise&lt;Window |未定義>

    Chrome 99 以上版本

    Promise 適用於 Manifest V3 及以上版本，但系統會為 回溯相容性您無法在同一函式呼叫中同時使用兩者。 保證會以傳遞至回呼的相同類型來解析。

getContexts()

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

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

參數

  • 篩選器

    ContextFilter

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

  • 回呼

    函式 選用

    callback 參數如下所示： 

    (contexts: ExtensionContext[]) => void

傳回

  • Promise&lt;ExtensionContext[]&gt;

    Promise 適用於 Manifest V3 及以上版本，但系統會為 回溯相容性您無法在同一函式呼叫中同時使用兩者。 保證會以傳遞至回呼的相同類型來解析。

getManifest()

chrome.runtime.getManifest()

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

傳回

  • 物件

    資訊清單詳細資料。

getPackageDirectoryEntry()

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

傳回套件目錄的 DirectoryEntry。

參數

  • 回呼

    函式 選用

    callback 參數如下所示： 

    (directoryEntry: DirectoryEntry) => void

    • directoryEntry

      DirectoryEntry

傳回

  • Promise&lt;DirectoryEntry&gt;

    Chrome 122 以上版本

    Promise 適用於 Manifest V3 及以上版本，但系統會為 回溯相容性您無法在同一函式呼叫中同時使用兩者。 保證會以傳遞至回呼的相同類型來解析。

getPlatformInfo()

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

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

參數

傳回

  • Promise&lt;PlatformInfo&gt;

    Chrome 99 以上版本

    Promise 適用於 Manifest 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

傳回

  • 承諾<void>

    Chrome 99 以上版本

    Promise 適用於 Manifest V3 及以上版本，但系統會為 回溯相容性您無法在同一函式呼叫中同時使用兩者。 保證會以傳遞至回呼的相同類型來解析。

reload()

chrome.runtime.reload()

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

requestUpdateCheck()

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

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

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

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

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

參數

  • 回呼

    函式 選用

    callback 參數如下所示： 

    (result: object) => void

    • 結果

      物件

      Chrome 109 以上版本

      RequestUpdateCheckResult 物件，該物件會保留更新檢查的狀態，以及有可用的更新時，結果的詳細資料

      • 更新檢查的結果。

      • 版本

        string optional

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

傳回

  • Promise&lt;object&gt;

    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，則會取消重新啟動。這是非 Kiosk 模式的免人工管理項目，只有第一個擴充功能可以重複呼叫此 API，才能叫用此 API。

參數

  • 秒

    數字

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

  • 回呼

    函式 選用

    callback 參數如下所示： 

    () => void

傳回

  • 承諾<void>

    Chrome 99 以上版本

    Promise 適用於 Manifest 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 格式的物件。

  • 選項

    物件 optional

    • includeTlsChannelId

      布林值 選填

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

  • 回呼

    函式 選用

    Chrome 99 以上版本

    callback 參數如下所示： 

    (response: any) => void

    • 回應

      不限

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

傳回

  • 承諾<任何>

    Chrome 99 以上版本

    Promise 適用於 Manifest 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

傳回

  • 承諾<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 optional

        表示已更新的共用模組擴充功能 ID。只有在「合理」情況下才會顯示是「shared_module_update」。

      • previousVersion

        string optional

        指出舊版擴充功能 (最近已更新)。只有在「合理」情況下才會顯示「更新」

      • 傳送這個事件的原因。

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 |未定義

onMessageExternal

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

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

參數

  • 回呼

    函式

    callback 參數如下所示： 

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

    • 訊息

      不限

    • 傳送者

      MessageSender

    • sendResponse

      函式

      sendResponse 參數如下所示： 

      () => void

    • returns

      boolean |未定義

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() 一樣，此事件的行為會如同呼叫 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

      boolean |未定義