文章目录
- 一、什么是预加载脚本(preload),为什么我们需要它
- 二、通过预加载脚本暴露相关 API 至渲染进程
- 1、实现获取系统默认桌面路径功能
- 2、向剪切板写入内容
- 3、使用系统默认浏览器访问目标 url
- 4、使用文件选择对话框
- 三、参考资料
一、什么是预加载脚本(preload),为什么我们需要它
根据 Electron 官方提供的相关说明,我们可以将预加载脚本理解成是主进程和渲染进程间的桥梁。通常出于安全性的角度考虑,我们使用预加载脚本来安全地将 Node.js 模块或第三方库的 API 暴露至渲染进程中。
有时,我们可能为了在渲染进程中使用 Node.js 相关模块而关闭上下文隔离和为页面集成 Node.js 环境,但是这种方式官方并不推荐:
// 不推荐
const mainWindow = new BrowserWindow({webPreferences: {// 关闭上下文隔离contextIsolation: false,// 为页面集成 Node.js 环境nodeIntegration: true,}
})mainWindow.loadURL('https://example.com')
官方推荐的使用预加载脚本(preload)暴露相关 API,以使用 Node.js 的模块功能:
// 推荐
const mainWindow = new BrowserWindow({webPreferences: {preload: path.join(app.getAppPath(), 'preload.js')}
})mainWindow.loadURL('https://example.com')
关于预加载脚本的更多介绍参见:https://www.electronjs.org/zh/docs/latest/tutorial/tutorial-preload
关于安全方面的更多介绍参见:https://www.electronjs.org/zh/docs/latest/tutorial/security
二、通过预加载脚本暴露相关 API 至渲染进程
实现目标:
- 获取系统默认桌面路径功能
- 向剪切板写入内容
- 使用系统默认浏览器访问目标 url
- 使用文件选择对话框
项目通过 electron-vite-vue 构建,详情可见:https://blog.csdn.net/qq_45897239/article/details/138490747
准备工作,在主进程 main.ts
文件中导入 preload
相关文件:
// electron/main.ts
function createWindow() {win = new BrowserWindow({width: 1200,height: 700,minWidth: 885,minHeight: 580,icon: path.join(process.env.VITE_PUBLIC, "electron-vite.svg"),webPreferences: {// 导入 preload 相关文件preload: path.join(__dirname, "preload.mjs"),},// 隐藏菜单栏 按 Alt 键显示autoHideMenuBar: true,});// 程序启动后开启 开发者工具// win.webContents.openDevTools();// 关闭菜单栏// Menu.setApplicationMenu(null);if (VITE_DEV_SERVER_URL) {win?.loadURL(VITE_DEV_SERVER_URL);} else {win?.loadFile(path.join(RENDERER_DIST, "index.html"));}
}
1、实现获取系统默认桌面路径功能
在 preload.ts
文件中通过 contextBridge
对外暴露自定义 API。
// electron/preload.ts
import { ipcRenderer, contextBridge } from "electron";contextBridge.exposeInMainWorld("electronAPI", {// 获取系统默认桌面路径getDesktopPath: async () => {try {return await ipcRenderer.invoke("get-desktop-path");} catch (error) {console.error("Failed to get desktop path:", error.message);}},...
});
ipcRenderer.invoke
允许渲染进程向主进程发送事件或消息,并且接收主进程返回的数据。
可以直接在主进程中使用 ipcMain.handle()
监听渲染进程发送来的消息:
// electron/main.ts
import { app, ipcMain } from "electron";
...
app.whenReady().then(async () => {try {...createWindow();// get-desktop-path => 获取系统桌面路径ipcMain.handle("get-desktop-path", () => {return app.getPath("desktop");});} catch (error) {console.error("Failed to start server:", error);}
});
调用 API 获取系统桌面路径:
<script setup lang="ts">
onMounted(async () => {// 获取系统桌面路径const res = await window.electronAPI.getDesktopPath();console.log(res);
});
</script>
注意: 可能会出现 ts
报错
属性“electronAPI”在类型“Window & typeof globalThis”上不存在。你是否指的是“Electron”?ts-plugin(2551)
electron.d.ts(12, 19): 在此处声明了 "Electron"。
解决方案
在 vite-env.d.ts
中追加以下内容即可:
declare interface Window {electronAPI: any
}
2、向剪切板写入内容
定义相关 API:
// electron/preload.ts
import { ipcRenderer, contextBridge } from "electron";contextBridge.exposeInMainWorld("electronAPI", {// 向剪切板写入内容clipboardWriteText: async (text) => {try {await ipcRenderer.invoke("write-to-clipboard", text);} catch (error) {console.error("Failed to write to clipboard:", error.message);}},,...
});
主进程中监听:
// electron/main.ts
import { app, ipcMain, clipboard } from "electron";
...
app.whenReady().then(async () => {try {...// write-to-clipboard => 向剪切板写入内容ipcMain.handle("write-to-clipboard", (event, text) => {clipboard.writeText(text);});} catch (error) {console.error("Failed to start server:", error);}
});
使用:
<script setup lang="ts">
// 向剪切板写入内容
const copyLink = (text) => {window.electronAPI.clipboardWriteText(text);
};
</script>
3、使用系统默认浏览器访问目标 url
定义相关 API:
// electron/preload.ts
import { ipcRenderer, contextBridge } from "electron";contextBridge.exposeInMainWorld("electronAPI", {// 使用系统默认浏览器访问目标 urlopenBrowserByUrl: async (url) => {try {await ipcRenderer.invoke("open-browser-by-url", url);} catch (error) {console.error("Failed to open browser:", error.message);}},...
});
主进程中监听:
// electron/main.ts
import { app, ipcMain, shell } from "electron";
...
app.whenReady().then(async () => {try {...// open-browser-by-url => 使用系统默认浏览器访问目标 urlipcMain.handle("open-browser-by-url", async (event, url) => {await shell.openExternal(url);});} catch (error) {console.error("Failed to start server:", error);}
});
使用:
<script setup lang="ts">
// 使用系统默认浏览器访问目标 url
const goToLink = (url) => {window.electronAPI.openBrowserByUrl(url);
};
</script>
4、使用文件选择对话框
定义相关 API:
// electron/preload.ts
import { ipcRenderer, contextBridge } from "electron";contextBridge.exposeInMainWorld("electronAPI", {// 打开文件保存对话框 返回文件保存路径openFileSaveDialog: async (path) => {try {return await ipcRenderer.invoke("open-save-dialog",path);} catch (error) {console.error("Failed to open save dialog:", error.message);}},...
});
此处需要将文件对话框设置为顶层窗口,否则用户关闭应用程序后,该窗口依然存在。由于将对话框设置为顶层对话框需要win实例,所以使用函数方式导出初始化。设置为顶层对话框后,防止对话框被多次打开和未关闭对话框时的其他窗口操作。
可以在 electron
文件夹下创建一个 ipcHandlers.ts
文件,该文件内放置主进程需要监听的渲染进程发送来的消息,后续再导入 main.ts
主进程文件中。
// electron/ipcHandlers.ts
import { app, ipcMain, dialog, BrowserWindow } from "electron";// 可以在此文件内放置需要监听的来自渲染进程的消息
// get-desktop-path => 获取系统桌面路径
ipcMain.handle("get-desktop-path", () => {...
});export function initIpcHandlerDialog(win: BrowserWindow) {// open-save-dialog => 打开文件保存对话框ipcMain.handle("open-save-dialog", async (event, path) => {try {// 打开保存文件对话框const result = await dialog.showOpenDialog(win, {// 对话框标题title: "选择文件保存目录",// 确认按钮buttonLabel: "选择目录",// 默认文件路径defaultPath: app.getPath("desktop"),// 只允许选择文件夹properties: ["openDirectory"],// 文件过滤器,定义可以选择哪些类型的文件filters: [{ name: "All Files", extensions: ["*"] }]});if (result) {if (result.canceled) {console.log("用户取消了保存操作");// 如果用户取消了保存操作,则返回之前的保存路径,如若为空,则使用默认值if (!path) {path = app.getPath("desktop");}return path;} else {const filePath = result.filePaths[0];console.log("用户选择了保存路径:", filePath);return filePath;}}} catch (error) {console.log("文件对话框打开失败:" + error);// 获取桌面默认路径并返回return app.getPath("desktop");}});
}
在主进程中导入:
// electron/main.ts
import { app, BrowserWindow, ipcMain } from "electron";
...
// 导入相关功能模块
import "./ipcHandlers.ts";
import { initIpcHandlerDialog } from "./ipcHandlers.ts";...app.whenReady().then(async () => {try {...createWindow();// 初始化对话框,将弹出对话框设置为顶层状态initIpcHandlerDialog(win);} catch (error) {console.error("Failed to start server:", error);}
});
使用:
<script setup lang="ts">
// 打开文件保存对话框
const openSaveDialog = async () => {const defaultPath = 'D:/Desktop'const path = await window.electronAPI.openFileSaveDialog(defaultPath);
};
</script>
该方法传递了一个 defaultPath
参数,用于处理当用户点击了取消文件选择对话框时,使用的默认文件保存路径。
效果展示:
三、参考资料
- electron - ipcRenderer
- electron - preload
- electron - security