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 | 简单 | ✅ | ✅ | 不适用 |
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')
}
})