跳转到主要内容

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

提供给 exposeInMainWorldapi 必须是 FunctionstringnumberArrayboolean,或者一个键为字符串且值是 FunctionstringnumberArrayboolean 或符合相同条件的另一个嵌套对象的对象。

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简单不适用
number简单不适用
boolean简单不适用
Object复杂键必须仅使用此表中的“简单”类型进行支持。值必须在此表中得到支持。原型修改将被丢弃。发送自定义类将复制值,但不会复制原型。
Array复杂Object 类型具有相同的限制
Error复杂抛出的错误也会被复制,这可能导致错误的**消息**和**堆栈跟踪**因在不同上下文中抛出而略有变化,并且错误对象上的任何自定义属性都会丢失
Promise复杂不适用
Function复杂原型修改将被丢弃。发送类或构造函数将不起作用。
可克隆类型简单请参阅可克隆类型的链接文档
Element复杂原型修改将被丢弃。发送自定义元素将不起作用。
Blob复杂不适用
Symbol不适用Symbol 无法跨上下文复制,因此它们会被丢弃

如果你的关心类型不在上面的表中,它可能不支持。

暴露 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 全局 Symbol

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')
}
})