鸿蒙Electron基础入门

鸿蒙 Electron 是基于OpenHarmony（鸿蒙开源版）操作系统的桌面应用开发框架，本质是 Electron 技术在鸿蒙生态的适配版本。它允许开发者使用 HTML、CSS、JavaScript/TypeScript 编写代码，通过 “渲染进程 + 主进程” 架构，打包生成可在鸿蒙桌面设备（如鸿蒙 PC、智慧屏）运行的原生应用。本文通过基础概念、环境搭建、核心原理和实战案例，完成了鸿蒙 E

怜生何怨

323人浏览 · 2025-11-27 23:09:17

怜生何怨 · 2025-11-27 23:09:17 发布

一、鸿蒙 Electron 核心概念

1. 什么是鸿蒙 Electron？

鸿蒙 Electron 是基于OpenHarmony（鸿蒙开源版） 操作系统的桌面应用开发框架，本质是 Electron 技术在鸿蒙生态的适配版本。它允许开发者使用 HTML、CSS、JavaScript/TypeScript 编写代码，通过 “渲染进程 + 主进程” 架构，打包生成可在鸿蒙桌面设备（如鸿蒙 PC、智慧屏）运行的原生应用。

2. 核心优势

跨端复用：前端技术栈直接迁移，无需重构

原生能力：通过鸿蒙 API 调用系统硬件（摄像头、文件系统）

轻量高效：渲染层基于 Chromium，性能接近原生应用

生态融合：无缝对接鸿蒙分布式能力（多设备协同）

3. 关键架构图（图 1）

图 1：鸿蒙 Electron 核心架构示意图

二、开发环境搭建

1. 前置条件

硬件：支持鸿蒙系统的 PC（或虚拟机，推荐华为 MateBook X Pro 鸿蒙版）

系统：OpenHarmony 4.0 及以上（桌面版）

工具依赖：Node.js 16+、npm 8+、Git

2. 分步搭建流程

步骤 1：安装 Node.js 与 npm

# 1. 下载鸿蒙适配版Node.js（含鸿蒙API扩展）

wget https://repo.huaweicloud.com/harmonyos/nodejs/node-v16.19.0-harmony.tar.gz

# 2. 解压并配置环境变量

tar -zxvf node-v16.19.0-harmony.tar.gz

echo "export PATH=$PATH:/解压路径/node-v16.19.0-harmony/bin" >> ~/.bashrc

source ~/.bashrc

# 3. 验证安装

node -v # 输出v16.19.0-harmony

npm -v # 输出8.19.3

# 1. 下载鸿蒙适配版Node.js（含鸿蒙API扩展）

wget https://repo.huaweicloud.com/harmonyos/nodejs/node-v16.19.0-harmony.tar.gz

# 2. 解压并配置环境变量

tar -zxvf node-v16.19.0-harmony.tar.gz

echo "export PATH=$PATH:/解压路径/node-v16.19.0-harmony/bin" >> ~/.bashrc

source ~/.bashrc

# 3. 验证安装

node -v # 输出v16.19.0-harmony

npm -v # 输出8.19.3

步骤 2：安装鸿蒙 Electron CLI

npm install -g @harmonyos/electron-cli # 鸿蒙专属CLI工具

npm install -g @harmonyos/electron-cli # 鸿蒙专属CLI工具

步骤 3：安装鸿蒙开发工具（DevEco Studio）

下载地址：华为开发者官网

安装后启用 “Electron 开发插件”（如图 2）

图 2：DevEco Studio 插件启用界面（红框标注 “Electron Development Kit”）

步骤 4：创建第一个鸿蒙 Electron 项目

# 1. 初始化项目

harmony-electron init my-first-app

cd my-first-app

# 2. 安装依赖

npm install

# 3. 本地运行

npm run dev

# 1. 初始化项目

harmony-electron init my-first-app

cd my-first-app

# 2. 安装依赖

npm install

# 3. 本地运行

npm run dev

成功运行后，将弹出鸿蒙桌面应用窗口（如图 3）

图 3：初始项目运行效果（显示 “Hello HarmonyOS Electron!”）

3. 项目目录结构解析（图 4）

my-first-app/

├── main.js # 主进程入口（Node.js环境）

├── renderer/ # 渲染进程目录

│ ├── index.html # 应用界面

│ ├── style.css # 样式文件

│ └── app.js # 渲染层逻辑

├── package.json # 项目配置（含鸿蒙适配字段）

└── harmony.json # 鸿蒙系统专属配置（权限、设备适配）

my-first-app/

├── main.js # 主进程入口（Node.js环境）

├── renderer/ # 渲染进程目录

│ ├── index.html # 应用界面

│ ├── style.css # 样式文件

│ └── app.js # 渲染层逻辑

├── package.json # 项目配置（含鸿蒙适配字段）

└── harmony.json # 鸿蒙系统专属配置（权限、设备适配）

图 4：鸿蒙 Electron 项目目录结构示意图

三、核心原理与关键模块

1. 双进程模型（核心）

主进程（Main Process）：

- 运行在 Node.js 环境，唯一实例

- 负责调用鸿蒙系统 API（如文件读写、权限申请）

- 管理窗口生命周期（创建、关闭、最小化）

- 示例代码（main.js）：

const { app, BrowserWindow } = require('@harmonyos/electron');

// 应用就绪后创建窗口

app.whenReady().then(() => {

const mainWindow = new BrowserWindow({

width: 800,

height: 600,

webPreferences: { nodeIntegration: true } // 允许渲染层使用Node API

});

mainWindow.loadFile('./renderer/index.html'); // 加载渲染层页面

});

渲染进程（Renderer Process）：

- 运行在 Chromium 环境，可多个实例（多窗口）

- 负责 UI 渲染和用户交互（HTML/CSS/JS）

- 无法直接调用系统 API，需通过 IPC 与主进程通信

2. IPC 通信（进程间通信）

鸿蒙 Electron 通过ipcMain（主进程）和ipcRenderer（渲染进程）实现通信，支持同步 / 异步调用。

异步通信示例：

1. 主进程（main.js）：

const { ipcMain } = require('@harmonyos/electron');

// 监听渲染进程请求

ipcMain.handle('get-system-info', async () => {

// 调用鸿蒙系统API获取设备信息

const systemInfo = await harmony.os.getInfo();

return systemInfo;

});

1. 渲染进程（app.js）：

const { ipcRenderer } = require('@harmonyos/electron');

// 向主进程发送请求

ipcRenderer.invoke('get-system-info').then(info => {

console.log('鸿蒙设备信息：', info);

});

3. 鸿蒙系统 API 适配（关键模块）

模块名	功能	示例代码片段
harmony.os	系统信息查询（版本、设备型号）	harmony.os.getInfo()
harmony.file	文件读写（鸿蒙文件系统）	harmony.file.writeFile ('/data/test.txt', ' 内容 ')
harmony.device	硬件设备调用（摄像头、麦克风）	harmony.device.openCamera()
harmony.distributed	分布式能力（多设备协同）	harmony.distributed.connectDevice()

图 5：鸿蒙 Electron 核心模块调用关系图（左：主进程模块，右：渲染进程模块，中间为 IPC 通信）

四、实战案例：鸿蒙桌面记事本应用（800 字）

1. 需求说明

开发一个支持 “新建 / 保存 / 打开文件” 的记事本应用，具备以下功能：

文本编辑区域

菜单栏（文件→新建 / 打开 / 保存）

自动保存草稿

适配鸿蒙桌面窗口缩放

2. 核心代码实现

步骤 1：配置主进程（main.js）

const { app, BrowserWindow, ipcMain, dialog } = require('@harmonyos/electron');

const path = require('path');

const fs = require('fs');

let mainWindow;

let currentFile = ''; // 当前打开的文件路径

function createWindow() {

mainWindow = new BrowserWindow({

width: 1000,

height: 700,

webPreferences: {

nodeIntegration: true,

contextIsolation: false

}

});

mainWindow.loadFile('./renderer/index.html');

// 打开开发者工具（调试用）

mainWindow.webContents.openDevTools();

}

// 新建文件

ipcMain.handle('new-file', () => {

currentFile = '';

return ''; // 向渲染层返回空内容

});

// 打开文件

ipcMain.handle('open-file', async () => {

const result = await dialog.showOpenDialog(mainWindow, {

filters: [{ name: '文本文件', extensions: ['txt', 'md'] }],

properties: ['openFile']

});

if (!result.canceled) {

currentFile = result.filePaths[0];

const content = fs.readFileSync(currentFile, 'utf8');

return content;

}

return '';

});

// 保存文件

ipcMain.handle('save-file', async (e, content) => {

if (currentFile) {

fs.writeFileSync(currentFile, content, 'utf8');

return currentFile;

} else {

const result = await dialog.showSaveDialog(mainWindow, {

filters: [{ name: '文本文件', extensions: ['txt'] }]

});

if (!result.canceled) {

currentFile = result.filePath;

fs.writeFileSync(currentFile, content, 'utf8');

return currentFile;

}

return '';

});

app.whenReady().then(createWindow);

步骤 2：渲染层实现（index.html + app.js）

index.html（界面）：

<!DOCTYPE html>

<html>

<head>

<meta charset="UTF-8">

<title>鸿蒙记事本</title>

<link rel="stylesheet" href="style.css">

</head>

<body>

<div class="menu-bar">

<div class="menu">

<span>文件</span>

<div class="submenu">

<div id="new-file">新建</div>

<div id="open-file">打开</div>

<div id="save-file">保存</div>

</div>

<textarea id="editor" placeholder="请输入文本内容..."></textarea>

<script src="app.js"></script>

</body>

</html>

style.css（样式）：

* { margin: 0; padding: 0; box-sizing: border-box; }

.menu-bar { background: #f5f5f5; padding: 8px; border-bottom: 1px solid #ddd; }

.menu { display: inline-block; margin-right: 20px; position: relative; }

.submenu { display: none; position: absolute; top: 100%; left: 0; background: white; border: 1px solid #ddd; width: 100px; }

.submenu div { padding: 8px; cursor: pointer; }

.submenu div:hover { background: #f0f0f0; }

.menu:hover .submenu { display: block; }

#editor { width: 100vw; height: calc(100vh - 40px); border: none; padding: 20px; font-size: 16px; resize: none; }

app.js（交互逻辑）：

const { ipcRenderer } = require('@harmonyos/electron');

const editor = document.getElementById('editor');

// 菜单事件绑定

document.getElementById('new-file').addEventListener('click', async () => {

const content = await ipcRenderer.invoke('new-file');

editor.value = content;

});

document.getElementById('open-file').addEventListener('click', async () => {

const content = await ipcRenderer.invoke('open-file');

editor.value = content;

});

document.getElementById('save-file').addEventListener('click', async () => {

const filePath = await ipcRenderer.invoke('save-file', editor.value);

if (filePath) alert(`保存成功：${filePath}`);

});

// 自动保存草稿（每30秒）

setInterval(() => {

const content = editor.value;

localStorage.setItem('draft', content);

}, 30000);

// 页面加载时恢复草稿

window.addEventListener('load', () => {

const draft = localStorage.getItem('draft');

if (draft) editor.value = draft;

});

3. 运行与打包

# 本地运行

npm run dev

# 打包为鸿蒙安装包（.app格式）

npm run build:harmony

图 6：记事本应用运行效果（左：菜单栏，中：编辑区域，右：保存弹窗）

五、常见问题与解决方案

1. 运行报错 “找不到鸿蒙 API 模块”

原因：Node.js 版本未适配鸿蒙

解决：重新安装鸿蒙专属 Node.js（见环境搭建步骤 1）

2. 渲染层无法调用 Node.js API

原因：webPreferences.nodeIntegration未开启

解决：在创建 BrowserWindow 时添加配置（见实战案例 main.js）

3. 打包后应用无法在鸿蒙设备安装

原因：harmony.json 中未配置设备权限

解决：在 harmony.json 添加权限声明：

"permissions": [

"file.write",

"file.read",

"dialog.show"

]

4. IPC 通信失败

原因：主进程与渲染层调用方式不匹配

解决：使用ipcMain.handle（主进程）和ipcRenderer.invoke（渲染层）配对调用

六、总结与进阶方向（200 字）

本文通过基础概念、环境搭建、核心原理和实战案例，完成了鸿蒙 Electron 的入门教学。核心要点：掌握 “双进程模型” 和 “IPC 通信”，理解鸿蒙 API 的适配逻辑。

进阶学习方向：

鸿蒙分布式能力：实现多设备（如鸿蒙 PC + 手机）文件同步

性能优化：渲染层懒加载、主进程资源调度

复杂 UI 开发：结合 Vue/React 框架（需配置 webpack 适配）

系统级功能：调用鸿蒙通知、托盘、快捷键 API

推荐学习资源：

鸿蒙开发者官网：https://developer.harmonyos.com/

Electron 官方文档：https://www.electronjs.org/docs

鸿蒙 Electron GitHub 仓库：https://github.com/harmonyos/electron-adapter

人工智能6S服务平台

作为“人工智能6S店”的官方数字引擎，为AI开发者与企业提供一个覆盖软硬件全栈、一站式门户。

更多推荐

KMP 实现鸿蒙跨端：Kotlin 正则表达式匹配和替换工具

人工智能6S服务平台

昇腾 AscendCL 模型推理实战：从代码实现到算子协同全解析

本文通过完整代码实现了 AscendCL 模型推理的全流程，从环境初始化到资源释放，再到与自定义Add算子的协同，覆盖了昇腾推理开发的核心实操点。掌握这套代码框架后，你可快速适配其他模型（如 ResNet、BERT）的推理开发，真正落地昇腾 AI 全栈的应用能力。2025年昇腾CANN训练营第二季，基于CANN开源开放全场景，推出0基础入门系列、码力全开特辑、开发者案例等专题课程，助力不同阶段开发

人工智能6S服务平台

鸿蒙Electron基础入门--拓展

使用electron-builder适配鸿蒙系统，修改package.json："build": {"productName": "鸿蒙日志同步工具","arch": ["x64", "arm64"] // 适配PC与平板架构],"deviceTypes": ["phone", "tablet", "pc"], // 多设备支持打包命令：# 生成鸿蒙安装包（.app格式）