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
any - 您的 API,有关此 API 可以是什么以及它如何工作的更多信息,请参见下文。
contextBridge.exposeInIsolatedWorld(worldId, apiKey, api)
worldId
整数 - 要将 API 注入的世界的 ID。0
是默认世界,999
是 Electron 的contextIsolation
功能使用的世界。使用 999 将会为预加载上下文暴露对象。我们建议在创建隔离世界时使用 1000+。apiKey
字符串 - 用于将 API 注入到window
的键。API 将可在window[apiKey]
上访问。api
any - 您的 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 | 复杂 | ✅ | ✅ | 抛出的错误也会被复制,这可能会导致错误的消息和堆栈跟踪略有变化,因为它们是在不同的上下文中抛出的,并且 Error 对象上的任何自定义属性都将丢失 |
Promise | 复杂 | ✅ | ✅ | N/A |
Function | 复杂 | ✅ | ✅ | 原型修改将被丢弃。发送类或构造函数将不起作用。 |
Cloneable Types | 简单 | ✅ | ✅ | 请参阅关于可克隆类型的链接文档 |
Element | 复杂 | ✅ | ✅ | 原型修改将被丢弃。发送自定义元素将不起作用。 |
Blob | 复杂 | ✅ | ✅ | N/A |
Symbol | N/A | ❌ | ❌ | Symbol 无法跨上下文复制,因此会被丢弃 |
如果您关心的类型不在上表中,则可能不受支持。
暴露 ipcRenderer
尝试通过 contextBridge
将整个 ipcRenderer
模块作为对象发送将导致桥梁接收侧出现一个空对象。完整地发送 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')
}
})