228 lines
5.5 KiB
Markdown
228 lines
5.5 KiB
Markdown
# HarmonyOS Electron HAP
|
||
|
||
[English](./README.md) | 简体中文
|
||
|
||
这是一个基于 HarmonyOS 平台的 Electron 应用程序包（HAP）项目，支持在鸿蒙设备上运行 Electron 应用。
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
ohos_electron_hap/
|
||
├── AppScope/ # 应用范围配置
|
||
├── chromium/ # Chromium 模块
|
||
├── electron/ # Electron 主模块
|
||
├── web_engine/ # Web 引擎组件
|
||
├── hvigor/ # 构建工具配置
|
||
├── build-profile.json5 # 项目构建配置
|
||
├── hvigorfile.ts # 构建脚本
|
||
└── oh-package.json5 # 项目依赖配置
|
||
```
|
||
|
||
## 快速开始
|
||
|
||
### 环境要求
|
||
|
||
- **DevEco Studio**: 4.0 或更高版本
|
||
- **HarmonyOS SDK**: API Level 10 或更高
|
||
- **Node.js**: 16.x 或更高版本
|
||
- **HDC工具**: 用于设备调试和安装
|
||
|
||
### 1. 准备资源文件
|
||
|
||
在开始构建之前，需要准备以下资源：
|
||
|
||
#### Electron 应用代码
|
||
将您的 Electron 应用代码（编译后的产物）放入：
|
||
```
|
||
web_engine/src/main/resources/resfile/resources/app/
|
||
```
|
||
|
||
### 2. 构建 HAP 包
|
||
|
||
#### 使用 DevEco Studio
|
||
1. 用 DevEco Studio 打开项目
|
||
2. 选择 **Build** → **Build Hap(s)/APP(s)** → **Build Hap(s)**
|
||
3. 或点击右上角的运行按钮启动应用
|
||
|
||
构建完成后，未签名的 HAP 包将保存在：
|
||
```
|
||
electron/build/default/outputs/default/electron-default-unsigned.hap
|
||
```
|
||
|
||
### 3. 应用签名
|
||
|
||
为了在设备上正常运行，需要对 HAP 包进行签名：
|
||
|
||
> 建议使用自动签名验证
|
||
1. 申请华为开发者证书
|
||
2. 在 DevEco Studio 中配置签名信息
|
||
3. 重新构建生成已签名的 HAP 包
|
||
|
||
详细签名流程请参考：[应用/服务签名-DevEco Studio](https://developer.huawei.com/)
|
||
|
||
### 4. 安装和运行
|
||
|
||
#### 通过 DevEco Studio
|
||
直接点击运行按钮安装到设备
|
||
|
||
#### 通过命令行
|
||
```bash
|
||
hdc app install <已签名hap包路径>
|
||
# 示例: hdc app install electron-default-signed.hap
|
||
```
|
||
|
||
## 应用定制
|
||
|
||
### 修改应用名称
|
||
编辑文件：`electron/src/main/resources/zh_CN/element/string.json`
|
||
```json
|
||
{
|
||
"string": [
|
||
{
|
||
"name": "EntryAbility_label",
|
||
"value": "您的应用名称"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### 替换应用图标
|
||
将新图标文件放入：`AppScope/resources/base/media/`
|
||
|
||
### 配置启动窗口大小
|
||
编辑 `electron/src/main/module.json5`，在 abilities 中添加 metadata：
|
||
```json
|
||
"metadata": [
|
||
{
|
||
"name": "ohos.ability.window.height",
|
||
"value": "800"
|
||
},
|
||
{
|
||
"name": "ohos.ability.window.width",
|
||
"value": "800"
|
||
},
|
||
{
|
||
"name": "ohos.ability.window.left",
|
||
"value": "center"
|
||
},
|
||
{
|
||
"name": "ohos.ability.window.top",
|
||
"value": "center"
|
||
}
|
||
]
|
||
```
|
||
|
||
## 权限配置
|
||
|
||
应用权限在 `web_engine/src/main/module.json5` 文件的 `requestPermissions` 字段中配置。
|
||
|
||
### 基础权限（无需特殊申请）
|
||
- `ohos.permission.INTERNET` - 网络访问
|
||
- `ohos.permission.GET_NETWORK_INFO` - 获取网络信息
|
||
- `ohos.permission.RUNNING_LOCK` - 后台运行锁
|
||
- `ohos.permission.PREPARE_APP_TERMINATE` - 应用终止准备
|
||
|
||
### 需要申请的权限
|
||
- `ohos.permission.CAMERA` - 相机权限
|
||
- `ohos.permission.MICROPHONE` - 麦克风权限
|
||
- `ohos.permission.LOCATION` - 位置权限
|
||
- `ohos.permission.READ_WRITE_DOWNLOAD_DIRECTORY` - 下载目录访问
|
||
|
||
## HarmonyOS 特有功能
|
||
|
||
### 悬浮窗
|
||
```javascript
|
||
const { BrowserWindow } = require('electron');
|
||
|
||
let floatWindow = new BrowserWindow({
|
||
windowInfo: {
|
||
type: 'floatWindow' // mainWindow, subWindow, floatWindow
|
||
},
|
||
parent: mainWindow,
|
||
x: 100,
|
||
y: 100,
|
||
width: 800,
|
||
height: 600,
|
||
transparent: true, // 透明窗口
|
||
opacity: 0.5 // 透明度
|
||
});
|
||
```
|
||
|
||
### 系统权限请求
|
||
```javascript
|
||
const { systemPreferences } = require('electron');
|
||
|
||
// 请求相机权限
|
||
systemPreferences.requestSystemPermission('camera').then(granted => {
|
||
console.log('Camera permission:', granted);
|
||
});
|
||
|
||
// 请求目录权限
|
||
systemPreferences.requestDirectoryPermission(null).then(granted => {
|
||
console.log('Directory permission:', granted);
|
||
});
|
||
```
|
||
|
||
## 调试
|
||
|
||
### 渲染进程调试
|
||
```javascript
|
||
const { BrowserWindow } = require('electron');
|
||
const win = new BrowserWindow();
|
||
win.webContents.openDevTools();
|
||
```
|
||
|
||
### 主进程调试
|
||
1. 在 `web_engine/src/main/ets/components/WebWindow.ets` 中添加调试参数：
|
||
```typescript
|
||
let inspect = '--inspect=9229';
|
||
let vec_args = [..., inspect];
|
||
```
|
||
|
||
2. 配置端口转发：
|
||
```bash
|
||
hdc fport tcp:9229 tcp:9229
|
||
```
|
||
|
||
3. 在 Chrome 浏览器中访问：`chrome://inspect`
|
||
|
||
## 应用数据目录
|
||
|
||
- 用户数据默认存储在：`/data/storage/el2/base/files`
|
||
- 应用安装目录：`/data/storage/el1/bundle`
|
||
- 数据库目录：`/data/storage/el2/database`
|
||
|
||
## 常见问题
|
||
|
||
### 构建失败
|
||
1. 检查 SO 库文件是否完整
|
||
2. 确认 Electron 应用代码已正确放置
|
||
3. 验证权限配置是否正确
|
||
|
||
### 三方库兼容性
|
||
- **C++ addon**: 需要重新编译适配鸿蒙平台
|
||
- **平台检测**: 需要适配 `process.platform === 'ohos'`
|
||
- **二进制文件**: 可能需要替换为鸿蒙版本
|
||
|
||
### 权限问题
|
||
如果某些 ACL 权限无法获得，可以暂时注释掉相关权限：
|
||
```json
|
||
// "requestPermissions": [
|
||
// {
|
||
// "name": "ohos.permission.SYSTEM_FLOAT_WINDOW"
|
||
// }
|
||
// ]
|
||
```
|
||
|
||
## 贡献指南
|
||
|
||
1. Fork 本仓库
|
||
2. 创建功能分支：`git checkout -b feature/your-feature`
|
||
3. 提交更改：`git commit -am 'Add some feature'`
|
||
4. 推送到分支：`git push origin feature/your-feature`
|
||
5. 提交 Pull Request
|
||
|
||
## 联系我们
|
||
|
||
如遇到问题或需要支持，请提交 Issue 或联系维护团队。
|