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)
reload chrome.runtime.reload()
connect Port chrome.runtime.connect(string extensionId, object connectInfo)
sendMessage chrome.runtime.sendMessage(string extensionId, any message, object options, function responseCallback)
getPlatformInfo chrome.runtime.getPlatformInfo(function callback)
getPackageDirectoryEntry chrome.runtime.getPackageDirectoryEntry(function callback)
事件
onStartup
onInstalled
onConnect
onConnectExternal
onMessage
onMessageExternal

类型

Port

从 Chrome 26 开始支持。

允许与其他页面双向通信的对象。
属性
string name
function disconnect
events.Event onDisconnect
events.Event onMessage
function postMessage
MessageSender (可选)
sender

只有当端口传递给 onConnect/onConnectExternal 监听器时才会存在该属性。

MessageSender

从 Chrome 26 开始支持。

包含有关发送消息或请求的脚本上下文信息的对象。
属性
tabs.Tab (可选)
tab

打开连接的 tabs.Tab(标签页),如果有的话。只有当连接从标签页或内容脚本中打开,并且接收方是应用而不是应用时才会存在这一属性。

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

当前运行百度浏览器的操作系统。

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

指向应用或应用内资源的路径,相对于它的安装目录。

reload

chrome.runtime.reload()

从 Chrome 25 开始支持。

重新加载应用或应用。

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 事件。

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 设为错误消息。

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

当应用第一次安装、更新至新版本或百度浏览器更新至新版本时产生。

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'.

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

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

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

function(any response) {...};
any response

要发送的 JSON 响应对象。

监听器返回值

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