在万物互联的时代，跨平台开发已成为开发者追求高效开发的核心诉求。OpenHarmony作为开源的分布式操作系统，凭借其"一次开发，多端部署"的特性，为物联网、智能终端及鸿蒙PC等领域提供了统一的技术底座。而鸿蒙Electron（Electron for OpenHarmony）的出现，为Web开发者提供了一条低成本迁移至OpenHarmony生态的捷径。本文将从技术原理、环境搭建、核心代码解析到实战案例，全方位解析鸿蒙Electron的开发流程，助力开发者快速上手。

一、鸿蒙Electron：技术融合的桥梁

1.1 什么是鸿蒙Electron？

鸿蒙Electron并非简单的"Electron套壳"，而是基于Electron技术栈深度改造的跨平台开发方案。它去除了Electron中与Chromium和Node.js紧密绑定的部分，转而适配OpenHarmony的系统API（如分布式文件、设备互联、通知推送等），同时优化了渲染引擎以支持OpenHarmony的窗口管理、分屏、全局菜单等原生特性，特别针对鸿蒙PC进行了桌面级优化。这种设计使得开发者能够复用现有的Web技术栈（HTML/CSS/JavaScript），快速开发出兼容OpenHarmony手机、平板、PC及智慧屏等设备的应用，实现"一次开发，多端部署"。

1.2 为什么选择鸿蒙Electron？

  • 技术复用：Web开发者无需学习新的编程语言或框架，即可快速上手OpenHarmony开发。

  • 跨端兼容：一套代码可同时运行于OpenHarmony手机、平板、鸿蒙PC及智慧屏等设备，降低适配成本。

  • 生态融合：支持调用OpenHarmony的分布式能力，实现跨设备文件访问、多端协同等高级功能。

  • 性能优化：相比标准Electron，鸿蒙Electron通过去除Node.js运行时和优化渲染引擎，显著降低了内存占用和启动时间。

二、环境搭建：三步快速上手

2.1 开发环境要求

  • 操作系统：Windows 10/11 64位或macOS 12及以上。

  • 开发工具：DevEco Studio 5.0 Beta2及以上（OpenHarmony官方IDE）。

  • 依赖工具：Node.js 16.x LTS版本、Git。

  • 硬件设备：搭载OpenHarmony 4.0及以上版本的设备，包括鸿蒙PC（推荐使用OpenHarmony开发板、模拟器或真实鸿蒙PC进行调试）。

2.2 详细搭建步骤

步骤1：安装DevEco Studio并配置OpenHarmony SDK

  1. 访问OpenHarmony开发者官网，下载并安装DevEco Studio。

  2. 启动DevEco Studio，进入"SDK Manager"（工具栏→Tools→SDK Manager），勾选"OpenHarmony SDK Platform 4.0"（API Version 10）及"Electron Adapter"（鸿蒙Electron适配插件），点击"Apply"完成安装。

  3. 新增系统变量OPENHARMONY_ELECTRON_SDK，值为SDK中Electron Adapter的路径（如D:\Huawei\Sdk\electron-adapter\1.0.0）。将Node.js路径（如C:\Program Files\nodejs）添加至Path变量。

步骤2：验证环境配置

打开终端（Windows用CMD，macOS用Terminal），执行以下命令验证环境配置：

 检查Node.js版本（需为16.x）
node -v

 检查鸿蒙Electron适配器版本
hpm electron -v

若输出“OpenHarmony Electron Adapter 1.0.0”，则环境配置成功

步骤3：安装鸿蒙Electron脚手架

通过npm全局安装鸿蒙Electron官方脚手架，用于快速创建项目：

安装脚手架
npm install -g @openharmony/electron-cli

验证脚手架安装
harmony-electron -v  # 输出“1.0.0”即安装成功

三、核心代码解析：从Hello World到分布式能力

3.1 项目结构解析

使用脚手架创建项目后，目录结构如下：

openharmony-electron-demo/
├── main/                # 主进程代码（控制应用生命周期）
│   └── index.js         # 主进程入口文件
├── renderer/            # 渲染进程代码（UI界面）
│   ├── index.html       # 界面入口
│   ├── css/             # 样式文件
│   └── js/              # 前端逻辑
├── package.json         # 项目配置（依赖、脚本）
└── openharmony.json     # OpenHarmony应用配置（权限、设备类型）

3.2 主进程代码：控制应用生命周期

主进程负责应用启动、窗口管理与调用OpenHarmony系统能力。修改main/index.js文件：

const { app, BrowserWindow } = require('@openharmony/electron'); // 引入鸿蒙Electron模块
const path = require('path');

let mainWindow; // 存储窗口实例

// 创建应用窗口
function createWindow() {
    mainWindow = new BrowserWindow({
        width: 800,
        height: 600,
        
        // 鸿蒙PC特有配置
        pcConfig: {
            nativeFrame: true,    // 使用原生窗口框架
            systemMenu: true,     // 启用系统菜单
            taskbar: true,        // 显示在任务栏
            acrylic: false,       // 亚克力效果（鸿蒙PC特性）
            shadow: true          // 窗口阴影
        },
        
        webPreferences: {
            nodeIntegration: false, // 禁用Node.js集成（安全规范）
            contextIsolation: true, // 开启上下文隔离
            preload: path.join(__dirname, '../renderer/js/preload.js') // 预加载脚本路径
        }
    });

    mainWindow.loadFile(path.join(__dirname, '../renderer/index.html')); // 加载HTML页面
    mainWindow.on('closed', () => { mainWindow = null; }); // 窗口关闭时释放资源
    
    // 鸿蒙PC开发：打开开发者工具（开发环境）
    if (process.env.NODE_ENV === 'development') {
        mainWindow.webContents.openDevTools();
    }
}

// 应用生命周期管理
app.whenReady().then(createWindow); // 应用就绪后创建窗口
app.on('activate', () => { 
    if (BrowserWindow.getAllWindows().length === 0) createWindow(); 
}); // 激活应用时创建窗口（macOS适配）

// 鸿蒙PC适配：所有窗口关闭时不退出，保持后台运行
app.on('window-all-closed', () => { 
    if (process.platform !== 'harmony-pc') app.quit(); 
});

代码解释：

  • app：控制应用生命周期的模块，如启动、退出。

  • BrowserWindow：创建和管理应用窗口，支持鸿蒙PC原生窗口特性。

  • webPreferences：配置窗口的Web环境，如禁用Node.js集成以增强安全性。

  • preload：指定预加载脚本路径，用于安全地暴露API给渲染进程。

3.3 预加载脚本：安全暴露API

预加载脚本用于在渲染进程和主进程之间建立安全的通信桥梁。修改renderer/js/preload.js文件：

const { contextBridge, ipcRenderer } = require('@openharmony/electron');

// 暴露API给渲染进程
contextBridge.exposeInMainWorld('electronAPI', {
    getAppVersion: () => ipcRenderer.invoke('get-app-version'), // 示例：获取应用版本
    
    // 鸿蒙PC特有功能
    minimizeWindow: () => ipcRenderer.send('window:minimize'),
    maximizeWindow: () => ipcRenderer.send('window:maximize'),
    closeWindow: () => ipcRenderer.send('window:close'),
    
    // 系统集成
    showInFolder: (path) => ipcRenderer.send('pc:show-in-folder', path),
    openExternal: (url) => ipcRenderer.send('pc:open-external', url),
    
    // 文件操作（沙盒内）
    readFile: (filePath) => ipcRenderer.invoke('file:read', filePath),
    saveFile: (data, options) => ipcRenderer.invoke('file:save', data, options)
});

// 环境检测
window.isHarmonyPC = process.platform === 'harmony-pc';

代码解释：

  • contextBridge.exposeInMainWorld：将API暴露给渲染进程的全局对象（window）。

  • ipcRenderer.invoke：通过IPC（进程间通信）调用主进程的API。

  • 针对鸿蒙PC添加了窗口控制、文件操作等桌面应用常用功能。

3.4 渲染进程代码：实现交互逻辑

修改renderer/index.html和renderer/js/renderer.js文件，实现一个简单的"Hello World"界面：

<!-- renderer/index.html -->
<!DOCTYPE html>
<html lang="zh-CN">
<head>
    <meta charset="UTF-8">
    <title>Hello World - 鸿蒙PC</title>
    <link rel="stylesheet" href="css/style.css">
    <style>
        .pc-badge {
            display: inline-block;
            background: #007dff;
            color: white;
            padding: 4px 12px;
            border-radius: 20px;
            font-size: 14px;
            margin-left: 10px;
        }
        
        .window-controls {
            position: absolute;
            top: 20px;
            right: 20px;
            display: flex;
            gap: 10px;
        }
        
        .control-btn {
            width: 32px;
            height: 32px;
            border-radius: 8px;
            border: 1px solid #e0e0e0;
            background: white;
            cursor: pointer;
            display: flex;
            align-items: center;
            justify-content: center;
        }
        
        .control-btn:hover {
            background: #f5f5f5;
        }
    </style>
</head>
<body>
    <div class="window-controls" id="windowControls">
        <button class="control-btn" οnclick="minimizeWindow()">－</button>
        <button class="control-btn" οnclick="maximizeWindow()">□</button>
        <button class="control-btn" οnclick="closeWindow()">×</button>
    </div>
    
    <h1>Hello OpenHarmony! <span class="pc-badge">鸿蒙PC版</span></h1>
    <p id="platformInfo">正在检测运行平台...</p>
    <button id="versionBtn">获取应用版本</button>
    <button id="pcFeatureBtn">测试鸿蒙PC功能</button>
    
    <script src="js/renderer.js"></script>
</body>
</html>

// renderer/js/renderer.js
document.addEventListener('DOMContentLoaded', () => {
    // 检测运行平台
    const platformInfo = document.getElementById('platformInfo');
    if (window.isHarmonyPC) {
        platformInfo.textContent = '运行环境：鸿蒙PC桌面系统';
        platformInfo.style.color = '#007dff';
    } else {
        platformInfo.textContent = '运行环境：OpenHarmony移动设备';
    }
    
    // 获取应用版本
    document.getElementById('versionBtn').addEventListener('click', async () => {
        const version = await window.electronAPI.getAppVersion(); // 调用预加载脚本暴露的API
        alert(`当前应用版本：${version}`);
    });
    
    // 测试鸿蒙PC功能
    document.getElementById('pcFeatureBtn').addEventListener('click', async () => {
        if (window.isHarmonyPC) {
            // 测试文件读取
            try {
                const content = await window.electronAPI.readFile('/etc/hostname');
                alert(`文件读取成功（示例）：${content.substring(0, 50)}...`);
            } catch (error) {
                alert('文件读取测试（沙盒限制正常）');
            }
        } else {
            alert('此功能仅限鸿蒙PC平台');
        }
    });
});

// 窗口控制函数
function minimizeWindow() {
    if (window.electronAPI.minimizeWindow) {
        window.electronAPI.minimizeWindow();
    }
}

function maximizeWindow() {
    if (window.electronAPI.maximizeWindow) {
        window.electronAPI.maximizeWindow();
    }
}

function closeWindow() {
    if (window.electronAPI.closeWindow) {
        window.electronAPI.closeWindow();
    }
}

代码解释：

  • 渲染进程通过window.electronAPI调用主进程的API。

  • 使用async/await处理异步通信，避免回调地狱。

  • 针对鸿蒙PC平台添加了窗口控制和平台检测功能。

3.5 扩展功能：调用OpenHarmony分布式能力

鸿蒙Electron支持调用OpenHarmony的分布式能力，如跨设备文件访问。修改main/index.js，添加分布式文件管理代码：

const { app, BrowserWindow, ipcMain } = require('@openharmony/electron');
const { DistributedFile } = require('@openharmony/electron/distributed'); // 引入分布式文件模块
const path = require('path');

// 初始化分布式文件管理器
const fileManager = new DistributedFile({
    bundleName: 'com.example.demo', // 应用包名（需与openharmony.json一致）
    storeName: 'sharedFiles' // 共享文件存储名称
});

// IPC通信：获取共享文件列表
ipcMain.handle('get-shared-files', async () => {
    try {
        const files = await fileManager.listFiles(); // 列出共享文件
        return files;
    } catch (error) {
        console.error('获取共享文件失败:', error);
        return [];
    }
});

// IPC通信：保存笔记（鸿蒙PC优化版）
ipcMain.handle('save-note', async (event, content, options = {}) => {
    try {
        // 如果是鸿蒙PC，提供额外的桌面集成功能
        if (process.platform === 'harmony-pc') {
            // 在鸿蒙PC上，可以将笔记保存到用户选择的目录
            if (options.saveToDesktop) {
                const desktopPath = require('@openharmony/electron').app.getPath('desktop');
                const fs = require('@openharmony/electron').fs;
                const filePath = path.join(desktopPath, `note_${Date.now()}.txt`);
                await fs.promises.writeFile(filePath, content, 'utf-8');
                
                // 鸿蒙PC特有：显示保存成功的系统通知
                const { Notification } = require('@openharmony/electron');
                new Notification({
                    title: '笔记保存成功',
                    body: `已保存到桌面：${path.basename(filePath)}`,
                    icon: path.join(__dirname, '../resources/icon.png')
                }).show();
                
                return { 
                    success: true, 
                    platform: 'harmony-pc',
                    filePath 
                };
            }
        }
        
        // 通用保存逻辑（分布式存储）
        await fileManager.put('currentNote', content);
        return { success: true };
    } catch (error) {
        console.error('保存笔记失败:', error);
        return { success: false, error: error.message };
    }
});

代码解释：

  • DistributedFile：OpenHarmony的分布式文件管理模块，支持跨设备文件访问。

  • ipcMain.handle：定义主进程的IPC处理器，供渲染进程调用。

  • 鸿蒙PC优化：添加了桌面集成功能，如保存到桌面、系统通知等。

四、实战案例：构建一个跨设备记事本

4.1 功能需求

  1. 用户可以输入笔记内容并保存。

  2. 笔记内容支持跨设备同步（通过OpenHarmony分布式能力）。

  3. 鸿蒙PC版特有功能：支持保存到桌面、系统托盘、任务栏进度显示。

  4. 界面简洁，支持响应式布局。

4.2 核心代码实现

修改main/index.js（添加分布式数据管理与鸿蒙PC特性）

const { app, BrowserWindow, ipcMain, systemTray, Menu } = require('@openharmony/electron');
const { DistributedDataManager } = require('@openharmony/electron/distributed');
const path = require('path');

// 初始化分布式数据管理器
const dataManager = new DistributedDataManager({
    bundleName: 'com.example.notepad',
    storeName: 'noteStore'
});

let tray = null;

// 创建系统托盘（仅鸿蒙PC）
function createSystemTray() {
    if (process.platform === 'harmony-pc') {
        tray = new systemTray.Tray(
            path.join(__dirname, '../resources/tray-icon.png')
        );
        
        const contextMenu = Menu.buildFromTemplate([
            { label: '打开记事本', click: () => mainWindow.show() },
            { label: '新建笔记', click: () => mainWindow.webContents.send('new-note') },
            { type: 'separator' },
            { label: '退出', click: () => app.quit() }
        ]);
        
        tray.setToolTip('鸿蒙记事本');
        tray.setContextMenu(contextMenu);
    }
}

// IPC通信：保存笔记
ipcMain.handle('save-note', async (event, content) => {
    try {
        await dataManager.put('currentNote', content); // 保存笔记内容
        
        // 鸿蒙PC特有：更新任务栏进度
        if (process.platform === 'harmony-pc' && mainWindow) {
            mainWindow.setProgressBar(1.0); // 100%进度
            setTimeout(() => mainWindow.setProgressBar(-1), 1000); // 1秒后清除
        }
        
        return { success: true };
    } catch (error) {
        console.error('保存笔记失败:', error);
        return { success: false, error: error.message };
    }
});

// IPC通信：获取笔记
ipcMain.handle('get-note', async () => {
    try {
        const content = await dataManager.get('currentNote'); // 获取笔记内容
        return content || ''; // 若不存在则返回空字符串
    } catch (error) {
        console.error('获取笔记失败:', error);
        return '';
    }
});

修改renderer/js/renderer.js（实现笔记保存与加载）

// 页面加载时获取笔记
window.addEventListener('DOMContentLoaded', async () => {
    const noteContent = await window.electronAPI.getNote(); // 调用主进程API获取笔记
    document.getElementById('noteContent').value = noteContent; // 填充到文本框
    
    // 鸿蒙PC特有：监听新建笔记事件
    if (window.isHarmonyPC) {
        window.electronAPI.onNewNote(() => {
            document.getElementById('noteContent').value = '';
            document.getElementById('noteContent').focus();
        });
    }
});

// 保存按钮点击事件
document.getElementById('saveBtn').addEventListener('click', async () => {
    const content = document.getElementById('noteContent').value;
    
    // 鸿蒙PC特有：添加保存选项
    const options = {};
    if (window.isHarmonyPC && document.getElementById('saveToDesktop').checked) {
        options.saveToDesktop = true;
    }
    
    const result = await window.electronAPI.saveNote(content, options); // 调用主进程API保存笔记
    
    if (result.success) {
        if (window.isHarmonyPC && result.filePath) {
            alert(`笔记已保存到桌面：${result.filePath}`);
        } else {
            alert('笔记保存成功！已同步到所有设备。');
        }
    } else {
        alert(`保存失败：${result.error}`);
    }
});

// 鸿蒙PC特有：添加键盘快捷键
if (window.isHarmonyPC) {
    document.addEventListener('keydown', (e) => {
        if (e.ctrlKey && e.key === 's') {
            e.preventDefault();
            document.getElementById('saveBtn').click();
        }
    });
}

修改preload.js（暴露笔记相关API）

const { contextBridge, ipcRenderer } = require('@openharmony/electron');

contextBridge.exposeInMainWorld('electronAPI', {
    getNote: () => ipcRenderer.invoke('get-note'),
    saveNote: (content, options) => ipcRenderer.invoke('save-note', content, options),
    
    // 鸿蒙PC特有功能
    minimizeWindow: () => ipcRenderer.send('window:minimize'),
    maximizeWindow: () => ipcRenderer.send('window:maximize'),
    closeWindow: () => ipcRenderer.send('window:close'),
    
    // 事件监听
    onNewNote: (callback) => {
        ipcRenderer.on('new-note', () => callback());
    }
});

五、总结与展望

鸿蒙Electron为Web开发者提供了一条高效迁移至OpenHarmony生态的路径，通过API桥接层解决了Electron与OpenHarmony的核心差异，实现了技术复用与跨端兼容。本文通过"Hello World"和跨设备记事本两个案例，详细解析了鸿蒙Electron的核心开发流程，包括主进程管理、IPC通信、分布式能力调用等，特别针对鸿蒙PC平台进行了桌面级优化。

随着OpenHarmony生态的持续完善，未来鸿蒙Electron有望实现更深度的集成，如官方原生支持Node.js运行时、更高效的渲染性能优化等。对于开发者而言，掌握鸿蒙Electron开发技能，将能够更好地把握万物互联时代的技术机遇，特别是在鸿蒙PC生态快速发展的大背景下。

欢迎加入开源鸿蒙PC社区

无论您是OpenHarmony的初学者，还是经验丰富的开发者，都欢迎加入我们的开源鸿蒙PC社区！在这里，您可以：

  • 📚 获取最新的鸿蒙PC开发资料和教程

  • 💬 与其他开发者交流技术问题和经验

  • 🔧 参与开源项目，共同完善鸿蒙PC生态

  • 🚀 获取技术支持和开发指导

社区地址：https://harmonypc.csdn.net/

让我们一起推动鸿蒙PC生态的发展，构建更美好的万物互联世界！

# wpf
Logo
Harmony PC 开发者社区

赋能鸿蒙PC开发者，共建全场景原生生态，共享一次开发多端部署创新价值。

更多推荐

cover

鸿蒙 PC 平台 Python 第三方库移植全景指南

avatar Harmony PC 开发者社区
cover

鸿蒙PC平台Rust语言第三方库与移植全景指南

avatar Harmony PC 开发者社区
cover

在 HarmonyOS/鸿蒙PC ArkTS 侧调用 C/C++ 三方库完整指南

avatar Harmony PC 开发者社区