Hello World 实战：10 分钟开发第一个鸿蒙PC Electron 应用（含代码 + 运行效果）

本文面向鸿蒙PC Electron新手，用最简洁的流程实现两个核心目标：
✅ 搭建基础 Hello World 界面
✅ 完成一次主进程与渲染进程通信（点击按钮获取主进程返回的系统信息）

全程基于已搭建好的开发环境（参考前文《鸿蒙 Electron 开发环境搭建》），从项目创建到模拟器运行仅需 4 个步骤，附完整代码和运行效果描述，新手可直接复刻。

---

🔧 前置条件

请确保已完成以下环境配置：

• Node.js v16.20.2
• DevEco Studio 4.1.3.500
• @hmos/electron-cli@1.2.0（全局安装）
• 已创建 Phone 类型模拟器，运行 HarmonyOS 4.0 及以上

💡 提示：本项目虽在手机模拟器中运行，但所用 API 和架构完全适用于鸿蒙PC桌面应用开发。

---

步骤 1：3 分钟创建标准项目（脚手架指令）

使用鸿蒙 Electron 脚手架快速生成项目结构。

1.1 打开终端执行创建指令

# 进入桌面目录
cd Desktop

# 创建项目（英文名）
hmos-electron create hello-hmos-electron

# 进入项目
cd hello-hmos-electron

1.2 选择模板

终端会提示选择模板，输入 1 选择 Basic Template（基础模板）：

? Please select a template (Use arrow keys)
> 1. Basic Template（基础模板）
  2. Vue Template
  3. React Template

1.3 验证项目结构

成功后，项目目录如下（重点关注标⭐文件）：

hello-hmos-electron/
├── src/
│   ├── main/              ⭐ 主进程
│   │   └── index.ts
│   ├── renderer/          ⭐ 渲染进程
│   │   ├── index.html
│   │   └── src/
│   │       └── App.vue
│   └── common/            ⭐ 通信桥接
│       └── preload.js
└── package.json

---

步骤 2：4 分钟编写核心代码（4 个关键文件）

2.1 主进程：监听通信请求（src/main/index.ts）

import { app, BrowserWindow, ipcMain } from '@hmos/electron';
import path from 'path';

let mainWindow: BrowserWindow | null = null;

function createWindow() {
  mainWindow = new BrowserWindow({
    width: 800,
    height: 600,
    webPreferences: {
      preload: path.join(__dirname, '../common/preload.js'),
      contextIsolation: true,   // 必须开启
      nodeIntegration: false    // 禁止直接访问 Node
    }
  });

  if (process.env.NODE_ENV === 'development') {
    mainWindow.loadURL('http://localhost:3000');
    mainWindow.webContents.openDevTools(); // 自动打开调试工具
  } else {
    mainWindow.loadFile(path.join(__dirname, '../renderer/index.html'));
  }

  mainWindow.on('closed', () => {
    mainWindow = null;
  });
}

// 🌟 新增：监听渲染进程请求，返回系统信息
ipcMain.handle('get-system-info', async () => {
  return {
    appVersion: app.getVersion(),               // 来自 package.json
    electronVersion: process.versions.electron, // Electron 版本
    platform: process.platform                  // 系统平台
  };
});

app.whenReady().then(createWindow);

app.on('window-all-closed', () => {
  if (process.platform !== 'darwin') app.quit();
});

app.on('activate', () => {
  if (BrowserWindow.getAllWindows().length === 0) createWindow();
});

---

2.2 预加载脚本：安全暴露接口（src/common/preload.js）

import { contextBridge, ipcRenderer } from '@hmos/electron';

// 🌟 将通信接口挂载到 window.hmosApi
contextBridge.exposeInMainWorld('hmosApi', {
  getSystemInfo: () => ipcRenderer.invoke('get-system-info')
});

✅ 安全机制：通过 contextBridge 避免渲染进程直接调用 ipcRenderer，防止安全漏洞。

---

2.3 渲染进程：UI 与交互（src/renderer/src/App.vue）

<template>
  <div class="app-container">
    <h1 class="title">Hello HarmonyOS Electron!</h1>
    <button class="info-btn" @click="fetchSystemInfo">
      获取系统信息
    </button>
    <div class="info-box" v-if="systemInfo">
      <h3>系统信息（来自主进程）：</h3>
      <p>应用版本：{{ systemInfo.appVersion }}</p>
      <p>Electron 版本：{{ systemInfo.electronVersion }}</p>
      <p>系统平台：{{ formatPlatform(systemInfo.platform) }}</p>
    </div>
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue';

const systemInfo = ref(null);

const fetchSystemInfo = async () => {
  try {
    // 🌟 调用主进程能力
    systemInfo.value = await window.hmosApi.getSystemInfo();
  } catch (error) {
    alert('获取信息失败：' + error.message);
  }
};

const formatPlatform = (platform) => {
  const map = { win32: 'Windows', darwin: 'macOS', linux: 'Linux' };
  return map[platform] || platform;
};
</script>

<style scoped>
.app-container {
  width: 100%;
  height: 100vh;
  display: flex;
  flex-direction: column;
  align-items: center;
  justify-content: center;
  background-color: #f5f5f5;
}
.title {
  color: #007dff;
  margin-bottom: 30px;
}
.info-btn {
  padding: 12px 24px;
  font-size: 16px;
  background-color: #007dff;
  color: white;
  border: none;
  border-radius: 8px;
  cursor: pointer;
  margin-bottom: 30px;
}
.info-btn:hover {
  background-color: #0066cc;
}
.info-box {
  width: 300px;
  padding: 20px;
  background: white;
  border-radius: 8px;
  box-shadow: 0 2px 10px rgba(0,0,0,0.1);
}
.info-box p {
  color: #666;
  margin: 8px 0;
}
</style>

---

2.4 简化页面载体（src/renderer/index.html）

<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Hello HarmonyOS Electron</title>
  <style>* { margin:0; padding:0; box-sizing:border-box; }</style>
</head>
<body>
  <div id="app"></div>
  <script src="/js/main.js"></script>
</body>
</html>

---

步骤 3：2 分钟本地调试（启动项目）

在项目根目录执行：

npm run dev

启动过程说明：

1. 编译阶段：主进程 + 渲染进程并行编译
2. 服务启动：http://localhost:3000 启动成功
3. 模拟器加载：自动启动 DevEco 模拟器并加载应用

⚠️ 避坑提示：若模拟器未自动启动，请手动操作：
① 打开 DevEco Studio → ② Tools → Device Manager → ③ 启动你的模拟器

---

步骤 4：1 分钟查看运行效果

4.1 初始界面效果

• 白色背景，居中显示蓝色标题 “Hello HarmonyOS Electron!”
• 下方一个蓝色圆角按钮 “获取系统信息”

4.2 点击按钮后的通信效果

点击后，下方显示从主进程返回的信息，例如：

系统信息（来自主进程）：
应用版本：1.0.0
Electron 版本：16.2.8
系统平台：Windows

✅ 证明通信成功：渲染进程 → 预加载脚本 → 主进程 → 返回数据 → 更新 UI

4.3 调试工具（自动弹出）

• 可查看 DOM 结构、JS 错误、网络请求
• 在 Console 中可输入 window.hmosApi 验证接口是否挂载

---

🛠 常见问题与避坑指南

问题现象	可能原因	解决方案
hmos-electron 不是内部命令	脚手架未全局安装	npm install -g @hmos/electron-cli@1.2.0 + 重启终端
模拟器白屏	渲染服务未启动或端口占用	检查终端是否有 Dev server started；关闭 3000 端口程序
window.hmosApi is undefined	preload 路径错误 或 contextIsolation: false	检查路径 & 确保 contextIsolation: true
ipcMain.handle 未定义	Electron 版本过低	升级至 @hmos/electron@≥1.2.0

---

✅ 总结：10 分钟掌握鸿蒙PC Electron 核心逻辑

本次实战浓缩为 “3 文件 + 1 机制”：

• 3 个关键文件

  • main/index.ts：主进程监听通信
  • common/preload.js：安全暴露接口
  • renderer/App.vue：UI 与用户交互

• 1 个核心机制
  IPC 跨进程通信：通过 ipcMain.handle + ipcRenderer.invoke + contextBridge 实现安全、高效的主-渲染进程协作。

🚀 下一步建议：
在此基础之上，你可以：

• 调用 harmony 模块实现鸿蒙PC分布式能力
• 添加文件读写、日志记录、窗口控制等桌面专属功能
• 打包为 .hap 或 .exe/.dmg 发布到鸿蒙PC设备

---

欢迎加入开源鸿蒙PC社区：https://harmonypc.csdn.net/
获取更多教程、组件库、实战案例，一起共建鸿蒙PC生态！