运行时 runtime

使用 chrome.runtime API 检索 Service Worker，返回有关 manifest.json 的详细信息
监听和响应应用或扩展程序生命周期中的事件
还可以使用此 API 将网址的相对路径转换为完整的一个 URL

一、权限

Runtime API 上的大多数方法都不需要任何权限但是 sendNativeMessage() 和 **connectNative() **除外，它们需要 nativeMessaging 权限。

{
  "permissions": [
    "nativeMessaging"
  ],
}

二、Runtime API 用法

消息传递

可以使用以下方法和事件与扩展程序中的不同上下文以及其他扩展程序进行通信：

connect()
onConnect
onConnectExternal
sendMessage()
onMessage
onMessageExternal

扩展程序还可以使用 connectNative() 和 sendNativeMessage() 将消息传递给用户设备上的原生应用。

Content-scripts.js 文件发送和接收消息

(async () => {
  // 使用 sendMessage 从 Content 发送消息
  const response = await chrome.runtime.sendMessage({greeting: "hello"});
  console.log(response);

  // 使用 onMessage.addListener Content 接收消息
  chrome.runtime.onMessage.addListener(function(request, sender, sendResponse) {
    console.log(sender.tab ? "from a content script:" + sender.tab.url : "from the extension");
    if (request.greeting === "hello") sendResponse({farewell: "goodbye"});
  });


  // 使用 connect 从 Content 发送和接收消息
  var port = chrome.runtime.connect({name: "knockknock"});
  port.postMessage({joke: "Knock knock"});
  port.onMessage.addListener(function(msg) {
    if (msg.question === "Who's there?")
      port.postMessage({answer: "Madame"});
    else if (msg.question === "Madame who?")
      port.postMessage({answer: "Madame... Bovary"});
  });
})();

service-worker.js 文件发送和接收消息

(async () => {
  // 使用 sendMessage 从 background/service-worker 发送消息
  const [tab] = await chrome.tabs.query({active: true, lastFocusedWindow: true});
  const response = await chrome.tabs.sendMessage(tab.id, {greeting: "hello"});
  console.log(response);

  // 使用 onMessage.addListener background/service-worker 接收消息
  chrome.runtime.onMessage.addListener(function(request, sender, sendResponse) {
    console.log(sender.tab ? "from a content script:" + sender.tab.url : "from the extension");
    if (request.greeting === "hello") sendResponse({farewell: "goodbye"});
  });


  // 使用 onConnect background/service-worker 接收消息和发送
  chrome.runtime.onConnect.addListener(function(port) {
    console.assert(port.name === "knockknock");
    port.onMessage.addListener(function(msg) {
      if (msg.joke === "Knock knock")
        port.postMessage({question: "Who's there?"});
      else if (msg.answer === "Madame")
        port.postMessage({question: "Madame who?"});
      else if (msg.answer === "Madame... Bovary")
        port.postMessage({question: "I don't get it."});
    });
  });
})();

访问拓展程序和平台元数据

getManifest()
getPlatformInfo()

管理拓展程序生命周期

onInstalled
onStartup
openOptionsPage()
reload()
requestUpdateCheck()
setUninstallURL()

实用功能

getURL()
restart()
restartAfterDelay()

三、类型（Types）

ContextFilter

用于匹配特定扩展程序上下文的过滤器。
匹配的上下文必须与所有指定的过滤条件匹配；任何未指定的过滤条件均匹配所有可用的上下文。因此，“{}”的过滤器将匹配所有可用上下文。

属性

**contextIds: string[] 可选 **此上下文的唯一标识符
**contextTypes: ContextType[] 可选 **对应的上下文类型。
**documentIds: string[] 可选 **与此上下文关联的文档的 UUID
**documentOrigins: string[] 可选 **与此上下文关联的文档的来源
**documentUrls: string[] 可选 **与此上下文关联的文档的网址
**frameIds: number[] 可选 **此上下文的帧 ID
**incognito: boolean 可选 **上下文是否与无痕模式个人资料相关联。
**tabIds: number[] 可选 **此上下文的标签页 ID
**windowIds: number[] 可选 **此上下文的窗口 ID

ContextType

枚举

TAB: 以标签页形式指定上下文类型
POPUP: 将上下文类型指定为扩展程序弹出式窗口
BACKGROUND: 将上下文类型指定为 Service Worker。
OFFSCREEN_DOCUMENT: 将上下文类型指定为屏幕外文档。
SIDE_PANEL: 以侧边栏形式指定上下文类型。

ExtensionContext

上下文托管扩展程序内容

3.1. 属性

**contextId: string **此上下文的唯一标识符
**contextType: **ContextType 对应的上下文类型
**documentId: string 可选 **与此上下文关联的文档的 UUID
**documentOrigin: string 可选 **与此上下文关联的文档的来源
**documentUrl: string 可选 **与此上下文关联的文档的网址
**frameId: number **此上下文的帧 ID，如果该上下文未托管在帧中，则为 -1
**incognito: boolean **上下文是否与无痕模式个人资料相关联
**tabId: number **此上下文的标签页 ID，如果该上下文未托管在标签页中，则为 -1
**windowId: number **此上下文的窗口 ID，如果此上下文未托管在窗口中，则为 -1

MessageSender

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

4.1. 属性

**打开连接的文档的 UUID。
**documentLifecycle: string 可选 **打开连接的文档在端口创建时所处的生命周期
**frameId: number 可选 **打开连接的帧，0 表示顶级帧，正值表示子帧
**id: string 可选 **打开连接的扩展程序或应用的 ID。
**nativeApplication: string 可选 **打开连接的原生应用的名称。
**origin: string 可选 **打开连接的网页或框架的来源
**tab: Tab 可选 **打开连接的 tabs.Tab
**tlsChannelId: string 可选 **打开连接的页面或框架的 TLS 通道 ID（
**url: string 可选 **打开连接的网页或框架的网址

OnInstalledReason

分派此事件的原因。

5.1. 枚举

install: 将事件原因指定为安装。
update: 以扩展程序更新的形式指定事件原因。
chrome_update: 将事件原因指定为 Chrome 更新。
shared_module_update: 将事件原因指定为共享模块的更新。

OnRestartRequiredReason

分派事件的原因

6.1. 枚举

app_update: 将事件原因指定为应用更新。
os_update: 将事件原因指定为操作系统更新。
periodic: 将事件原因指定为应用定期重启。

PlatformArch

机器的处理器架构。

7.1. 枚举

arm: 将处理器架构指定为 arm。
arm64: 将处理器架构指定为 arm64。
x86-32: 将处理器架构指定为 x86-32。
x86-64: 将处理器架构指定为 x86-64。
mips: 以 mips 形式指定处理器架构。
mips64: 以 mips64 形式指定处理器架构。

PlatformInfo

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

属性

**arch: **PlatformArch 机器的处理器架构。
**nacl_arch: **PlatformNaclArch 原生客户端架构
**os: **PlatformOs 运行 Chrome 的操作系统。

PlatformNaclArch

原生客户端架构

9.1. 枚举

arm: 将原生客户端架构指定为 arm。
x86-32: 将原生客户端架构指定为 x86-32。
x86-64: 将原生客户端架构指定为 x86-64。
mips: 以 mips 形式指定原生客户端架构。
mips64: 以 mips64 形式指定原生客户端架构。

PlatformOs

运行 Chrome 的操作系统。

10.1. 枚举

mac: 指定 MacOS 操作系统。
win: 指定了 Windows 操作系统。
android: 用于指定 Android 操作系统。
cros: 指定 Chrome 操作系统。
linux: 用于指定 Linux 操作系统。
openbsd: 指定 OpenBSD 操作系统。
fuchsia: 用于指定 Fuchsia 操作系统。

Port

允许与其他网页进行双向通信的对象

属性

**name: string **端口的名称，在对 runtime.connect 的调用中指定
**onDisconnect: Event **在端口与另一端断开连接时触发。
**onMessage: Event **端口的另一端调用 postMessage 时会触发此事件
sender: MessageSender 可选 此属性将仅出现在传递到 onConnect / onConnectExternal / onConnectNative 监听器的端口上。
**disconnect: void **立即断开该端口的连接
**postMessage: void **向端口的另一端发送消息。如果端口断开连接，则会抛出错误

RequestUpdateCheckStatus

更新检查的结果

枚举

throttled: 指定状态检查已受到限制。如果您在短时间内反复检查，就可能会发生这种情况
no_update: 指定没有可安装的更新。
update_available: 指明有要安装的可用更新。

四、属性（Properties）

4.1. id

string 扩展程序/应用的 ID。

4.2. lastError

Object 如果 API 函数调用失败，则填充错误消息，否则将填充未定义状态
- message: string 可选所发生的错误的详细信息

五、方法（Methods）

connect()

尝试连接扩展程序/应用（例如后台网页）或其他扩展程序/应用中的监听器

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

参数

**extensionId: string 可选 **要连接的扩展程序或应用的 ID
connectInfo: object 可选
- **includeTlsChannelId: boolean 选填 **对于正在监听连接事件的进程，是否将 TLS 通道 ID 传递到 onConnectExternal。
- **name: string 可选 **对于正在监听连接事件的进程，此参数将传递到 onConnect。

Port 可以发送和接收消息的端口

connectNative()

连接到主机中的原生应用

chrome.runtime.connectNative(
  application:
  string,
)

参数

**application: string **要连接的已注册应用的名称。

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

getBackgroundPage()

检索当前扩展程序/应用中运行的后台网页的 JavaScript“window”对象

仅限 Popup 页面使用

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

参数

**callback 可选 **callback 参数如下所示：

(backgroundPage?: Window)=>void

**backgroundPage: Window 可选 **背景网页的 JavaScript“window”对象。

Promise<Window|undefined>

getContexts()

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

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

参数

**filter: **ContextFilter 用于查找匹配上下文的过滤条件
callback: function 可选: (contexts: ExtensionContext[])=>void
- **contexts: ExtensionContext[] **匹配的上下文

Promise<ExtensionContext[]>

getManifest()

chrome.runtime.getManifest()

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

**object： **manifest 详情

getPackageDirectoryEntry()

返回软件包目录的 DirectoryEntry。

只能在 popup 页面调用

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

参数

callback：function 可选callback 参数如下所示：(directoryEntry:DirectoryEntry)=>void
- directoryEntry：DirectoryEntry

Promise

getPlatformInfo()

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

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

参数

callback：function 可选 (platformInfo:PlatformInfo)=>void
- **platformInfo: **PlatformInfo

Promise<PlatformInfo>

getURL()

根据路径获取对应的网址 URL

chrome.runtime.getURL(path:string)

参数

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

**string **对应的网址 URL

openOptionsPage()

打开扩展程序的选项页面

chrome.runtime.openOptionsPage(callback?:function)

参数

callback: function 可选()=>void

Promise

reload()

chrome.runtime.reload()

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

requestUpdateCheck()

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

chrome.runtime.requestUpdateCheck(callback?:function)

参数

callback: function 可选 (result:object)=>void
- **result: object **
  - **status: **RequestUpdateCheckStatus 更新检查的结果。
  - **version: string 可选 **如果有可用更新，则此字段包含可用更新的版本。

Promise
restart()

chrome.runtime.restart()

当应用在自助服务终端模式下运行时，重启 ChromeOS 设备

restartAfterDelay()

当应用在自助服务终端模式下运行时，在特定秒数后重启 ChromeOS 设备

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

参数

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

**callback: function 可选 **()=>void

返回

Promise

sendMessage()

向扩展程序/应用或其他扩展程序/应用中的事件监听器发送一条消息

chrome.runtime.sendMessage( extensionId?: string, message: any, options?: object, callback?: function, )

参数

**extensionId： string 可选 **要向其发送消息的扩展程序/应用的 ID。如果省略此选项，消息将会发送到您自己的扩展程序/应用。如果您从网页发送消息以实现网络消息，则必须使用此标签。

message: any 要发送的消息

options: object 可选

**includeTlsChannelId: boolean 选填 **对于正在监听连接事件的进程，是否将 TLS 通道 ID 传递到 onMessageExternal。

callback: function 可选 (response:any)=>void

**response: any **消息的处理程序发送的 JSON 响应对象

返回

Promise

sendNativeMessage()

向原生应用发送单条消息。

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

参数

**application: string **原生消息传递主机的名称。

**message: object **将传递给原生消息传递主机的消息。

callback: function 可选 (response:any)=>void

返回

Promise

setUninstallURL()

设置卸载后要访问的网址

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

参数

**url: string **要在卸载扩展程序后打开的网址

callback: function（可选）()=>void

返回

Promise

六、Events

从扩展程序进程或内容脚本，通过 runtime.connect 建立连接时触发。

onConnect

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

参数

callback：function: (port:Port)=>void

onConnectExternal

从其他扩展程序通过 runtime.connect 建立连接时触发。

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

参数

callback: function: (port:Port)=>void

onConnectNative

从原生应用建立连接时触发

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

参数

callback: function: (port:Port)=>void

onInstalled

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

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

参数

callback: function: (details:object)=>void

details:object

**id: string 可选 **表示已更新的导入共享模块扩展程序的 ID

**previousVersion: string 可选 **表示扩展程序的旧版本，只是刚被更新过

**reason: **OnInstalledReason 分派此事件的原因。

onMessage

当消息从扩展程序进程通过 runtime.sendMessage 或内容脚本通过 tabs.sendMessage 发送时触发

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

参数

**callback: function: **

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

message: any

sender: MessageSender

sendResponse:function：()=>void

return: boolean|undefined

onMessageExternal

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

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

参数

callback: fubction

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

message:any

sender:MessageSender

sendResponse:function：()=>void

return: boolean|undefined

onRestartRequired

当应用或运行该应用的设备需要重启时触发

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

参数

callback: function: (reason: OnRestartRequiredReason)=>void

onStartup

在安装了此扩展程序的配置文件首次启动时触发

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

参数

callback: function：()=>void

onSuspend

在取消加载之前被发送到事件页面

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

参数

callback: function：()=>void

onSuspendCanceled

在 onSuspend 之后发送

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

参数

callback: function：()=>void

onUpdateAvailable

有可用更新，但由于应用当前正在运行而未立即安装时触发

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

参数

callback: function：(details:object)=>void

onUserScriptConnect

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

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

参数

callback: function：(port:Port)=>void

onUserScriptMessage

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

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

参数

callback功能callback 参数如下所示：

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

message: any

sender: MessageSender

sendResponse:function：()=>void

return: boolean|undefined

Chrome 浏览器插件 runtime 字段解析