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

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

这些方法仅适用于 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

扩展程序的内容脚本经常需要由扩展程序的其他部分（如 Service Worker）管理的数据。就像打开同一个网页的两个浏览器窗口一样，这两个上下文无法直接访问彼此的值。相反，该扩展程序可以使用消息传递功能在这些不同上下文之间进行协调。

在此示例中，内容脚本需要来自扩展程序的 Service Worker 的一些数据来初始化其界面。为了获取此数据，它会将开发者定义的 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);
});

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

示例

如需查看更多 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"
以侧边栏形式指定上下文类型。

ExtensionContext

Chrome 114 及更高版本

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

属性

• contextId

  string

  此上下文的唯一标识符

• contextType

  ContextType

  对应的上下文类型。

• documentId

  字符串（可选）

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

• documentOrigin

  字符串（可选）

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

• documentUrl

  字符串（可选）

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

• frameId

  number

  此上下文的帧 ID，如果该上下文未托管在帧中，则为 -1。

• 无痕模式

  boolean

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

• tabId

  number

  此上下文的标签页 ID，如果该上下文未托管在标签页中，则为 -1。

• windowId

  number

  此上下文的窗口 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_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 形式指定处理器架构。

PlatformInfo

包含当前平台相关信息的对象。

属性

• 拱门

  PlatformArch

  机器的处理器架构。

• nacl_arch

  PlatformNaclArch

  原生客户端架构。在某些平台上，这可能与 arch 不同。

• os

  PlatformOs

  运行 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

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

属性

• name

  string

  端口的名称，在对 runtime.connect 的调用中指定。

• onDisconnect

  事件<functionvoid>

  在端口与另一端断开连接时触发。如果端口因错误而断开连接，则可以设置 runtime.lastError。如果端口通过 断开连接关闭，则此事件只会在另一端触发。此事件最多触发一次（另请参阅端口生命周期）。

  onDisconnect.addListener 函数如下所示：

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

  • callback

    功能

    callback 参数如下所示：

    (port: Port)=>void

    • 端口

      Port（端口）

• onMessage

  事件<functionvoid>

  端口的另一端调用 postMessage 时会触发此事件。

  onMessage.addListener 函数如下所示：

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

  • callback

    功能

    callback 参数如下所示：

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

    • 信息

      任意

    • 端口

      Port（端口）

• 发送者

  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。

类型

string

lastError

如果 API 函数调用失败，则填充错误消息，否则将填充未定义状态。这只能在该函数的回调范围内定义。如果产生了错误，但未在回调中访问 runtime.lastError，则控制台会记录一条消息，列出产生该错误的 API 函数。返回 promise 的 API 函数不会设置此属性。

类型

对象

属性

• 信息

  字符串（可选）

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

方法

connect()

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

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

参数

• extensionId

  字符串（可选）

  要连接的扩展程序的 ID。如果省略此参数，系统将尝试与您自己的扩展程序建立连接。如果要使用网络消息功能从网页发送消息，则必须提供此值。

• connectInfo

  对象（可选）

  • includeTlsChannelId

    布尔值 选填

    对于正在监听连接事件的进程，是否将 TLS 通道 ID 传递到 onConnectExternal。

  • name

    字符串（可选）

    对于正在监听连接事件的进程，此参数将传递到 onConnect。

返回

• Port（端口）

  可以发送和接收消息的端口。如果该扩展程序不存在，则会触发相应端口的 onDisconnect 事件。

connectNative()

chrome.runtime.connectNative(
  application: string,
)

连接到主机中的原生应用。此方法需要 "nativeMessaging" 权限。如需了解详情，请参阅原生消息传递。

参数

• 应用

  string

  要连接的已注册应用的名称。

返回

• Port（端口）

  可通过应用发送和接收消息的端口

getBackgroundPage()

Promise 仅限前台

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

检索当前扩展程序/应用中运行的后台网页的 JavaScript“window”对象。如果该后台网页是事件网页，系统将确保在调用回调之前已加载该网页。如果没有后台网页，则会设置错误。

参数

• callback

  函数（可选）

  callback 参数如下所示：

  (backgroundPage?: Window)=>void

  • backgroundPage

    窗口（可选）

    背景网页的 JavaScript“window”对象。

返回

• Promise<Window|undefined>

  Chrome 99 及更高版本

  Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。

getContexts()

Promise Chrome 116 及更高版本 MV3+

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

提取与此扩展程序相关联的有效上下文的相关信息

参数

• filter

  ContextFilter

  用于查找匹配上下文的过滤条件。如果上下文与过滤器中的所有指定字段匹配，则与之匹配。过滤器中任何未指定的字段都与所有上下文匹配。

• callback

  函数（可选）

  callback 参数如下所示：

  (contexts: ExtensionContext[])=>void

  • 上下文

    ExtensionContext[]

    匹配的上下文（如果有）。

返回

• Promise<ExtensionContext[]>

  Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。

getManifest()

chrome.runtime.getManifest()

从清单中返回有关应用或扩展程序的详细信息。返回的对象是完整清单文件的序列化内容。

返回

• 对象

  清单详情。

getPackageDirectoryEntry()

Promise 仅限前台

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

返回软件包目录的 DirectoryEntry。

参数

• callback

  函数（可选）

  callback 参数如下所示：

  (directoryEntry: DirectoryEntry)=>void

  • directoryEntry

    DirectoryEntry

返回

• Promise<DirectoryEntry>

  Chrome 122 及更高版本

  Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。

getPlatformInfo()

Promise

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

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

参数

• callback

  函数（可选）

  callback 参数如下所示：

  (platformInfo: PlatformInfo)=>void

  • platformInfo

    PlatformInfo

返回

• Promise<PlatformInfo>

  Chrome 99 及更高版本

  Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。

getURL()

chrome.runtime.getURL(
  path: string,
)

将应用/扩展程序安装目录中的相对路径转换为完全限定网址。

参数

• path

  string

  应用/扩展程序中资源的路径，以相对于其安装目录表示。

返回

• 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

  函数（可选）

  callback 参数如下所示：

  ()=>void

返回

• Promise<void>

  Chrome 99 及更高版本

  Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。

reload()

chrome.runtime.reload()

重新加载应用或扩展程序。自助服务终端模式不支持此方法。对于自助服务终端模式，请使用 chrome.runtime.restart() 方法。

requestUpdateCheck()

Promise

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

请求对此应用程序/扩展程序进行立即更新检查。

重要提示：大多数扩展程序/应用不应使用此方法，因为 Chrome 已每隔几小时执行一次自动检查，您无需调用 requestUpdateCheck 即可监听 runtime.onUpdateAvailable 事件。

此方法仅适合在极少数情况下调用，例如，您的扩展程序与后端服务通信，而后端服务已确定该客户端扩展程序版本太旧，而您想要提示用户进行更新。requestUpdateCheck 的大多数其他用途（例如根据重复性计时器无条件调用）可能只会浪费客户端、网络和服务器资源。

注意： 使用回调进行调用时，此函数不会返回对象，而是将返回这两个属性作为分别传递到该回调的参数。

参数

• callback

  函数（可选）

  callback 参数如下所示：

  (result: object)=>void

  • 结果

    对象

    Chrome 109 及更高版本

    RequestUpdateCheckResult 对象，用于保存更新检查的状态以及结果的任何详细信息（如果有可用更新）

    • status

      RequestUpdateCheckStatus

      更新检查的结果。

    • 版本

      字符串（可选）

      如果有可用更新，则此字段包含可用更新的版本。

返回

• Promise<object>

  Chrome 109 及更高版本

  Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。

restart()

chrome.runtime.restart()

当应用在自助服务终端模式下运行时，重启 ChromeOS 设备。否则，这就是空操作。

restartAfterDelay()

Promise Chrome 53 及更高版本

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

当应用在自助服务终端模式下运行时，在特定秒数后重启 ChromeOS 设备。如果在时间结束前再次调用，重新启动将会延迟。如果使用 -1 值调用，则重新启动将被取消。这是非自助服务终端模式下的空操作。只能由第一个扩展程序重复调用以调用此 API。

参数

• 秒

  number

  重新启动设备前的等待时间（以秒为单位），如果选择 -1，则可以取消预定的重新启动。

• callback

  函数（可选）

  callback 参数如下所示：

  ()=>void

返回

• Promise<void>

  Chrome 99 及更高版本

  Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。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。

• callback

  函数（可选）

  Chrome 99 及更高版本

  callback 参数如下所示：

  (response: any)=>void

  • 条回复

    任意

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

返回

• 承诺<any>

  Chrome 99 及更高版本

  Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。

sendNativeMessage()

Promise

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

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

参数

• 应用

  string

  原生消息传递主机的名称。

• 信息

  对象

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

• callback

  函数（可选）

  Chrome 99 及更高版本

  callback 参数如下所示：

  (response: any)=>void

  • 条回复

    任意

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

返回

• 承诺<any>

  Chrome 99 及更高版本

  Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。

setUninstallURL()

Promise

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

设置卸载后要访问的网址。可用于清理服务器端数据、执行分析和开展调查。不得超过 1023 个字符。

参数

• 网址

  string

  要在卸载扩展程序后打开的网址。此网址必须包含 http: 或 https: 架构。设置空字符串，即可在卸载时不打开新标签页。

• callback

  函数（可选）

  Chrome 45 及更高版本

  callback 参数如下所示：

  ()=>void

返回

• Promise<void>

  Chrome 99 及更高版本

  Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。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

  • 端口

    Port（端口）

onConnectExternal

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

通过其他扩展程序（通过 runtime.connect）或外部可连接的网站建立连接时触发。

参数

• callback

  功能

  callback 参数如下所示：

  (port: Port)=>void

  • 端口

    Port（端口）

onConnectNative

Chrome 76 及更高版本

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

从原生应用建立连接时触发。此活动需要 "nativeMessaging" 权限。只有 Chrome 操作系统支持此功能。

参数

• callback

  功能

  callback 参数如下所示：

  (port: Port)=>void

  • 端口

    Port（端口）

onInstalled

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

首次安装扩展程序、将扩展程序更新到新版本以及 Chrome 更新到新版本时触发。

参数

• callback

  功能

  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

  功能

  callback 参数如下所示：

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

  • 信息

    任意

  • 发送者

    MessageSender

  • sendResponse

    功能

    sendResponse 参数如下所示：

    ()=>void

  • 返回

    boolean|undefined

onMessageExternal

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

从其他扩展程序发送消息时触发（通过 runtime.sendMessage）。无法在内容脚本中使用。

参数

• callback

  功能

  callback 参数如下所示：

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

  • 信息

    任意

  • 发送者

    MessageSender

  • sendResponse

    功能

    sendResponse 参数如下所示：

    ()=>void

  • 返回

    boolean|undefined

onRestartRequired

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

当应用或运行该应用的设备需要重启时触发。应用应在方便时尽早关闭所有窗口，以便重新启动。如果应用不执行任何操作，则系统会在 24 小时宽限期过后强制重启。目前，系统仅会针对 Chrome 操作系统自助服务终端应用触发此事件。

参数

• callback

  功能

  callback 参数如下所示：

  (reason: OnRestartRequiredReason)=>void

  • 原因

    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

  • 明细

    对象

    • 版本

      string

      可用更新的版本号。

onUserScriptConnect

Chrome 115 及更高版本 MV3+

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

通过此扩展程序中的用户脚本建立连接时触发。

参数

• callback

  功能

  callback 参数如下所示：

  (port: Port)=>void

  • 端口

    Port（端口）

onUserScriptMessage

Chrome 115 及更高版本 MV3+

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

从与同一扩展程序相关联的用户脚本发送消息时触发。

参数

• callback

  功能

  callback 参数如下所示：

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

  • 信息

    任意

  • 发送者

    MessageSender

  • sendResponse

    功能

    sendResponse 参数如下所示：

    ()=>void

  • 返回

    boolean|undefined