ele_suacaiqingxuban:基于 Vue3 生态的 HarmonyOS 桌面应用开发框架

可帮助开发者使用 Vue3 技术栈开发 HarmonyOS 桌面应用,通过内置桥接层让 Vue3 代码直接调用鸿蒙原生 API,支持系统通知、文件操作、剪贴板等能力,提供完整开发流程与热更新支持。【此简介由AI生成】

Branch1Tags0
FilesLast commitLast update
5 months ago
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)
}

开发建议

  1. 开发时 使用 npm run dev 启动 Vite,支持热更新
  2. 调试时 可在 main.js 中取消注释 openDevTools() 打开开发者工具
  3. 样式 使用 global.css 中定义的 HarmonyOS 风格变量
  4. 降级处理 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

Introduction

可帮助开发者使用 Vue3 技术栈开发 HarmonyOS 桌面应用,通过内置桥接层让 Vue3 代码直接调用鸿蒙原生 API,支持系统通知、文件操作、剪贴板等能力,提供完整开发流程与热更新支持。【此简介由AI生成】

Customize your domain