MyApp — React + Capacitor 鸿蒙 OpenHarmony 示例

基于 hionic CLI 构建的 React + Vite 应用，运行在鸿蒙 OpenHarmony 设备上。

---

项目结构

MyApp/
├── src/                          # React 前端源码
│   ├── App.jsx                   # 主页面（含三插件示例）
│   ├── App.css                   # 样式
│   ├── main.jsx                  # 入口
│   └── ...
├── openharmony/                  # OpenHarmony 原生工程
│   ├── entry/                    # 主模块
│   │   └── src/main/resources/rawfile/www/  # WebView 加载的页面资源
│   └── capacitor/                # Capacitor 桥接模块（C++ + ArkTS 原生代码）
│       └── src/main/
│           ├── cpp/              # C++ 插件代码
│           ├── ets/              # ArkTS 插件代码
│           └── resources/rawfile/ # 桥接文件（cordova.js, native-bridge.js）
├── public/                       # 静态资源
├── dist/                         # Vite 构建产物
├── dev.md                        # 开发踩坑记录（详细适配过程）
├── index.html                    # HTML 入口
├── config.xml                    # Cordova 插件配置
├── package.json
└── vite.config.js

---

快速开始

前置条件

• hionic CLI 全局安装
• DevEco Studio 5.0+（含 HarmonyOS SDK 5.0+）
• 鸿蒙设备或模拟器

安装

# 1. 初始化项目
hionic start capacitor MyApp --template react-ts

# 2. 安装插件
hionic plugin add @capacitor/camera
hionic plugin add @ionic-native/in-app-browser
hionic plugin add @ionic-native/device

开发

npm run dev

构建与部署

# 1. 构建前端
npm run build

# 2. 同步到原生工程（注意 WebView 加载路径）
WWW=openharmony/entry/src/main/resources/rawfile/www
cp cordova_plugins.js "$WWW/"
cp node_modules/@capacitor/core/cordova.js "$WWW/"
cp -r dist/assets/* "$WWW/assets/"

# 3. 构建 HAP（使用 DevEco 内置 Node.js）
cd openharmony
NODE_HOME=/Applications/DevEco-Studio.app/Contents/tools/node \
  hvigorw assembleApp --no-daemon -p product=default

# 4. 安装到设备
hdc install entry/build/default/outputs/default/entry-default-signed.hap
hdc shell aa start -a EntryAbility -b <bundle-name>

---

集成插件说明

插件	类型	调用方式	说明
@capacitor/camera	Capacitor	import { Camera } from '@capacitor/camera'	✅ 原生 C++，正常工作
@ionic-native/in-app-browser	Cordova	window.InAppBrowser.create(url)	✅ 原生 C++，正常工作
@ionic-native/device	Cordova	window.device	⚠️ 原生 C++ 桥不可用，使用纯 JS 回退方案

相机

import { Camera } from '@capacitor/camera'

const photo = await Camera.getPhoto({ quality: 90 })

InAppBrowser

const ref = window.InAppBrowser.create('https://example.com', '_blank', options)

设备信息

通过 纯 JavaScript 获取（不依赖原生桥）：

// 方式一：通过 window.device（由 cordova_plugins.js 注入）
const model = window.device?.model

// 方式二：直接浏览器 API
const platform = Capacitor.getPlatform()      // 提示：hionic 返回 'android'
const model = navigator.userAgent.match(/; ([^;]+?)(?:;|\))/)

注意：hionic 的 C++ 桥注册为 androidBridge（兼容标准 Capacitor），导致 Capacitor.getPlatform() 返回 'android'。需用 TsCapacitorPlugin 二次判断：

function isHionic() {
  return !!(window.Capacitor?.Plugins?.TsCapacitorPlugin)
}
const platform = isHionic() ? 'OpenHarmony' : Capacitor.getPlatform()

---

已知踩坑

详细适配过程见 dev.md，这里列出关键问题：

#	问题	解决
1	插件安装到 cordova/ 模块，项目用 capacitor/ 模块	手动复制 C++/ArkTS 代码
2	C++ 插件只注册 Cordova 桥，JS 层用 Capacitor 桥通信	无法两全，改用纯 JS 方案
3	@capacitor/core/cordova.js 的 define 闭包隔离	放弃模块系统，IIFE 直接注入
4	WebView 加载 rawfile/www/，一直误改 rawfile/	确认正确路径
5	桥接注册为 androidBridge，platform 误判为 Android	用 TsCapacitorPlugin 检测

---

构建环境

• Node.js：DevEco Studio 内置 v18.20.1（Homebrew v26 与 hvigor 不兼容）
• SDK：HarmonyOS SDK 5.0+
• IDE：DevEco Studio 5.0+

构建时需设置 NODE_HOME：

export NODE_HOME=/Applications/DevEco-Studio.app/Contents/tools/node

---

参考资源

• hionic CLI
• @ionic-native/device 鸿蒙版
• @ionic-native/in-app-browser 鸿蒙版
• Vite + React
• Capacitor

---

License

MIT