chrome.runtime
Description
使用 chrome.runtime API 检索后台页面、返回有关清单的详细信息，以及侦听和响应应用程序或扩展程序生命周期中的事件。您还可以使用此 API 将 URL 的相对路径转换为完全限定的 URL。
运行时 API 提供了支持扩展可以使用的许多功能领域的方法：
消息传递
- 这些方法支持消息传递，以便您可以与扩展程序的不同部分（例如扩展程序弹出窗口和后台脚本）、其他扩展程序或用户设备上的本机应用程序进行通信。有关主题的概述，请参阅消息传递（Message Passing）。此类别中的方法包括connect, connectNative, sendMessage, 和 sendNativeMessage.。
访问扩展和平台元数据
- 这些方法使您可以检索有关扩展和平台的几个特定元数据。此类别中的方法包括 getBackgroundPage, getManifest, getPackageDirectoryEntry, 和 getPlatformInfo.。
管理扩展生命周期和选项
- 这些方法让您可以对扩展程序执行一些元操作，并向扩展程序用户显示选项页面。此类别中的方法包括 reload, requestUpdateCheck, setUninstallURL, 和 openOptionsPage.
设备重启支持
- 这些方法仅在 Chrome 操作系统上可用，主要用于支持自助服务终端实现。此类别中的方法包括 restart 和 restartAfterDelay.
辅助工具
- 这些方法提供了实用程序，例如将内部资源表示转换为外部格式。此类别中的方法包括getURL
# Manifest
运行时 API 上的大多数方法不需要任何权限即可使用。但是，sendNativeMessage and connectNative 需要在清单中声明 nativeMessaging 权限。
# Examples
# 使用 getURL 向页面添加扩展图像
为了让网页访问托管在另一个域上的资产，它必须指定资源的完整 URL（例如 <img src="https://example.com/logo.png">）。当网页想要包含扩展中包含的资产时也是如此。这里的两个主要区别是扩展的资产必须作为 Web 可访问资源web accessible resources公开，并且通常内容脚本负责注入扩展资产。
此示例显示内容脚本（content script）如何将扩展程序包中的图像添加到已注入（injected）内容脚本的页面。
//// 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);
}# Getting background data into a content script(Getting background data into a content script)
扩展的内容脚本通常需要由扩展的另一部分管理的数据，例如扩展的后台脚本。就像打开同一个网页的两个浏览器窗口一样，这两个上下文不能直接访问彼此的值。相反，扩展可以使用消息传递（message passing）来协调这些不同的上下文。
在这个例子中，内容脚本需要一些来自扩展后台脚本的数据来初始化它的 UI。为了获取这些数据，它向后台传递一条 get-user-data 消息，后台以用户信息的副本作为响应。
//// content.js ////
// 1. Send the background a message requesting the user's data
chrome.runtime.sendMessage('get-user-data', (response) => {
// 3. Got an asynchronous response with the data from the background
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);
}
});# Gathering feedback on uninstall(收集有关卸载的反馈)
许多扩展程序使用卸载后调查来了解扩展程序如何更好地为其用户服务并提高保留率。下面的示例展示了如何将此功能添加到他们的扩展中。
chrome.runtime.onInstalled.addListener(details => {
if (details.reason === chrome.runtime.OnInstalledReason.INSTALL) {
chrome.runtime.setUninstallURL('https://example.com/extension-survey');
}
});Summary
Types
Properties
Methods
Events
Types
MessageSender
一个对象，包含有关发送消息或请求的脚本上下文的信息。
PROPERTIES
frameId
number optional
打开连接的框架（frame）。 0 表示顶级框架，正值表示子框架。这只会在设置
tab时设置。id
string optional
打开连接的扩展程序或应用程序的 ID（如果有）。
nativeApplication
string optional
Chrome 74+打开连接的本机应用程序的名称（如果有）。
origin
string optional
Chrome 80+打开连接的页面或框架的来源。它可以与 url 属性不同（例如 about:blank），也可以是不透明的（例如，沙盒 iframe）。如果我们不能立即从 URL 中分辨出来，这对于确定来源是否可信很有用。
tab
Tab optional
打开连接的 tabs.Tab（如果有）。此属性仅在从选项卡（包括内容脚本）打开连接时出现，并且仅当接收器是扩展程序而不是应用程序时才会出现。
tlsChannelId
string optional
打开连接的页面或框架的 TLS 通道 ID（如果扩展程序或应用程序请求并且可用）。
url
string optional
打开连接的页面或框架的 URL。如果发件人在 iframe 中，它将是 iframe 的 URL，而不是托管它的页面的 URL。
OnInstalledReason
Chrome 44+
正在调度此事件的原因。
TYPE
"install", "update", "chrome_update", or "shared_module_update"
OnRestartRequiredReason
Chrome 44+
调度事件的原因。 'app_update' 在需要重新启动时使用，因为应用程序已更新到较新的版本。'os_update' 在需要重新启动时使用，因为浏览器/操作系统已更新到更新版本。当系统运行时间超过企业策略中设置的允许正常运行时间时，使用“定期(periodic)”。
TYPE
"app_update", "os_update", or "periodic"
PlatformArch
Chrome 44+
机器的处理器架构。
TYPE
"arm", "arm64", "x86-32", "x86-64", "mips", or "mips64"
PlatformInfo
一个包含当前平台信息的对象。
PROPERTIES
arch
机器的处理器架构。
nacl_arch
本机客户端架构。这可能与某些平台上的 arch 不同。
os
运行 Chrome 的操作系统。
PlatformNaclArch
Chrome 44+
本机客户端架构。这可能与某些平台上的 arch 不同。
TYPE
"arm", "x86-32", "x86-64", "mips", or "mips64"
PlatformOs
Chrome 44+
运行 Chrome 的操作系统。
TYPE
"mac", "win", "android", "cros", "linux", or "openbsd"
Port
允许与其他页面进行双向通信的对象。有关详细信息，请参阅长期连接（Long-lived connections）。
PROPERTIES
name
string
在调用
runtime.connect时指定的端口名称。onDisconnect
event
当端口与另一端断开连接时触发。如果端口因错误而断开连接，则可以设置
runtime.lastError。如果端口通过断开（disconnect）连接关闭，则此事件仅在另一端触发。此事件最多触发一次（另请参阅端口生存期Port lifetime）。onDisconnect.addListener 函数例如：
(callback: function) => {...}
onMessage
event
当端口的另一端调用 postMessage 时会触发此事件。
onMessage.addListener 函数如下所示：
(callback: function) => {...}
sender
MessageSender optional
此属性只会出现在传递给 onConnect / onConnectExternal / onConnectNative 侦听器的端口上。
disconnect
function
立即断开端口。在已断开连接的端口上调用
disconnect()无效。当一个端口断开连接时，不会有新的事件被分派到这个端口。disconnect功能如下所示：() => {...}
postMessage
function
向端口的另一端发送消息。如果端口断开连接，则会引发错误。
postMessage函数如下所示：(message: any) => {...}
message
any
Chrome 52+要发送的消息。这个对象应该是 JSON-ifiable。
RequestUpdateCheckStatus
Chrome 44+
更新检查的结果。
TYPE
"throttled", "no_update", or "update_available"
Properties
id
扩展程序/应用程序的 ID。
TYPE
string
lastError
如果出现错误，这将在 API 方法回调期间定义
TYPE
object
PROPERTIES
message
string optional
有关发生的错误的详细信息。
Methods
connect
chrome.runtime.connect(
extensionId?: string,
connectInfo?: object,
)尝试连接以连接扩展程序/应用程序（例如后台页面）或其他扩展程序/应用程序中的侦听器。这对于连接到它们的扩展进程、应用间/扩展通信和网络消息web messaging传递的内容脚本很有用。请注意，这不会连接到内容脚本中的任何侦听器。请注意，这不会连接到内容脚本中的任何侦听器。扩展可以通过 tabs.connect 连接到嵌入在标签中的内容脚本。
PARAMETERS
extensionId
string optional
要连接的扩展程序或应用程序的 ID。如果省略，将尝试使用您自己的扩展名进行连接。如果从网页发送消息以进行 Web 消息传递web messaging，则需要。
connectInfo
object optional
includeTlsChannelId
boolean optional
对于侦听连接事件的进程，TLS 通道 ID 是否将传递到
onConnectExternal中。name
string optional
将被传递给监听连接事件的进程的
onConnect。
RETURNS
可以通过其发送和接收消息的端口。如果扩展程序/应用程序不存在，则会触发端口的 onDisconnect 事件。
connectNative
chrome.runtime.connectNative(
application: string,
)连接到主机中的本机应用程序。有关更多信息，请参阅本机消息传递（Native Messaging）。
PARAMETERS
application
string
要连接的已注册应用程序的名称。
RETURNS
应用程序可以通过其发送和接收消息的端口
getBackgroundPage
chrome.runtime.getBackgroundPage( callback: function, )
Foreground only
检索在当前扩展程序/应用程序中运行的后台页面的 JavaScript 'window' 对象。如果后台页面是一个事件页面，系统会在调用回调之前确保它被加载。如果没有后台页面，则设置错误。
PARAMETERS
callback
function
The
callbackparameter looks like:(backgroundPage?: Window) => void
backgroundPage
Window optional
背景页面的 JavaScript 'window' 对象。
getManifest
chrome.runtime.getManifest()
从清单（manifest file）返回有关应用程序或扩展程序的详细信息。返回的对象是完整清单文件的序列化。
RETURNS
object
清单详情。
getPackageDirectoryEntry
chrome.runtime.getPackageDirectoryEntry(
callback: function,
)Foreground only
返回包目录的 DirectoryEntry。
PARAMETERS
callback
function
The
callbackparameter looks like:(directoryEntry: DirectoryEntry) => voiddirectoryEntry
DirectoryEntry
getPlatformInfo
chrome.runtime.getPlatformInfo(
callback: function,
)返回有关当前平台的信息。
PARAMETERS
callback
function
The
callbackparameter looks like:(platformInfo: PlatformInfo) => voidplatformInfo
getURL
chrome.runtime.getURL(
path: string,
)将应用程序/扩展安装目录中的相对路径转换为完全限定的 URL。
PARAMETERS
path
string
应用程序/扩展程序中资源的路径，表示相对于其安装目录。
RETURNS
string
资源的完全限定 URL。
openOptionsPage
chrome.runtime.openOptionsPage(
callback?: function,
)如果可能，打开扩展程序的选项页面。
确切的行为可能取决于清单的 options_ui 或 options_page 键，或者当时 Chrome 刚好支持什么。例如，该页面可能会在新标签页、chrome://extensions 中、应用程序中打开，或者它可能只关注打开的选项页面。它永远不会导致调用者页面重新加载。
如果您的扩展程序未声明选项页面，或者 Chrome 由于其他原因未能创建选项页面，则回调将设置 lastError。
PARAMETERS
callback
function optional
The
callbackparameter looks like:() => void
reload
chrome.runtime.reload()
重新加载应用程序或扩展程序。自助服务终端(kiosk)模式不支持此方法。对于自助服务终端(kiosk)模式，请使用 chrome.runtime.restart() 方法。
requestUpdateCheck
chrome.runtime.requestUpdateCheck(
callback: function,
)请求立即对此应用程序/扩展程序进行更新检查。
重要提示：大多数扩展程序/应用程序不应使用此方法，因为 Chrome 已经每隔几个小时进行一次自动检查，并且您可以侦听 runtime.onUpdateAvailable 事件而无需调用 requestUpdateCheck。
这种方法只适合在非常有限的情况下调用，例如，如果您的扩展程序/应用程序与后端服务通信，并且后端服务确定客户端扩展程序/应用程序版本非常过时，并且您想提示用户进行更新。requestUpdateCheck 的大多数其他用途，例如基于重复计时器无条件调用它，可能只会浪费客户端、网络和服务器资源。
PARAMETERS
callback
function
The
callbackparameter looks like:(status: RequestUpdateCheckStatus, details?: object) => voidstatus
更新检查的结果。
details
object optional
如果有可用更新，则其中包含有关可用更新的更多信息。
version
string
可用更新的版本。
restart
chrome.runtime.restart()当应用在自助服务终端(kiosk)模式下运行时重新启动 ChromeOS 设备。否则，它是无操作的。
restartAfterDelay
chrome.runtime.restartAfterDelay(
seconds: number,
callback?: function,
)Chrome 53+
当应用在给定秒数后以自助服务终端模式运行时，重新启动 ChromeOS 设备。如果在时间结束之前再次调用，则重启将被延迟。如果以 -1 的值调用，则重新启动将被取消。这是非自助服务终端模式下的空操作。只允许第一个扩展重复调用来调用这个 API。
PARAMETERS
seconds
number
在重新启动设备之前等待的时间（以秒为单位），或 -1 以取消计划的重新启动。
callback
function optional
The
callbackparameter looks like:() => void
sendMessage
chrome.runtime.sendMessage(
extensionId?: string,
message: any,
options?: object,
responseCallback?: function,
)向您的扩展程序/应用程序或其他扩展程序/应用程序中的事件侦听器发送一条消息。与 runtime.connect 类似，但只发送一条消息，带有可选的响应。如果发送到您的扩展，runtime.onMessage 事件将在您的扩展的每一帧中被触发（发送者的帧除外），或者 runtime.onMessageExternal，如果是不同的扩展。请注意，扩展无法使用此方法向内容脚本发送消息。要将消息发送到内容脚本，请使用 tabs.sendMessage。
PARAMETERS
extensionId
string optional
要将消息发送到的扩展程序/应用程序的 ID。如果省略，消息将发送到您自己的扩展程序/应用程序。如果从网页发送消息以进行 Web 消息传递web messaging，则需要。
message
any
要发送的消息。此消息应该是一个 JSON-ifiable 对象。
options
object optional
includeTlsChannelId
boolean optional
对于侦听连接事件的进程，TLS 通道 ID 是否将传递到 onMessageExternal 中。
responseCallback
function optional
The
responseCallbackparameter looks like:(response: any) => voidresponse
any
消息处理程序发送的 JSON 响应对象。如果在连接到扩展时发生错误，将不带参数调用回调，并且
runtime.lastError将设置为错误消息。
sendNativeMessage
chrome.runtime.sendNativeMessage(
application: string,
message: object,
responseCallback?: function,
)向本机应用程序发送一条消息。
PARAMETERS
application
string
本机消息传递主机的名称。
message
object
将传递到本机消息传递主机的消息。
responseCallback
function optional
The
responseCallbackparameter looks like:(response: any) => voidresponse
any
本地消息传递主机发送的响应消息。如果在连接到本机消息传递主机时发生错误，将不带参数调用回调，并且
runtime.lastError将设置为错误消息。
setUninstallURL
chrome.runtime.setUninstallURL(
url: string,
callback?: function,
)设置卸载时要访问的 URL。这可用于清理服务器端数据、进行分析和实施调查。最多 255 个字符。
PARAMETERS
url
string
卸载扩展后打开的 URL。此 URL 必须具有 http: 或 https: 方案。设置一个空字符串以在卸载时不打开新选项卡。
callback
function optional
Chrome 45+
The
callbackparameter looks like:() => void
Events
onBrowserUpdateAvailable
chrome.runtime.onBrowserUpdateAvailable.addListener(
callback: function,
)Deprecated
请使用 runtime.onRestartRequired。
当 Chrome 更新可用时触发，但由于需要重新启动浏览器而不会立即安装。
PARAMETERS
callback
function
The
callbackparameter looks like:() => void
onConnect
chrome.runtime.onConnect.addListener(
callback: function,
)当从扩展进程或内容脚本（通过 runtime.connect）建立连接时触发。
PARAMETERS
callback
function
The
callbackparameter looks like:(port: Port) => voidport
onConnectExternal
chrome.runtime.onConnectExternal.addListener(
callback: function,
)当从另一个扩展（通过 runtime.connect）建立连接时触发。
PARAMETERS
callback
function
The
callbackparameter looks like:(port: Port) => voidport
onConnectNative
chrome.runtime.onConnectNative.addListener(
callback: function,
)Chrome 74+
当从本机应用程序建立连接时触发。目前仅支持 Chrome 操作系统。
PARAMETERS
callback
function
The
callbackparameter looks like:(port: Port) => voidport
onInstalled
chrome.runtime.onInstalled.addListener(
callback: function,
)在首次安装扩展程序、扩展程序更新到新版本以及 Chrome 更新到新版本时触发。
PARAMETERS
callback
function
The
callbackparameter looks like:(details: object) => voiddetails
object
id
string optional
表示更新的导入共享模块扩展的ID。仅当“原因”为“shared_module_update”时才存在。
previousVersion
string optional
表示刚刚更新的扩展的先前版本。仅当“原因(reason)”为“更新(update)”时才存在。
reason
正在调度此事件的原因。
onMessage
chrome.runtime.onMessage.addListener(
callback: function,
)当从扩展进程（通过 runtime.sendMessage）或内容脚本（通过 tabs.sendMessage）发送消息时触发。
PARAMETERS
callback
function
The
callbackparameter looks like:(message: any, sender: MessageSender, sendResponse: function) => boolean | undefined
message
any
sender
sendResponse
function
The
sendResponseparameter looks like:() => voidreturns
boolean | undefined
onMessageExternal
chrome.runtime.onMessageExternal.addListener(
callback: function,
)从另一个扩展程序/应用程序（通过 runtime.sendMessage）发送消息时触发。不能在内容脚本中使用。
PARAMETERS
callback
function
The
callbackparameter looks like:(message: any, sender: MessageSender, sendResponse: function) => boolean | undefined
message
any
sender
sendResponse
function
The
sendResponseparameter looks like:() => voidreturns
boolean | undefined
onRestartRequired
chrome.runtime.onRestartRequired.addListener(
callback: function,
)当应用程序或运行它的设备需要重新启动时触发。该应用程序应在方便的最早时间关闭其所有窗口，以便重新启动。如果应用程序不执行任何操作，则会在 24 小时宽限期过后强制重启。目前，此事件仅针对 Chrome 操作系统自助服务终端应用触发。
PARAMETERS
callback
function
The
callbackparameter looks like:(reason: OnRestartRequiredReason) => void
reason
onStartup
chrome.runtime.onStartup.addListener(
callback: function,
)当安装了此扩展的配置文件首次启动时触发。启动隐身配置文件时，不会触发此事件，即使此扩展程序在“拆分(split)”隐身模式下运行。
PARAMETERS
callback
function
The
callbackparameter looks like:() => void
onSuspend
chrome.runtime.onSuspend.addListener(
callback: function,
)在卸载之前发送到事件页面。这为扩展程序提供了进行一些清理的机会。请注意，由于页面正在卸载，因此在处理此事件时启动的任何异步操作都不能保证完成。如果事件页面在卸载之前发生更多活动，则将发送 onSuspendCanceled 事件并且页面不会被卸载。
PARAMETERS
callback
function
The
callbackparameter looks like:() => void
onSuspendCanceled
chrome.runtime.onSuspendCanceled.addListener(
callback: function,
)在 onSuspend 之后发送，表示应用程序最终不会被卸载。
PARAMETERS
callback
function
The
callbackparameter looks like:() => void
onUpdateAvailable
chrome.runtime.onUpdateAvailable.addListener(
callback: function,
)当有可用更新但未立即安装时触发，因为应用程序当前正在运行。如果你什么都不做，更新将在下一次后台页面卸载时安装，如果你想更快地安装它，你可以显式调用 chrome.runtime.reload()。如果您的扩展程序使用持久的后台页面，那么后台页面当然永远不会被卸载，因此，除非您手动调用 chrome.runtime.reload() 以响应此事件，否则在 Chrome 下次重新启动之前不会安装更新。如果没有处理程序正在侦听此事件，并且您的扩展程序具有持久的后台页面，则它的行为就像调用 chrome.runtime.reload() 以响应此事件一样。
PARAMETERS
callback
function
The
callbackparameter looks like:(details: object) => voiddetails
object
version
string
可用更新的版本号。
By.一粒技术服务