Electron Preload 预加载脚本

Quasar CLI with Vite - @quasar/app-vite

处于安全的原因，渲染进程（/src 目录中的 UI 代码）无法访问 Nodejs 的能力。然而，您可以通过 Electron Preload 预加载脚本将 Node.js 与渲染进程桥接。Preload 脚本位于 /src-electron/electron-preload.[js|ts]。使用 contextBridge 将 UI 中需要的能力注入。

由于 preload 脚本运行在 Node.js 环境中，请小心使用它的能力！

如何使用它

在 /src-electron/ 目录中，有一个 electron-preload.js 文件，在此书写您的 preload 脚本代码。

请确保您的 /src-electron/electron-main.js 中有以下内容（在 “webPreferences” 附近的部分）：

// Add this at the top:
import path from 'node:path'

// ...

function createWindow () {
  // ...
  const mainWindow = new BrowserWindow({
    // ...
    webPreferences: {
      // 注意这里使用 .cjs 后缀（没有写错）：
      preload: path.join(import.meta.dirname, "electron-preload.cjs")
    }
  })

/src-electron/electron-preload 示例：

/**
 * 此文件专门用于安全目的。
 * 您可以在此访问 Node.js 能力，并将功能注入到
 * 渲染进程中（在渲染进程中通过 "window" 对象访问）
 *
 * 警告！
 * 如果您从 node_modules 中导入了任何内容，请确保该包被声明在
 * /src-electron/package.json > dependencies 中，而不是 devDependencies
 *
 * 示例（将 window.myAPI.doAThing() 注入到渲染进程中）：
 *
 *   import { contextBridge } from 'electron'
 *
 *   contextBridge.exposeInMainWorld('myAPI', {
 *     doAThing: () => {}
 *   })
 *
 * 警告！
 * 如果需要访问 Node 功能（如导入 @electron/remote），那么您需要在
 * electron-main.ts 中实例化 BrowserWindow 时设置以下内容：
 *
 * mainWindow = new BrowserWindow({
 *   // ...
 *   webPreferences: {
 *     // ...
 *     sandbox: false // <-- 以便在 preload 脚本中导入 @electron/remote
 *   }
 * }
 */
import { contextBridge } from 'electron'
import { quasarRuntime } from '#q-app/electron/preload'

contextBridge.exposeInMainWorld('quasarRuntime', quasarRuntime)

WARNING

请注意，此文件在 Node.js 环境中运行。
如果您导入了一些来自 node_modules 中的内容，请确保您将其安装在了 /src-electron/package.json > “dependencies” 中，而不是 “devDependencies”。

安全注意事项

仅仅使用 contextBridge 并不意味着您所做的一切都是安全的。例如，下面的代码是不安全的：

// BAD code; DON'T!!
contextBridge.exposeInMainWorld("myAPI", {
  send: ipcRenderer.send,
});

它直接暴露了强大的 API，没有进行任何类型的参数过滤。这将允许任何网站发送您不希望的任意 IPC 消息。公开基于 IPC 的 API 的正确方法是为每条 IPC 消息提供一个方法。

// Good code
contextBridge.exposeInMainWorld('myAPI', {
  loadPreferences: () => ipcRenderer.invoke('myAPI:load-prefs')
})

现在， loadPreferences 可以在您的 javascript 中全局访问（如：window.myAPI.loadPreferences）。

WARNING

确保使用与现有 Window 中的属性不冲突的名称。

上述代码会触发主进程中的如下代码：

ipcMain.handle('myAPI:load-prefs', () => {
  return {
    // 包含 preferences 的对象
  }
})

自定义 preload 脚本路径

您可能希望修改 preload 脚本的位置（或者主进程代码文件），那么需要修改 /quasar.config 文件：

// should you wish to change default files
sourceFiles: {
  electronMain: 'src-electron/electron-main.js'
}

发现错误？在浏览器中编辑此页

1. Introduction

2. 如何使用它

3. 安全注意事项

4. 自定义 preload 脚本路径