Chrome 浏览器插件 runtime 字段解析

运行时 runtime

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

一、权限

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

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

二、Runtime API 用法

1. 消息传递

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

connect()
onConnect
onConnectExternal
sendMessage()
onMessage
onMessageExternal

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

1.1. 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"});
  });
})();

1.2. 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."});
    });
  });
})();

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

getManifest()
getPlatformInfo()

3. 管理拓展程序生命周期

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

4. 实用功能

getURL()
restart()
restartAfterDelay()

三、类型（Types）

1. ContextFilter

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

1.1. 属性

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

2. ContextType

2.1. 枚举

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

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

4. MessageSender

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

4.1. 属性

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

5. OnInstalledReason

分派此事件的原因。

5.1. 枚举

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

6. OnRestartRequiredReason

分派事件的原因

6.1. 枚举

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

7. PlatformArch

机器的处理器架构。

7.1. 枚举

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

8. PlatformInfo

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

8.1. 属性

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

9. PlatformNaclArch

原生客户端架构

9.1. 枚举

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

10. PlatformOs

运行 Chrome 的操作系统。

10.1. 枚举

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

11. Port

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

11.1. 属性

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

12. RequestUpdateCheckStatus

更新检查的结果

12.1. 枚举

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

四、属性（Properties）

4.1. id

string 扩展程序/应用的 ID。

4.2. lastError

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

五、方法（Methods）

1. connect()

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

1.1. 参数

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

1.2. 返回

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

2. connectNative()

chrome.runtime.connectNative(
  application:
  string,
)

2.1. 参数

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

2.2. 返回

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

3. getBackgroundPage()

仅限 Popup 页面使用

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

3.1. 参数

callback 可选 callback 参数如下所示：

(backgroundPage?: Window)=>void

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

3.2. 返回

Promise<Window|undefined>

4. getContexts()

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

4.1. 参数

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

4.2. 返回

Promise<ExtensionContext[]>

5. getManifest()

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

5.1 返回

object: manifest 详情

6. getPackageDirectoryEntry()

只能在 popup 页面调用

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

6.1. 参数

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

6.2. 返回

Promise

7. getPlatformInfo()

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

7.1. 参数

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

7.2. 返回

Promise<PlatformInfo>

8. getURL()

chrome.runtime.getURL(path:string)

8.1. 参数

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

8.2. 返回

string对应的网址 URL

9. openOptionsPage()

chrome.runtime.openOptionsPage(callback?:function)

9.1. 参数

callback: function 可选()=>void

9.2. 返回

Promise

10. reload()

11. requestUpdateCheck()

chrome.runtime.requestUpdateCheck(callback?:function)

11.1. 参数

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

11.2. 返回

Promise

12. restart()

13. restartAfterDelay()

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

13.1. 参数

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

13.2. 返回

Promise

14. sendMessage()

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

14.1. 参数

extensionId： string 可选要向其发送消息的扩展程序/应用的 ID。如果省略此选项，消息将会发送到您自己的扩展程序/应用。如果您从网页发送消息以实现网络消息，则必须使用此标签。
message: any 要发送的消息
options: object 可选
- includeTlsChannelId: boolean 可选对于正在监听连接事件的进程，是否将 TLS 通道 ID 传递到 onMessageExternal。
callback: function 可选 (response:any)=>void
- response: any 消息的处理程序发送的 JSON 响应对象

14.2. 返回

Promise

15. sendNativeMessage()

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

15.1. 参数

application: string 原生消息传递主机的名称。
message: object 将传递给原生消息传递主机的消息。
callback: function 可选 (response:any)=>void

15.2. 返回

Promise

16. setUninstallURL()

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

16.1. 参数

url: string 要在卸载扩展程序后打开的网址
callback: function（可选）()=>void

16.2. 返回

Promise

六、Events

1. onConnect

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

1.1. 参数

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

2. onConnectExternal

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

2.1. 参数

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

3. onConnectNative

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

3.1. 参数

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

4. onInstalled

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

4.1. 参数

callback: function: (details:object)=>void
- details:object
  - id: string 可选表示已更新的导入共享模块扩展程序的 ID
  - previousVersion: string 可选表示扩展程序的旧版本，只是刚被更新过
  - reason: OnInstalledReason 分派此事件的原因。

5. onMessage

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

5.1. 参数

callback: function:

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

message: any
sender: MessageSender
sendResponse:function：()=>void
return: boolean|undefined

6. onMessageExternal

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

6.1. 参数

callback: fubction

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

message:any
sender:MessageSender
sendResponse:function：()=>void
return: boolean|undefined

7. onRestartRequired

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

7.1. 参数

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

8. onStartup

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

8.1. 参数

callback: function：()=>void

9. onSuspend

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

9.1. 参数

callback: function：()=>void

10. onSuspendCanceled

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

10.1. 参数

callback: function：()=>void

11. onUpdateAvailable

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

11.1. 参数

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

12. onUserScriptConnect

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

12.1. 参数

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

13. onUserScriptMessage

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

13.1. 参数

callback功能callback 参数如下所示：

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

message: any
sender: MessageSender
sendResponse:function：()=>void
return: boolean|undefined

gqkmiss

Chrome 浏览器插件 runtime 字段解析

运行时 runtime

一、权限

二、Runtime API 用法

1. 消息传递

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

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

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

3. 管理拓展程序生命周期

4. 实用功能

三、类型（Types）

1. ContextFilter

1.1. 属性

2. ContextType

2.1. 枚举

3. ExtensionContext

3.1. 属性

4. MessageSender

4.1. 属性

5. OnInstalledReason

5.1. 枚举

6. OnRestartRequiredReason

6.1. 枚举

7. PlatformArch

7.1. 枚举

8. PlatformInfo

8.1. 属性

9. PlatformNaclArch

9.1. 枚举

10. PlatformOs

10.1. 枚举

11. Port

11.1. 属性

12. RequestUpdateCheckStatus

12.1. 枚举

四、属性（Properties）

4.1. id

4.2. lastError

五、方法（Methods）

1. connect()

1.1. 参数

1.2. 返回

2. connectNative()

2.1. 参数

2.2. 返回

3. getBackgroundPage()

3.1. 参数

3.2. 返回

4. getContexts()

4.1. 参数

4.2. 返回

5. getManifest()

5.1 返回

6. getPackageDirectoryEntry()

6.1. 参数

6.2. 返回

7. getPlatformInfo()

7.1. 参数

7.2. 返回

8. getURL()

8.1. 参数

8.2. 返回

9. openOptionsPage()

9.1. 参数

9.2. 返回

10. reload()

11. requestUpdateCheck()

11.1. 参数

11.2. 返回

12. restart()

13. restartAfterDelay()

13.1. 参数

13.2. 返回

14. sendMessage()

14.1. 参数

14.2. 返回

15. sendNativeMessage()

15.1. 参数

15.2. 返回