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()
        
        检索当前扩展程序/应用中运行的后台网页的 JavaScript“window”对象
        
        仅限 Popup 页面使用
        
        chrome.runtime.getBackgroundPage( callback?: function, )
        
        3.1. 参数
        
        callback 可选 callback 参数如下所示：
        (backgroundPage?: Window)=>void
        
        backgroundPage: Window 可选背景网页的 JavaScript“window”对象。
        3.2. 返回
        
        Promise
        4. getContexts()
        
        提取与此扩展程序相关联的有效上下文的相关信息
        
        chrome.runtime.getContexts( filter: ContextFilter, callback?: function, )
        
        4.1. 参数
        
        filter: ContextFilter 用于查找匹配上下文的过滤条件
        callback: function 可选: (contexts: ExtensionContext[])=>void
        contexts: ExtensionContext[] 匹配的上下文
        4.2. 返回
        
        Promise
        5. getManifest()
        
        chrome.runtime.getManifest()
        
        从清单中返回有关应用或扩展程序的详细信息，返回的对象是完整清单文件的序列化内容。
        
        5.1 返回
        
        object: manifest 详情
        6. getPackageDirectoryEntry()
        
        返回软件包目录的 DirectoryEntry。
        
        只能在 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
        8. getURL()
        
        根据路径获取对应的网址 URL
        
        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()
        
        chrome.runtime.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()
        
        chrome.runtime.restart()
        
        当应用在自助服务终端模式下运行时，重启 ChromeOS 设备
        
        13. restartAfterDelay()
        
        当应用在自助服务终端模式下运行时，在特定秒数后重启 ChromeOS 设备
        
        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
        
        从扩展程序进程或内容脚本，通过 runtime.connect 建立连接时触发。
        
        1. onConnect
        
        chrome.runtime.onConnect.addListener( callback:function, )
        
        1.1. 参数
        
        callback：function: (port:Port)=>void
        2. onConnectExternal
        
        从其他扩展程序通过 runtime.connect 建立连接时触发。
        
        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 更新到新版本时触发
        
        chrome.runtime.onInstalled.addListener( callback: function, )
        
        4.1. 参数
        
        callback: function: (details:object)=>void
        details:object
        id: string 可选表示已更新的导入共享模块扩展程序的 ID
        previousVersion: string 可选表示扩展程序的旧版本，只是刚被更新过
        reason: OnInstalledReason 分派此事件的原因。
        5. onMessage
        
        当消息从扩展程序进程通过 runtime.sendMessage 或内容脚本通过 tabs.sendMessage 发送时触发
        
        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
        
        从其他扩展程序/应用发送消息时触发通过 runtime.sendMessage。无法在内容脚本中使用。
        
        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
        
        在 onSuspend 之后发送
        
        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

分类:热门推荐日期:2024-02-01浏览:1评论:0

运行时 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. 返回