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()。

自助服务终端模式实用程序

这些方法仅适用于 ChromeOS，主要用于支持自助服务终端实现。 此类别中的方法包括 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 获取一些数据来初始化其界面。为了获取这些数据，它会向 Service Worker 传递一条 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);
});

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 - 可通过网络访问的资源演示。

类型

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"
将上下文类型指定为侧边栏。

"DEVELOPER_TOOLS"
将上下文类型指定为开发者工具。

ExtensionContext

Chrome 114 及更高版本

托管扩展程序内容的上下文。

属性

• 上下文 ID

  字符串

  此上下文的唯一标识符

• contextType

  ContextType

  此上下文对应的类型。

• documentId

  字符串 可选

  与此上下文关联的文档的 UUID；如果此上下文未托管在文档中，则为 undefined。

• documentOrigin

  字符串 可选

  与此上下文关联的文档的来源；如果上下文未托管在文档中，则为 undefined。

• documentUrl

  字符串 可选

  与此上下文关联的文档的网址；如果上下文未托管在文档中，则为 undefined。

• frameId

  数值

  此上下文的框架 ID；如果此上下文未托管在框架中，则为 -1。

• 无痕模式

  布尔值

  上下文是否与无痕式个人资料相关联。

• 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

  number 可选

  打开连接的框架。0 表示顶层框架，正数表示子框架。仅当设置了 tab 时，才会设置此字段。

• id

  字符串 可选

  打开连接的扩展程序的 ID（如果有）。

• nativeApplication

  字符串 可选

  Chrome 74 及更高版本

  打开连接的原生应用的名称（如有）。

• 源

  字符串 可选

  Chrome 80 及更高版本

  打开连接的页面或框架的来源。它可能与 url 属性不同（例如 about:blank），也可能不透明（例如沙盒化 iframe）。如果我们无法立即从网址中判断来源是否可信，此功能就非常有用。

• Tab

  标签页 （可选）

  打开连接的 tabs.Tab（如果有）。仅当连接是从标签页（包括内容脚本）打开时，并且仅当接收方是扩展程序而非应用时，此属性才会存在。

• tlsChannelId

  字符串 可选

  打开连接的页面或框架的 TLS 渠道 ID（如果扩展程序请求了该 ID 且该 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”用于因浏览器/操作系统更新到较新版本而需要重启的情况。当系统运行时间超过企业政策中设置的允许运行时间时，系统会使用“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

一个允许与其他页面进行双向通信的对象。如需了解详情，请参阅长连接。

属性

• name

  字符串

  端口的名称，在对 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

    • 私信

      任意

    • 端口

      端口

• 发送者

  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 函数失败，则填充出错提示；否则为 undefined。此变量仅在该函数的回调范围内定义。如果发生错误，但未在回调中访问 runtime.lastError，则系统会将一条消息记录到控制台，其中列出了产生错误的 API 函数。返回 promise 的 API 函数不会设置此属性。

类型

对象

属性

• 私信

  字符串 可选

  有关所发生错误的详细信息。

方法

connect()

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

尝试连接扩展程序（例如后台页面）或其他扩展程序/应用中的监听器。这对于连接到其扩展程序进程的内容脚本、应用/扩展程序间通信以及网络消息传递非常有用。请注意，这不会连接到内容脚本中的任何监听器。扩展程序可以通过 tabs.connect 连接到嵌入在标签页中的内容脚本。

参数

• extensionId

  字符串 可选

  要连接的扩展程序的 ID。如果省略，系统会尝试与您自己的扩展程序建立连接。如果从网页发送消息以进行网页消息传递，则必须提供此参数。

• connectInfo

  对象（可选）

  • includeTlsChannelId

    布尔值 （可选）

    是否将 TLS 频道 ID 传递到 onConnectExternal，以便监听连接事件。

  • name

    字符串 可选

    将传递到 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 及更高版本

  只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

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 及更高版本

  只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

getPlatformInfo()

Promise

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

返回有关当前平台的信息。

参数

• callback

  函数可选

  callback 参数如下所示：

  (platformInfo: PlatformInfo) => void

  • platformInfo

    PlatformInfo

返回

• Promise<PlatformInfo>

  Chrome 99 及更高版本

  使用当前平台的相关信息进行解析的 Promise。

  只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

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 及更高版本

  只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

reload()

chrome.runtime.reload(): void

重新加载应用或扩展程序。自助服务终端模式不支持此方法。对于自助服务终端模式，请使用 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 及更高版本

  只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

restart()

chrome.runtime.restart(): void

在应用以自助服务终端模式运行时重启 ChromeOS 设备。否则，它不执行任何操作。

restartAfterDelay()

Promise Chrome 53 及更高版本

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

当应用在自助服务终端模式下运行达到指定秒数后，重启 ChromeOS 设备。如果在时间结束前再次调用，重启将会延迟。如果调用时值为 -1，则重启将被取消。在非自助服务终端模式下，此方法为空操作。只有第一个调用此 API 的扩展程序才能重复调用它。

参数

• 秒

  数值

  重启设备前等待的时间（以秒为单位），或输入 -1 以取消预定的重启。

• callback

  函数可选

  callback 参数如下所示：

  () => void

返回

• 承诺<void>

  Chrome 99 及更高版本

  在重启请求成功重新安排后解析的 Promise。

  只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

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

  • Response

    任意

    消息处理程序发送的 JSON 响应对象。如果在连接到扩展程序时发生错误，系统会在不带任何参数的情况下调用回调，并将 runtime.lastError 设置为出错提示。

返回

• 承诺<任何>

  Chrome 99 及更高版本

  Chrome 99 中添加了对扩展程序上下文的 Promise 支持。从 Chrome 118 开始，在从网页与扩展程序通信时，可以使用 promise。

  只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

sendNativeMessage()

Promise

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

向原生应用发送单条消息。此方法需要 "nativeMessaging" 权限。

参数

• 应用

  字符串

  原生消息传递主机的名称或目标详情。

• 私信

  对象

  将传递给原生消息传递主机的消息。

• callback

  函数可选

  Chrome 99 及更高版本

  callback 参数如下所示：

  (response: any) => void

  • Response

    任意

    原生消息传递主机发送的响应消息。如果在连接到原生消息传递主机时发生错误，系统会在不带任何参数的情况下调用回调，并将 runtime.lastError 设置为出错提示。

返回

• 承诺<任何>

  Chrome 99 及更高版本

  只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

setUninstallURL()

Promise

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

设置卸载时要访问的网址。这可用于清理服务器端数据、进行分析和实施调查。最多 1023 个字符。

参数

• url

  字符串

  卸载扩展程序后要打开的网址。此网址必须采用 http: 或 https: 协议。如果设置为空字符串，则卸载后不会打开新标签页。

• callback

  函数可选

  Chrome 45 及更高版本

  callback 参数如下所示：

  () => void

返回

• 承诺<void>

  Chrome 99 及更高版本

  在设置卸载网址时解析的 Promise。如果给定的网址无效，promise 将被拒绝。

  只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

事件

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

  • 私信

    任意

  • 发送者

    MessageSender

  • sendResponse

    函数

    sendResponse 参数如下所示：

    (response?: any) => void

    • Response

      any 可选

      要返回给消息发送者的响应。

  • 返回

    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

  • 私信

    任意

  • 发送者

    MessageSender

  • sendResponse

    函数

    sendResponse 参数如下所示：

    (response?: any) => void

    • Response

      any 可选

      要返回给消息发送者的响应。

  • 返回

    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

  • 详细信息

    对象

    • 版本

      字符串

      可用更新的版本号。