可帮助开发者使用 Vue3 技术栈开发 HarmonyOS 桌面应用,通过内置桥接层实现 Vue3 代码直接调用鸿蒙原生 API,支持系统通知、文件操作、剪贴板等能力,提供完整开发与构建流程。【此简介由AI生成】
| Files | Last commit | Last update |
|---|---|---|
| 5 months ago | ||
| 5 months ago | ||
| 5 months ago |
Electron-OpenHarmony-Vue3
📺 视频演示: https://www.bilibili.com/video/BV1Fpi5BhEDj
使用 Vue3 开发鸿蒙桌面应用的完整框架。
简介
本项目基于 Electron 运行时,让你可以使用熟悉的 Vue3 技术栈开发 HarmonyOS 桌面应用。通过内置的桥接层,Vue3 代码可以直接调用鸿蒙原生 API。
┌─────────────────────────────────────────────────────┐
│ Vue3 应用层 │
│ (你的业务代码、UI组件、路由、状态管理) │
├─────────────────────────────────────────────────────┤
│ useOhos() 桥接层 │
│ (封装好的 Vue3 Composable) │
├─────────────────────────────────────────────────────┤
│ Electron + Preload 层 │
│ (IPC 通信、API 暴露) │
├─────────────────────────────────────────────────────┤
│ HarmonyOS 原生层 │
│ (libadapter.so + ETS Adapters) │
└─────────────────────────────────────────────────────┘
快速开始
环境要求
- Node.js 18+
- DevEco Studio 5.0+
- HarmonyOS SDK
1. 安装依赖
cd ohos_hap/web_engine/src/main/resources/resfile/resources/app/vue-app
npm install
2. 开发模式
# 启动 Vite 开发服务器
npm run dev
然后在 DevEco Studio 中运行项目,应用会自动连接到 http://localhost:5173。
3. 生产构建
# 构建 Vue3 应用到鸿蒙平台
npm run build
构建产物会输出到 dist/ 目录,然后在 DevEco Studio 中构建 HAP:
# 在 ohos_hap 目录下
hvigorw assembleHap
项目结构
ohos_hap/
├── electron/ # HAP 入口模块
├── web_engine/ # 核心引擎模块
│ └── src/main/
│ ├── ets/
│ │ ├── adapter/ # 鸿蒙原生适配器
│ │ └── jsbindings/ # JS 绑定层
│ └── resources/resfile/resources/app/
│ ├── main.js # Electron 主进程
│ ├── preload.js # 桥接脚本
│ ├── dist/ # Vue3 构建输出
│ └── vue-app/ # Vue3 源码
│ ├── src/
│ │ ├── composables/useOhos.ts # 原生能力封装
│ │ ├── views/ # 页面组件
│ │ ├── router/ # 路由配置
│ │ └── styles/ # 全局样式
│ ├── vite.config.ts
│ └── package.json
└── docs/ # 文档资料
在 Vue3 中使用原生能力
基本用法
<script setup lang="ts">
import { useOhos } from '@/composables/useOhos'
const {
showNotification,
openFile,
clipboard,
isOhosEnv
} = useOhos()
// 发送系统通知
const notify = async () => {
await showNotification('标题', '这是通知内容')
}
// 打开文件选择器
const selectFile = async () => {
const files = await openFile({
title: '选择图片',
filters: [{ name: '图片', extensions: ['png', 'jpg'] }]
})
console.log('选中:', files)
}
// 剪贴板操作
const copyText = async () => {
await clipboard.write('Hello HarmonyOS!')
const text = await clipboard.read()
}
</script>
可用 API
| 分类 | 方法 | 说明 |
|---|---|---|
| 系统 | getSystemInfo() |
获取系统信息 |
isOhosEnv |
是否在鸿蒙环境 | |
| 文件 | openFile(options?) |
打开文件选择对话框 |
openDirectory(options?) |
打开文件夹选择对话框 | |
saveFile(options?) |
打开保存文件对话框 | |
| 通知 | showNotification(title, body) |
显示系统通知 |
| 剪贴板 | clipboard.read() |
读取剪贴板 |
clipboard.write(text) |
写入剪贴板 | |
| 窗口 | minimizeWindow() |
最小化窗口 |
maximizeWindow() |
最大化/还原窗口 | |
closeWindow() |
关闭窗口 | |
setWindowTitle(title) |
设置窗口标题 | |
setWindowSize(w, h) |
设置窗口大小 |
扩展原生能力
如需添加新的原生 API 桥接,按以下步骤操作:
1. 添加 IPC 处理器 (main.js)
ipcMain.handle('ohos:myNewApi', async (event, params) => {
// 调用 Electron API 或通过 JsBinding 调用鸿蒙原生
return result
})
2. 暴露 API (preload.js)
contextBridge.exposeInMainWorld('ohos', {
// ...existing APIs
myNewApi: (params) => ipcRenderer.invoke('ohos:myNewApi', params),
})
3. 封装 Composable (useOhos.ts)
const myNewApi = async (params: MyParams): Promise<MyResult> => {
if (!ohos) return null
return await ohos.myNewApi(params)
}
开发建议
- 开发时 使用
npm run dev启动 Vite,支持热更新 - 调试时 可在
main.js中取消注释openDevTools()打开开发者工具 - 样式 使用
global.css中定义的 HarmonyOS 风格变量 - 降级处理
useOhos已内置浏览器环境降级,可在普通浏览器中预览
常见问题
Q: 构建报错 "string resource not defined"
检查 electron/src/main/resources/base/element/string.json 是否定义了所需字符串。
Q: 签名配置不匹配
确保 AppScope/app.json5 中的 bundleName 与 build-profile.json5 签名配置一致。
Q: Vue3 热更新不生效
确认 Vite 开发服务器运行在 5173 端口,且 main.js 中 NODE_ENV 为 development。
技术栈
- 前端框架: Vue 3.4 + TypeScript
- 构建工具: Vite 5
- 路由: Vue Router 4
- 状态管理: Pinia 2
- 运行时: Electron (HarmonyOS 定制版)
- 原生层: ArkTS + libadapter.so
License
MIT