跳到主要内容

contextBridge

历史

在隔离的上下文之间创建一个安全的、双向的、同步的桥

进程：渲染器

下面给出了一个从隔离的预加载脚本向渲染器公开 API 的示例

// Preload (Isolated World)
const { contextBridge, ipcRenderer } = require('electron')

contextBridge.exposeInMainWorld(
  'electron',
  {
    doThing: () => ipcRenderer.send('do-a-thing')
  }
)
// Renderer (Main World)

window.electron.doThing()

词汇表​

主世界​

“主世界”是您的主渲染器代码在其中运行的 JavaScript 上下文。默认情况下，您在渲染器中加载的页面在此世界中执行代码。

隔离世界​

当您的 webPreferences 中启用了 contextIsolation 时（这是自 Electron 12.0.0 以来的默认行为），您的 preload 脚本在“隔离世界”中运行。您可以在 安全 文档中阅读有关上下文隔离及其影响的更多信息。

方法​

contextBridge 模块具有以下方法

contextBridge.exposeInMainWorld(apiKey, api)​

  • apiKey 字符串 - 将 API 注入到 window 上的键。API 将可以在 window[apiKey] 上访问。
  • api 任何 - 您的 API，有关此 API 可以是什么以及它是如何工作的更多信息，请参见下文。

contextBridge.exposeInIsolatedWorld(worldId, apiKey, api)​

  • worldId 整数 - 将 API 注入到的世界的 ID。0 是默认世界，999 是 Electron 的 contextIsolation 功能使用的世界。使用 999 将公开预加载上下文的对象。我们建议在创建隔离世界时使用 1000+。
  • apiKey 字符串 - 将 API 注入到 window 上的键。API 将可以在 window[apiKey] 上访问。
  • api 任何 - 您的 API，有关此 API 可以是什么以及它是如何工作的更多信息，请参见下文。

contextBridge.executeInMainWorld(executionScript) 实验性​

  • executionScript 对象
    • func (...args: any[]) => any - 要执行的 JavaScript 函数。该函数将被序列化，这意味着任何绑定的参数和执行上下文都将丢失。
    • args any[]（可选）- 传递给所提供函数的参数数组。这些参数将根据 支持的类型表 在世界之间复制。

返回 any - 在主世界中执行函数的结果值的副本。有关如何在世界之间复制值，请参阅该表。

用法​

API​

提供给 exposeInMainWorld 的 api 必须是 Function、string、number、Array、boolean 或一个对象，其键是字符串，值是 Function、string、number、Array、boolean 或另一个满足相同条件的嵌套对象。

Function 值被代理到另一个上下文，所有其他值都被复制和冻结。API 中发送的任何数据/基元都变为不可变的，并且桥两侧的更新不会导致另一侧的更新。

下面显示了一个复杂 API 的示例

const { contextBridge, ipcRenderer } = require('electron')

contextBridge.exposeInMainWorld(
  'electron',
  {
    doThing: () => ipcRenderer.send('do-a-thing'),
    myPromises: [Promise.resolve(), Promise.reject(new Error('whoops'))],
    anAsyncFunction: async () => 123,
    data: {
      myFlags: ['a', 'b', 'c'],
      bootTime: 1234
    },
    nestedAPI: {
      evenDeeper: {
        youCanDoThisAsMuchAsYouWant: {
          fn: () => ({
            returnData: 123
          })
        }
      }
    }
  }
)

下面显示了 exposeInIsolatedWorld 的示例

const { contextBridge, ipcRenderer } = require('electron')

contextBridge.exposeInIsolatedWorld(
  1004,
  'electron',
  {
    doThing: () => ipcRenderer.send('do-a-thing')
  }
)
// Renderer (In isolated world id1004)

window.electron.doThing()

API 函数​

您通过 contextBridge 绑定的 Function 值通过 Electron 代理，以确保上下文保持隔离。这导致了一些我们下面概述的关键限制。

参数 / 错误 / 返回类型支持​

由于参数、错误和返回值在通过桥发送时被复制，因此只有某些类型可以使用。在较高的层次上，如果您要使用的类型可以被序列化和反序列化为同一对象，它将起作用。为了完整起见，下面包含了一个类型支持表

类型复杂性参数支持返回值支持限制
string简单✅✅N/A
number简单✅✅N/A
boolean简单✅✅N/A
Object复杂✅✅键必须仅使用此表中的“简单”类型支持。值必须在此表中受支持。原型修改被删除。发送自定义类将复制值，但不会复制原型。
Array复杂✅✅与 Object 类型相同的限制
Error复杂✅✅抛出的错误也会被复制，这可能会导致错误的 message 和 stack trace 略有变化，原因是它们在不同的上下文中被抛出，并且 Error 对象上的任何自定义属性 都将丢失
Promise复杂✅✅N/A
Function复杂✅✅原型修改被删除。发送类或构造函数将不起作用。
可克隆类型简单✅✅请参阅有关可克隆类型的链接文档
Element复杂✅✅原型修改被删除。发送自定义元素将不起作用。
Blob复杂✅✅N/A
SymbolN/A❌❌符号无法跨上下文复制，因此它们会被删除

如果您关心的类型不在上表中，则可能不受支持。

公开 ipcRenderer​

尝试将整个 ipcRenderer 模块作为对象通过 contextBridge 发送将导致桥接收侧出现一个空对象。完整地发送 ipcRenderer 可以让任何代码发送任何消息，这是一个安全隐患。要通过 ipcRenderer 进行交互，请提供如下所示的安全包装器

// Preload (Isolated World)
contextBridge.exposeInMainWorld('electron', {
  onMyEventName: (callback) => ipcRenderer.on('MyEventName', (e, ...args) => callback(args))
})
// Renderer (Main World)
window.electron.onMyEventName(data => { /* ... */ })

公开 Node 全局符号​

预加载脚本可以使用 contextBridge，使您的渲染器可以访问 Node API。上面描述的支持类型表也适用于您通过 contextBridge 公开的 Node API。请注意，许多 Node API 授予对本地系统资源的访问权限。请非常谨慎地将哪些全局变量和 API 公开给不受信任的远程内容。

const { contextBridge } = require('electron')
const crypto = require('node:crypto')
contextBridge.exposeInMainWorld('nodeCrypto', {
  sha256sum (data) {
    const hash = crypto.createHash('sha256')
    hash.update(data)
    return hash.digest('hex')
  }
})