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()。
自助服务终端模式实用程序
这些方法仅适用于 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);
}

将数据从内容脚本发送到服务工件

扩展程序的内容脚本通常需要由扩展程序的其他部分（例如服务工件）管理的数据。这两种情境就像打开了两个指向同一网页的浏览器窗口一样，无法直接访问对方的值。相反，扩展程序可以使用消息传递来跨这些不同的上下文进行协调。

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

示例

如需查看更多 Runtime API 示例，请参阅 Manifest V3 - Web Accessible Resources 演示。

类型

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”
将上下文类型指定为服务工件。

"OFFSCREEN_DOCUMENT"
将上下文类型指定为屏幕外文档。

"SIDE_PANEL"
将情境类型指定为侧边栏。

“DEVELOPER_TOOLS”
将情境类型指定为开发者工具。

ExtensionContext

Chrome 114 及更高版本

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

属性

  • 上下文 ID

    字符串

    此情境的唯一标识符

  • contextType

    ContextType

    此项对应的上下文类型。

  • documentId

    字符串（选填）

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

  • documentOrigin

    字符串（选填）

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

  • documentUrl

    字符串（选填）

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

  • frameId

    数值

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

  • 无痕

    布尔值

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

  • tabId

    数值

    此情境对应的标签页的 ID；如果此情境未托管在标签页中，则为 -1。

  • windowId

    数值

    此上下文对应的窗口的 ID；如果此上下文未托管在窗口中，则为 -1。

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（如果扩展程序请求且可用）。

  • 网址

    字符串（选填）

    打开连接的网页或框架的网址。如果发件人位于 iframe 中，则为 iframe 的网址，而不是托管 iframe 的网页的网址。

OnInstalledReason

Chrome 44 及更高版本

分派此事件的原因。

枚举

“install”
将事件原因指定为安装。

“update”
将事件原因指定为扩展程序更新。

"chrome_update"
将事件原因指定为 Chrome 更新。

"shared_module_update"
将事件原因指定为对共享模块的更新。

OnRestartRequiredReason

Chrome 44 及更高版本

调度事件的原因。如果应用更新到较新版本而需要重启，则使用“app_update”。如果由于浏览器/操作系统更新到较新版本而需要重启，则使用“os_update”。如果系统运行时间超过企业政策中设置的允许正常运行时间，则使用“定期”。

枚举

"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

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

属性

  • 机器的处理器架构。

  • 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

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

属性

  • name

    字符串

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

  • onDisconnect

    Event<functionvoidvoid>

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

    onDisconnect.addListener 函数如下所示： 

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

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

类型

对象

属性

  • 消息

    字符串（选填）

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

方法

connect()

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

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

参数

  • extensionId

    字符串（选填）

    要连接到的扩展程序的 ID。如果省略，系统会尝试与您自己的扩展程序建立连接。如果要通过网页发送网络消息，则必须提供此属性。

  • connectInfo

    对象（可选）

    • includeTlsChannelId

      布尔值（可选）

      是否将 TLS 通道 ID 传递给监听连接事件的进程的 onConnectExternal。

    • name

      字符串（选填）

      将传递给监听连接事件的进程的 onConnect。

返回

  • 用于发送和接收消息的端口。如果扩展程序不存在，则会触发相应充电桩的 onDisconnect 事件。

connectNative()

chrome.runtime.connectNative(
  application: string,
)

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

参数

  • 应用

    字符串

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

返回

getBackgroundPage()

Promise 仅限前台 
chrome.runtime.getBackgroundPage(
  callback?: function,
)

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

参数

  • callback

    函数（可选）

    callback 参数如下所示： 

    (backgroundPage?: Window) => void

    • backgroundPage

      窗口（可选）

      后台页面的 JavaScript“window”对象。

返回

  • Promise<Window | undefined>

    Chrome 99 及更高版本

    清单 V3 及更高版本支持 Promise，但为了实现向后兼容性，我们提供了回调。您不能在同一函数调用中同时使用这两种方法。promise 的解析结果与传递给回调的类型相同。

getContexts()

Promise Chrome 116 及更高版本 MV3 及更高版本 
chrome.runtime.getContexts(
  filter: ContextFilter,
  callback?: function,
)

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

参数

  • filter

    ContextFilter

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

  • callback

    函数（可选）

    callback 参数如下所示： 

    (contexts: ExtensionContext[]) => void

返回

  • Promise<ExtensionContext[]>

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

    清单 V3 及更高版本支持 Promise，但为了实现向后兼容性，我们提供了回调。您不能在同一函数调用中同时使用这两种方法。promise 的解析结果与传递给回调的类型相同。

getPlatformInfo()

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

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

参数

  • callback

    函数（可选）

    callback 参数如下所示： 

    (platformInfo: PlatformInfo) => void

返回

  • Promise<PlatformInfo>

    Chrome 99 及更高版本

    清单 V3 及更高版本支持 Promise，但为了实现向后兼容性，我们提供了回调。您不能在同一函数调用中同时使用这两种方法。promise 的解析结果与传递给回调的类型相同。

getURL()

chrome.runtime.getURL(
  path: string,
)

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

参数

  • 路径

    字符串

    相对于应用/扩展程序安装目录的应用/扩展程序内资源的路径。

返回

  • 字符串

    资源的完全限定网址。

openOptionsPage()

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

打开扩展程序的选项页面（如果可能）。

具体行为可能取决于清单的 options_ui 或 options_page 键，或 Chrome 当时支持的功能。例如，该页面可能会在新标签页中、chrome://extensions 中、应用中打开，或者只会将焦点移至已打开的选项页面。它绝不会导致调用方页面重新加载。

如果您的扩展程序未声明选项页面，或者 Chrome 因其他原因而未能创建选项页面，回调将设置 lastError。

参数

  • callback

    函数（可选）

    callback 参数如下所示： 

    () => void

返回

  • Promise<void>

    Chrome 99 及更高版本

    清单 V3 及更高版本支持 Promise，但为了实现向后兼容性，我们提供了回调。您不能在同一函数调用中同时使用这两种方法。promise 的解析结果与传递给回调的类型相同。

reload()

chrome.runtime.reload()

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

requestUpdateCheck()

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

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

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

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

注意：使用回调调用此函数时，此函数将返回这两个属性作为传递给回调的单独参数，而不是返回一个对象。

参数

  • callback

    函数（可选）

    callback 参数如下所示： 

    (result: object) => void

    • 结果

      对象

      Chrome 109 及更高版本

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

      • 更新检查的结果。

      • 版本

        字符串（选填）

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

返回

  • Promise<object>

    Chrome 109 及更高版本

    清单 V3 及更高版本支持 Promise，但为了实现向后兼容性，我们提供了回调。您不能在同一函数调用中同时使用这两种方法。promise 的解析结果与传递给回调的类型相同。

restart()

chrome.runtime.restart()

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

restartAfterDelay()

Promise Chrome 53 及更高版本 
chrome.runtime.restartAfterDelay(
  seconds: number,
  callback?: function,
)

在指定秒数后，当应用在自助服务终端模式下运行时，重启 ChromeOS 设备。如果在时间结束前再次调用，系统会延迟重新启动。如果使用值 -1 进行调用，系统会取消重新启动。在非自助服务终端模式下，此方法会执行无操作。只有首次调用此 API 的扩展程序才能重复调用此方法。

参数

  • 秒

    数值

    在重新启动设备之前等待的时间（以秒为单位），或 -1 表示取消安排的重新启动。

  • callback

    函数（可选）

    callback 参数如下所示： 

    () => void

返回

  • Promise<void>

    Chrome 99 及更高版本

    清单 V3 及更高版本支持 Promise，但为了实现向后兼容性，我们提供了回调。您不能在同一函数调用中同时使用这两种方法。promise 的解析结果与传递给回调的类型相同。

sendMessage()

prometido 
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

    • Response

      任意

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

返回

  • Promise<any>

    Chrome 99 及更高版本

    清单 V3 及更高版本支持 Promise，但为了实现向后兼容性，我们提供了回调。您不能在同一函数调用中同时使用这两种方法。promise 的解析结果与传递给回调的类型相同。

sendNativeMessage()

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

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

参数

  • 应用

    字符串

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

  • 消息

    对象

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

  • callback

    函数（可选）

    Chrome 99 及更高版本

    callback 参数如下所示： 

    (response: any) => void

    • Response

      任意

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

返回

  • Promise<any>

    Chrome 99 及更高版本

    清单 V3 及更高版本支持 Promise，但为了实现向后兼容性，我们提供了回调。您不能在同一函数调用中同时使用这两种方法。promise 的解析结果与传递给回调的类型相同。

setUninstallURL()

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

设置在卸载时要访问的网址。这可能用于清理服务器端数据、执行分析和实施调查问卷。不得超过 1023 个字符。

参数

  • 网址

    字符串

    在卸载扩展程序后要打开的网址。此网址必须采用 http: 或 https: 协议方案。设置空字符串，以便在卸载时不打开新标签页。

  • callback

    函数（可选）

    Chrome 45 及更高版本

    callback 参数如下所示： 

    () => void

返回

  • Promise<void>

    Chrome 99 及更高版本

    清单 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）建立连接时触发。

参数

onConnectExternal

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

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

参数

onConnectNative

Chrome 76 及更高版本 
chrome.runtime.onConnectNative.addListener(
  callback: function,
)

在从原生应用建立连接时触发。此事件需要 "nativeMessaging" 权限。只有 ChromeOS 支持此功能。

参数

onInstalled

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

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

参数

  • callback

    函数

    callback 参数如下所示： 

    (details: object) => void

    • 详细信息

      对象

      • id

        字符串（选填）

        指示更新的导入的共享模块扩展程序的 ID。只有当“reason”为“shared_module_update”时，此字段才会存在。

      • previousVersion

        字符串（选填）

        表示刚刚更新的扩展程序的旧版本。只有当“reason”为“update”时，此字段才会存在。

      • 分派此事件的原因。

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

    • 返回

      布尔值 | 未定义

onMessageExternal

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

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

参数

  • callback

    函数

    callback 参数如下所示： 

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

    • 消息

      任意

    • 发送者

      MessageSender

    • sendResponse

      函数

      sendResponse 参数如下所示： 

      () => void

    • 返回

      布尔值 | 未定义

onRestartRequired

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

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

参数

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

    • 详细信息

      对象

      • 版本

        字符串

        可用更新的版本号。

onUserScriptConnect

Chrome 115 及更高版本 MV3 及更高版本 
chrome.runtime.onUserScriptConnect.addListener(
  callback: function,
)

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

参数

onUserScriptMessage

Chrome 115 及更高版本 MV3 及更高版本 
chrome.runtime.onUserScriptMessage.addListener(
  callback: function,
)

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

参数

  • callback

    函数

    callback 参数如下所示： 

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

    • 消息

      任意

    • 发送者

      MessageSender

    • sendResponse

      函数

      sendResponse 参数如下所示： 

      () => void

    • 返回

      布尔值 | 未定义