chrome.runtime

描述：	使用 `chrome.runtime` API 获取后台网页、返回清单文件详情、监听并响应应用或扩展程序生命周期内的事件，您还可以使用该 API 将相对路径的 URL 转换为完全限定的 URL。
可用版本：	从 Chrome 22 开始支持。
内容脚本：	支持 connect、getManifest、getURL、id、onConnect、onMessage 和 sendMessage。了解更多
了解更多：	管理应用的生命周期事件页面

摘要

类型
Port
MessageSender
PlatformInfo
属性
lastError
id
方法
getBackgroundPage − `chrome.runtime.getBackgroundPage(function callback)`
getManifest − `object chrome.runtime.getManifest()`
getURL − `string chrome.runtime.getURL(string path)`
setUninstallURL − `chrome.runtime.setUninstallURL(string url)`
reload − `chrome.runtime.reload()`
requestUpdateCheck − `chrome.runtime.requestUpdateCheck(function callback)`
restart − `chrome.runtime.restart()`
connect − `Port chrome.runtime.connect(string extensionId, object connectInfo)`
connectNative − `Port chrome.runtime.connectNative(string application)`
sendMessage − `chrome.runtime.sendMessage(string extensionId, any message, object options, function responseCallback)`
sendNativeMessage − `chrome.runtime.sendNativeMessage(string application, object message, function responseCallback)`
getPlatformInfo − `chrome.runtime.getPlatformInfo(function callback)`
getPackageDirectoryEntry − `chrome.runtime.getPackageDirectoryEntry(function callback)`
事件
onStartup
onInstalled
onSuspend
onSuspendCanceled
onUpdateAvailable
onBrowserUpdateAvailable
onConnect
onConnectExternal
onMessage
onMessageExternal
onRestartRequired

类型

Port

从 Chrome 26 开始支持。

允许与其他页面双向通信的对象。

属性
string	name
function	disconnect
events.Event	onDisconnect
events.Event	onMessage
function	postMessage
MessageSender	（可选） sender	只有当端口传递给 onConnect/onConnectExternal 监听器时才会存在该属性。

MessageSender

从 Chrome 26 开始支持。

包含有关发送消息或请求的脚本上下文信息的对象。

属性
string	（可选） id	打开连接的扩展程序或应用的标识符（如果有的话）。
string	（可选） url	从 Chrome 28 开始支持。打开连接的页面或框架 URL（如果有的话），只有当连接从标签页或内容脚本打开时才会存在这一属性。
string	（可选） tlsChannelId	从 Chrome 32 开始支持。如果扩展程序或应用请求该属性并且可用，则为打开连接的网页的 TLS 通道标识符。

属性

string

（可选）
id

打开连接的扩展程序或应用的标识符（如果有的话）。

string

（可选）
url

从 Chrome 28 开始支持。

打开连接的页面或框架 URL（如果有的话），只有当连接从标签页或内容脚本打开时才会存在这一属性。

string

（可选）
tlsChannelId

从 Chrome 32 开始支持。

如果扩展程序或应用请求该属性并且可用，则为打开连接的网页的 TLS 通道标识符。

PlatformInfo

从 Chrome 36 开始支持。

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

属性
enum of `"mac"`, `"win"`, `"android"`, `"cros"`, `"linux"`, or `"openbsd"`	os	当前运行 Chrome 浏览器的操作系统。
enum of `"arm"`, `"x86-32"`, or `"x86-64"`	arch	计算机的处理器架构。
enum of `"arm"`, `"x86-32"`, or `"x86-64"`	nacl_arch	Native Client 架构，在某些平台上可能和 arch 不同。

属性

object

chrome.runtime.lastError

如果发生错误，在 API 方法的回调函数执行的过程中将会定义该属性。

属性
string	（可选） message	有关发生错误的详情。

string chrome.runtime.id 扩展程序/应用的标识符。

方法

getBackgroundPage


              chrome.runtime.getBackgroundPage(function callback)

获取当前扩展程序/应用中正在运行的后台网页的 JavaScript window 对象。如果后台网页是事件页面，系统会确保在调用回调函数前它已经加载。如果没有后台网页，将会设置错误信息。

参数

function

callback

callback 参数应该是一个如下形式的函数：

function(Window backgroundPage) {...};

Window

（可选）
backgroundPage

后台页面的 JavaScript window 对象。

getManifest


              object
              chrome.runtime.getManifest()

从清单文件中返回有关应用或扩展程序的详情，返回的对象是完整清单文件序列化的结果。

返回值

清单文件详情。

getURL


              string
              chrome.runtime.getURL(string path)

将应用或扩展程序安装目录内的相对路径转换为完全限定的 URL。

参数
string	path	指向应用或扩展程序内资源的路径，相对于它的安装目录。

setUninstallURL


              chrome.runtime.setUninstallURL(string url)

仅用于 Dev 分支。了解更多内容

设置卸载时访问的 URL，可以用来清理服务器上的数据、进行分析以及实现调查。最多不能超过 255 个字符。

参数
string	url	从 Chrome 34 开始支持。

reload


              chrome.runtime.reload()

从 Chrome 25 开始支持。

重新加载应用或扩展程序。

requestUpdateCheck


              chrome.runtime.requestUpdateCheck(function callback)

从 Chrome 25 开始支持。

为当前应用/扩展程序请求检查更新。

参数

function

callback

callback 参数应该是一个如下形式的函数：

function(enum of "throttled", "no_update", or "update_available" status, object details) {...};

enum of "throttled", "no_update", or "update_available"

status

检查更新的结果。

object

（可选）
details

如果更新可用的话，包含有关可用更新的更多信息。

string

version

可用更新的版本。

restart


              chrome.runtime.restart()

从 Chrome 32 开始支持。

如果应用在信息亭模式下运行，则重新启动 Chrome OS 设备，否则不进行任何操作。

connect


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

从 Chrome 26 开始支持。

尝试连接到扩展程序/应用中的连接监听者（例如后台网页）或其他扩展程序/应用，该方法可用于内容脚本连接到所属扩展程序进程、应用/扩展程序之间的通信以及与网页通信。注意，该方法不能连接到内容脚本中的监听者，扩展程序可以通过 tabs.connect 连接到嵌入至标签页中的内容脚本。

参数

string

（可选）
extensionId

您需要连接的扩展程序或应用的标识符，如果省略，则会尝试连接到您自己的扩展程序。如果使用与网页通信的方式从网页发送消息则必须指定该参数。

object

（可选）
connectInfo

string

（可选）
name

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

boolean

（可选）
includeTlsChannelId

从 Chrome 32 开始支持。

TLS 通道标识符是否会传递至 onConnectExternal 事件。

connectNative


                  Port
              chrome.runtime.connectNative(string application)

从 Chrome 28 开始支持。

连接到计算机上的原生应用程序。

参数
string	application	要连接的已注册应用程序名称。

sendMessage


              chrome.runtime.sendMessage(string extensionId, any message, object options, function responseCallback)

从 Chrome 26 开始支持。

向您的扩展程序/应用或另一个扩展程序/应用中的其他事件监听者发送单个消息。与 runtime.connect 类似，但是只发送单个消息（可以有响应）。如果向您自己的扩展程序发送消息，每个网页中都会产生 runtime.onMessage 事件；如果发送至另一个扩展程序则产生 runtime.onMessageExternal 事件。注意，扩展程序不能使用该方法向内容脚本发送消息。要向内容脚本发送消息，请使用 tabs.sendMessage。

参数

string

（可选）
extensionId

您需要发送消息的扩展程序或应用的标识符，如果省略，消息就发送到您自己的扩展程序/应用。如果使用与网页通信的方式从网页发送消息则必须指定该参数。

any message

object

（可选）
options

从 Chrome 32 开始支持。

boolean

（可选）
includeTlsChannelId

TLS 通道标识符是否会传递至 onMessageExternal 事件。

function

（可选）
responseCallback

如果您指定了 responseCallback 参数，它应该是一个如下形式的函数：

function(any response) {...};

any

response

消息处理程序发送的 JSON 响应对象。如果连接到扩展程序的过程中发生错误，调用这一回调函数时将不传递参数，并将 runtime.lastError 设为错误消息。

sendNativeMessage


              chrome.runtime.sendNativeMessage(string application, object message, function responseCallback)

从 Chrome 28 开始支持。

向原生应用程序发送单个消息。

参数

string

application

原生消息通信宿主的名称。

object

message

传递给原生消息通信宿主的消息。

function

（可选）
responseCallback

如果您指定了 responseCallback 参数，它应该是一个如下形式的函数：

function(any response) {...};

any

response

原生消息宿主发送的响应消息。如果连接到原生消息宿主的过程中发生错误，调用回调函数时不会传递参数，同时 runtime.lastError 将设置为错误消息。

getPlatformInfo


              chrome.runtime.getPlatformInfo(function callback)

从 Chrome 29 开始支持。

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

参数

function

callback

调用时返回结果。

callback 参数应该是一个如下形式的函数：

function( PlatformInfo platformInfo) {...};

PlatformInfo

platformInfo

getPackageDirectoryEntry


              chrome.runtime.getPackageDirectoryEntry(function callback)

从 Chrome 29 开始支持。

返回包目录对应的 DirectoryEntry（目录项）。

参数

function

callback

callback 参数应该是一个如下形式的函数：

function(DirectoryEntry directoryEntry) {...};

DirectoryEntry

directoryEntry

事件

onStartup

从 Chrome 23 开始支持。

当安装了该扩展程序的配置文件第一次启动时产生。即使扩展程序以“分离式”隐身模式运行，启动隐身配置文件时也不会产生该事件。

addListener


                    chrome.runtime.onStartup.addListener(function callback)

参数
function	callback	callback 参数应该是一个如下形式的函数： `function() {...};`

onInstalled

当扩展程序第一次安装、更新至新版本或 Chrome 浏览器更新至新版本时产生。

addListener


                    chrome.runtime.onInstalled.addListener(function callback)

参数

function

callback

callback 参数应该是一个如下形式的函数：

function(object details) {...};

object

details

从 Chrome 23 开始支持。

enum of "install", "update", "chrome_update", or "shared_module_update"

reason

分发这一事件的原因。

string

（可选）
previousVersion

表示已更新扩展程序的前一个版本，只有当 reason 为 'update' 时才存在。

string

（可选）
id

从 Chrome 29 开始支持。

Indicates the ID of the imported shared module extension which updated. This is present only if 'reason' is 'shared_module_update'.

onSuspend

在事件页面即将卸载前发送，这样扩展程序就有机会进行清理。注意，由于页面即将卸载，处理该事件时开始的任何异步操作都不能保证完成。如果卸载前事件页面产生了更多活动，将产生 onSuspendCanceled 事件，并且事件页面不会卸载。

addListener


                    chrome.runtime.onSuspend.addListener(function callback)

参数
function	callback	callback 参数应该是一个如下形式的函数： `function() {...};`

onSuspendCanceled

在 onSuspend 之后发送，表示应用最终不会被卸载。

addListener


                    chrome.runtime.onSuspendCanceled.addListener(function callback)

参数
function	callback	callback 参数应该是一个如下形式的函数： `function() {...};`

onUpdateAvailable

从 Chrome 25 开始支持。

当更新可用时产生，然而由于应用当前还在运行，不能立即安装。如果您什么都不做，更新将在后台网页下一次卸载时安装。如果您希望快点安装，您可以显式调用 runtime.reload。如果您的扩展程序使用的是持久存在的后台网页，后台网页始终不会卸载，所以除非您响应该事件并调用 chrome.runtime.reload()，否则只有等到 Chrome 浏览器下一次重新启动时更新才会安装。如果没有处理程序监听该事件，并且您的扩展程序使用持久的后台网页，那么实际行为就和您调用 chrome.runtime.reload() 响应该事件一样。

addListener


                    chrome.runtime.onUpdateAvailable.addListener(function callback)

参数

function

callback

callback 参数应该是一个如下形式的函数：

function(object details) {...};

object

details

可用更新的清单文件详情。

string

version

可用更新的版本号。

onBrowserUpdateAvailable

从 Chrome 33 开始弃用。请使用 runtime.onRestartRequired。

当 Chrome 浏览器的更新可用，但是由于需要浏览器重新启动而没有立即安装时产生。

addListener


                    chrome.runtime.onBrowserUpdateAvailable.addListener(function callback)

参数
function	callback	callback 参数应该是一个如下形式的函数： `function() {...};`

onConnect

从 Chrome 26 开始支持。

当连接从扩展程序进程或内容脚本中发起时产生。

addListener


                    chrome.runtime.onConnect.addListener(function callback)

参数

function

callback

callback 参数应该是一个如下形式的函数：

function( Port port) {...};

Port

port

onConnectExternal

从 Chrome 26 开始支持。

当连接从另一个扩展程序发起时产生。

addListener


                    chrome.runtime.onConnectExternal.addListener(function callback)

参数

function

callback

callback 参数应该是一个如下形式的函数：

function( Port port) {...};

Port

port

onMessage

从 Chrome 26 开始支持。

当消息从扩展程序进程或者内容脚本中发送时产生。

addListener


                    chrome.runtime.onMessage.addListener(function callback)

参数

function

callback

callback 参数应该是一个如下形式的函数：

function(any message, MessageSender sender, function sendResponse) {...};

any

（可选）
message

调用脚本发送的消息。

MessageSender sender

function

sendResponse

当您产生响应时调用（最多一次）的函数，参数可以是任何可转化为 JSON 的对象。如果您在同一个文档中有一个以上的 onMessage 事件处理函数，只有其中一个可以发送响应。当事件处理函数返回时，该函数将失效，除非您在事件处理函数中返回 true，表示您希望通过异步方式发送响应（这样，与另一端之间的消息通道将会保持打开状态，直到调用了 sendResponse）。

sendResponse 参数应该是一个如下形式的函数：

function(any response) {...};

any

response

要发送的 JSON 响应对象。

监听器返回值

( boolean ): 如果您需要在事件监听器返回后再调用 sendResponse 请在事件监听器中返回 true。

onMessageExternal

从 Chrome 26 开始支持。

当消息从另一个扩展程序/应用发送时产生。不能在内容脚本中使用。

addListener


                    chrome.runtime.onMessageExternal.addListener(function callback)

参数

function

callback

callback 参数应该是一个如下形式的函数：

function(any message, MessageSender sender, function sendResponse) {...};

any

（可选）
message

调用脚本发送的消息。

MessageSender sender

function

sendResponse

sendResponse 参数应该是一个如下形式的函数：

function(any response) {...};

any

response

要发送的 JSON 响应对象。

监听器返回值

( boolean ): 如果您需要在事件监听器返回后再调用 sendResponse 请在事件监听器中返回 true。

onRestartRequired

从 Chrome 29 开始支持。

应用或者运行它的设备需要重新启动时产生，应用应该尽早关闭所有窗口，以便开始重新启动。如果应用什么都不做，超过 24 小时的宽限期后会强制重新启动。目前，只有 Chrome OS 的 Kiosk 应用会产生该事件。

addListener


                    chrome.runtime.onRestartRequired.addListener(function callback)

参数

function

callback

callback 参数应该是一个如下形式的函数：

function(enum of "app_update", "os_update", or "periodic" reason) {...};

enum of "app_update", "os_update", or "periodic"

reason

产生该事件的原因。由于应用更新至新版本而需要重新启动时使用 'app_update'，由于浏览器/操作系统更新到新版本而需要重新启动时使用 'os_update'，当系统运行的时间超过企业策略中设置的允许值时使用 'periodic'。