ohos_electron_hap/README.md

HarmonyOS Electron HAP

English | 简体中文

这是一个基于 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

4. 安装和运行

通过 DevEco Studio

直接点击运行按钮安装到设备

通过命令行

hdc app install <已签名hap包路径>
# 示例: hdc app install electron-default-signed.hap

应用定制

修改应用名称

编辑文件：electron/src/main/resources/zh_CN/element/string.json

{
  "string": [
    {
      "name": "EntryAbility_label",
      "value": "您的应用名称"
    }
  ]
}

替换应用图标

将新图标文件放入：AppScope/resources/base/media/

配置启动窗口大小

编辑 electron/src/main/module.json5，在 abilities 中添加 metadata：

"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 特有功能

悬浮窗

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       // 透明度
});

系统权限请求

const { systemPreferences } = require('electron');

// 请求相机权限
systemPreferences.requestSystemPermission('camera').then(granted => {
  console.log('Camera permission:', granted);
});

// 请求目录权限
systemPreferences.requestDirectoryPermission(null).then(granted => {
  console.log('Directory permission:', granted);
});

调试

渲染进程调试

const { BrowserWindow } = require('electron');
const win = new BrowserWindow();
win.webContents.openDevTools();

主进程调试

1. 在 web_engine/src/main/ets/components/WebWindow.ets 中添加调试参数：

let inspect = '--inspect=9229';
let vec_args = [..., inspect];

2. 配置端口转发：

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 权限无法获得，可以暂时注释掉相关权限：

// "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 或联系维护团队。