mirror of
https://gitee.com/dromara/electron-egg.git
synced 2026-06-13 03:11:10 +08:00
doc
This commit is contained in:
gaoshuaixing
2
.gitignore
vendored
2
.gitignore
vendored
@@ -22,7 +22,7 @@ python/dist/
|
||||
*DS_Store
|
||||
|
||||
# 忽略鸿蒙相关文件
|
||||
ohos_hap/docs/
|
||||
#ohos_hap/docs/
|
||||
ohos_hap/.idea
|
||||
ohos_hap/.appanalyzer
|
||||
ohos_hap/.hvigor
|
||||
|
||||
BIN
ohos_hap/docs/Electron框架命令行参数支持说明.zip
Normal file
BIN
ohos_hap/docs/Electron框架命令行参数支持说明.zip
Normal file
Binary file not shown.
BIN
ohos_hap/docs/callArkTSFunction接口文档与示例.zip
Normal file
BIN
ohos_hap/docs/callArkTSFunction接口文档与示例.zip
Normal file
Binary file not shown.
BIN
ohos_hap/docs/electron-example.zip
Normal file
BIN
ohos_hap/docs/electron-example.zip
Normal file
Binary file not shown.
BIN
ohos_hap/docs/electron-napi-library.zip
Normal file
BIN
ohos_hap/docs/electron-napi-library.zip
Normal file
Binary file not shown.
BIN
ohos_hap/docs/electron调用ets指导文档0411.pdf
Normal file
BIN
ohos_hap/docs/electron调用ets指导文档0411.pdf
Normal file
Binary file not shown.
BIN
ohos_hap/docs/ets-adapter.zip
Normal file
BIN
ohos_hap/docs/ets-adapter.zip
Normal file
Binary file not shown.
129
ohos_hap/docs/目录结构.md
Normal file
129
ohos_hap/docs/目录结构.md
Normal file
@@ -0,0 +1,129 @@
|
||||
# 目录结构总览
|
||||
|
||||
## 官方配置链接
|
||||
|
||||
- [AppScope/app.json5](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/app-configuration-file)
|
||||
- [**/module.json5](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/module-configuration-file)
|
||||
- [**/oh-package.json5](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/ide-ohpm-cli)
|
||||
|
||||
|
||||
## 开发只需关注以下目录
|
||||
|
||||
- `AppScope/` 鸿蒙应用工程根目录
|
||||
- `web_engine/src/main/resources/resfile/resources/` 代码及资源
|
||||
|
||||
## 目录结构说明
|
||||
|
||||
```
|
||||
ohos_hap/ # 鸿蒙应用工程根目录
|
||||
├── AppScope/ # 应用级公共资源与配置
|
||||
│ ├── app.json5 # 应用全局配置（包名、版本、图标等）
|
||||
│ └── resources/ # 应用级资源（图标、字符串等）
|
||||
├── build-profile.json5 # 工程级构建配置
|
||||
├── oh-package.json5 # 工程级包管理配置
|
||||
├── hvigor/ # Hvigor 构建工具配置
|
||||
│
|
||||
├── electron/ # 【主模块】Entry HAP（应用入口）
|
||||
│ ├── src/main/
|
||||
│ │ ├── ets/
|
||||
│ │ │ ├── Application/
|
||||
│ │ │ │ └── AbilityStage.ets # AbilityStage 生命周期管理（继承 WebAbilityStage）
|
||||
│ │ │ ├── entryability/
|
||||
│ │ │ │ ├── EntryAbility.ets # 主入口 Ability（桌面图标启动）
|
||||
│ │ │ │ ├── BrowserAbility.ets # 浏览器模式 Ability（独立进程）
|
||||
│ │ │ │ ├── StatelessAbility.ets # 无状态 Ability（辅助窗口）
|
||||
│ │ │ │ └── TaskManagerAbility.ets # 任务管理 Ability
|
||||
│ │ │ ├── extensionAbility/
|
||||
│ │ │ │ └── BrowserEmbeddedAbility.ets # 嵌入式 UI 扩展 Ability
|
||||
│ │ │ ├── pages/
|
||||
│ │ │ │ ├── Index.ets # 主页面（加载 WebWindow 组件）
|
||||
│ │ │ │ ├── WebPage.ets # Web 内容页面
|
||||
│ │ │ │ ├── WindowNode.ets # 窗口节点页面（浏览器模式）
|
||||
│ │ │ │ ├── SubWindow.ets # 子窗口页面
|
||||
│ │ │ │ ├── NodeHandleWindow.ets # 节点句柄窗口（支持 NodeHandle 特性）
|
||||
│ │ │ │ └── ...
|
||||
│ │ │ └── process/
|
||||
│ │ │ └── CustomChildProcess.ets # 自定义子进程（渲染进程封装）
|
||||
│ │ ├── resources/ # 模块级资源文件
|
||||
│ │ └── module.json5 # 模块配置（Ability 声明、权限等）
|
||||
│ ├── build-profile.json5 # 模块构建配置
|
||||
│ ├── oh-package.json5 # 模块包配置（依赖 web_engine）
|
||||
│ └── hvigorfile.ts # Hvigor 构建脚本
|
||||
│
|
||||
├── web_engine/ # 【引擎模块】HAR 静态库（可复用）
|
||||
│ ├── src/main/
|
||||
│ │ ├── ets/
|
||||
│ │ │ ├── ability/
|
||||
│ │ │ │ ├── WebAbility.ets # 基础 Web Ability（封装窗口与生命周期）
|
||||
│ │ │ │ ├── WebBaseAbility.ets # WebAbility 基类（参数解析、Native 初始化）
|
||||
│ │ │ │ ├── WebEmbeddedAbility.ets # 嵌入式 Ability
|
||||
│ │ │ │ └── WebBaseExtensionAbility.ets # 扩展 Ability 基类
|
||||
│ │ │ ├── application/
|
||||
│ │ │ │ └── WebAbilityStage.ets # 全局 AbilityStage（应用级生命周期、多实例管理）
|
||||
│ │ │ ├── adapter/ # 系统能力适配层（桥接鸿蒙 API）
|
||||
│ │ │ │ ├── AccessibilityAdapter.ets # 无障碍适配
|
||||
│ │ │ │ ├── AppLifecycleAdapter.ets # 应用生命周期适配
|
||||
│ │ │ │ ├── AppWindowAdapter.ets # 应用窗口适配
|
||||
│ │ │ │ ├── BluetoothAdapter.ets # 蓝牙适配
|
||||
│ │ │ │ ├── BrowserPolicyAdapter.ets # 浏览器策略适配
|
||||
│ │ │ │ ├── ContextAdapter.ets # 上下文适配
|
||||
│ │ │ │ ├── CursorAdapter.ets # 光标适配
|
||||
│ │ │ │ ├── DeviceAdapter.ets # 设备信息适配
|
||||
│ │ │ │ ├── DialogAdapter.ets # 对话框适配
|
||||
│ │ │ │ ├── DisplayAdapter.ets # 显示适配（分辨率、DPI）
|
||||
│ │ │ │ ├── DragDropAdapter.ets # 拖拽适配
|
||||
│ │ │ │ ├── ElectronAppAdapter.ets # Electron 应用级适配（语言、通知等）
|
||||
│ │ │ │ ├── FileManagerAdapter.ets # 文件管理适配
|
||||
│ │ │ │ ├── IMFAdapter.ets # 输入法适配
|
||||
│ │ │ │ ├── MediaAdapter.ets # 媒体适配
|
||||
│ │ │ │ ├── NativeThemeAdapter.ets # 原生主题适配（深色/浅色模式）
|
||||
│ │ │ │ ├── NotificationAdapter.ets # 通知适配
|
||||
│ │ │ │ ├── PermissionManagerAdapter.ets # 权限管理适配
|
||||
│ │ │ │ ├── PrintAdapter.ets # 打印适配
|
||||
│ │ │ │ ├── ScreenshotAdapter.ets # 截图适配
|
||||
│ │ │ │ ├── StatusBarManager.ets # 状态栏管理
|
||||
│ │ │ │ └── ... (共 40+ 个适配器)
|
||||
│ │ │ ├── common/ # 公共基础设施
|
||||
│ │ │ │ ├── BaseAdapter.ets # 适配器基类（依赖注入、NativeContext 获取）
|
||||
│ │ │ │ ├── Constants.ets # 全局常量定义（枚举、配置）
|
||||
│ │ │ │ ├── InjectModule.ets # 依赖注入容器（基于 Inversify）
|
||||
│ │ │ │ ├── ModuleType.ts # 模块类型标识
|
||||
│ │ │ │ ├── AbilityManager.ets # Ability 管理器
|
||||
│ │ │ │ └── ...
|
||||
│ │ │ ├── components/ # UI 组件封装
|
||||
│ │ │ │ ├── WebWindow.ets # 主窗口组件（XComponent 封装）
|
||||
│ │ │ │ ├── WebSubWindow.ets # 子窗口组件
|
||||
│ │ │ │ ├── WebEmbeddedWindow.ets # 嵌入式窗口组件
|
||||
│ │ │ │ ├── WebWindowNode.ets # 窗口节点组件
|
||||
│ │ │ │ └── MessageBox.ets # 消息对话框组件
|
||||
│ │ │ ├── interface/ # 接口定义
|
||||
│ │ │ │ ├── CommonInterface.ts # 公共接口（NativeContext、窗口边界等）
|
||||
│ │ │ │ ├── Dependency.ets # 依赖接口
|
||||
│ │ │ │ └── WebProxy.ets # Web 代理接口
|
||||
│ │ │ ├── jsbindings/ # JS 绑定层（Ability -> Native 桥接）
|
||||
│ │ │ │ └── ...AdapterBind.ets # 各适配器的 JS 绑定入口
|
||||
│ │ │ ├── utils/ # 工具类
|
||||
│ │ │ │ ├── JsBindingUtils.ets # Native 绑定工具
|
||||
│ │ │ │ ├── LogUtil.ets # 日志工具
|
||||
│ │ │ │ └── ...
|
||||
│ │ │ └── process/
|
||||
│ │ │ └── WebChildProcess.ets # 子进程基类（渲染进程）
|
||||
│ │ ├── cpp/
|
||||
│ │ │ └── types/libadapter/ # Native 库类型声明
|
||||
│ │ │ ├── index.d.ts # libadapter.so NAPI 接口声明
|
||||
│ │ │ └── oh-package.json5 # Native 库包配置
|
||||
│ │ ├── resources/ # 模块资源
|
||||
│ │ └── module.json5 # 模块配置（权限声明等）
|
||||
│ ├── build-profile.json5 # 模块构建配置
|
||||
│ ├── oh-package.json5 # 模块包配置（依赖 inversify、reflect-metadata）
|
||||
│ ├── Index.ets # 模块入口导出
|
||||
│ ├── childProcess.ets # 子进程入口导出
|
||||
│ └── hvigorfile.ts # Hvigor 构建脚本
|
||||
│
|
||||
└── ...
|
||||
|
||||
---
|
||||
|
||||
|
||||
|
||||
|
||||
346
ohos_hap/docs/项目导读.md
Normal file
346
ohos_hap/docs/项目导读.md
Normal file
@@ -0,0 +1,346 @@
|
||||
# 鸿蒙 Electron 应用项目结构分析
|
||||
|
||||
## 一、项目概述
|
||||
|
||||
本项目是 **HarmonyOS（鸿蒙）平台上的 Electron 应用封装层**，基于鸿蒙 Stage 模型开发。项目将 Chromium/Electron 核心引擎移植到鸿蒙系统，通过 ArkTS 封装鸿蒙系统 API，为 Electron 上层应用提供底层能力支持。
|
||||
|
||||
**应用包名**: `com.huawei.ohos_electron`
|
||||
**目标平台**: HarmonyOS 5.0.5+ / API 12+
|
||||
**支持设备**: 2in1（二合一设备）、Tablet（平板）
|
||||
**构建工具**: Hvigor（鸿蒙官方构建系统）
|
||||
|
||||
---
|
||||
|
||||
## 二、整体架构
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ Electron 应用 (上层业务) │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ electron (entry HAP) │ 应用入口、页面、Ability 生命周期管理 │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ web_engine (HAR 库) │ 引擎封装、系统适配、Native 桥接层 │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ libelectron.so │ Chromium + Electron 核心 Native 引擎 │
|
||||
│ libadapter.so │ 鸿蒙平台 Native 适配层 (C++) │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ HarmonyOS 系统 API │ 窗口、文件、网络、权限、设备能力 │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
**模块关系**:
|
||||
- `electron` 模块依赖 `web_engine` 模块（通过本地文件引用）
|
||||
- `web_engine` 模块依赖 `libadapter.so` Native 库（通过 NAPI 接口）
|
||||
- `libadapter.so` 与 `libelectron.so` 协同工作，提供完整的浏览器引擎能力
|
||||
|
||||
---
|
||||
|
||||
## 三、目录结构总览
|
||||
|
||||
```
|
||||
ohos_hap/ # 鸿蒙应用工程根目录
|
||||
├── AppScope/ # 应用级公共资源与配置
|
||||
│ ├── app.json5 # 应用全局配置（包名、版本、图标等）
|
||||
│ └── resources/ # 应用级资源（图标、字符串等）
|
||||
├── build-profile.json5 # 工程级构建配置
|
||||
├── oh-package.json5 # 工程级包管理配置
|
||||
├── hvigor/ # Hvigor 构建工具配置
|
||||
│
|
||||
├── electron/ # 【主模块】Entry HAP（应用入口）
|
||||
│ ├── src/main/
|
||||
│ │ ├── ets/
|
||||
│ │ │ ├── Application/
|
||||
│ │ │ │ └── AbilityStage.ets # AbilityStage 生命周期管理（继承 WebAbilityStage）
|
||||
│ │ │ ├── entryability/
|
||||
│ │ │ │ ├── EntryAbility.ets # 主入口 Ability（桌面图标启动）
|
||||
│ │ │ │ ├── BrowserAbility.ets # 浏览器模式 Ability（独立进程）
|
||||
│ │ │ │ ├── StatelessAbility.ets # 无状态 Ability（辅助窗口）
|
||||
│ │ │ │ └── TaskManagerAbility.ets # 任务管理 Ability
|
||||
│ │ │ ├── extensionAbility/
|
||||
│ │ │ │ └── BrowserEmbeddedAbility.ets # 嵌入式 UI 扩展 Ability
|
||||
│ │ │ ├── pages/
|
||||
│ │ │ │ ├── Index.ets # 主页面（加载 WebWindow 组件）
|
||||
│ │ │ │ ├── WebPage.ets # Web 内容页面
|
||||
│ │ │ │ ├── WindowNode.ets # 窗口节点页面（浏览器模式）
|
||||
│ │ │ │ ├── SubWindow.ets # 子窗口页面
|
||||
│ │ │ │ ├── NodeHandleWindow.ets # 节点句柄窗口（支持 NodeHandle 特性）
|
||||
│ │ │ │ └── ...
|
||||
│ │ │ └── process/
|
||||
│ │ │ └── CustomChildProcess.ets # 自定义子进程（渲染进程封装）
|
||||
│ │ ├── resources/ # 模块级资源文件
|
||||
│ │ └── module.json5 # 模块配置（Ability 声明、权限等）
|
||||
│ ├── build-profile.json5 # 模块构建配置
|
||||
│ ├── oh-package.json5 # 模块包配置（依赖 web_engine）
|
||||
│ └── hvigorfile.ts # Hvigor 构建脚本
|
||||
│
|
||||
├── web_engine/ # 【引擎模块】HAR 静态库（可复用）
|
||||
│ ├── src/main/
|
||||
│ │ ├── ets/
|
||||
│ │ │ ├── ability/
|
||||
│ │ │ │ ├── WebAbility.ets # 基础 Web Ability（封装窗口与生命周期）
|
||||
│ │ │ │ ├── WebBaseAbility.ets # WebAbility 基类（参数解析、Native 初始化）
|
||||
│ │ │ │ ├── WebEmbeddedAbility.ets # 嵌入式 Ability
|
||||
│ │ │ │ └── WebBaseExtensionAbility.ets # 扩展 Ability 基类
|
||||
│ │ │ ├── application/
|
||||
│ │ │ │ └── WebAbilityStage.ets # 全局 AbilityStage（应用级生命周期、多实例管理）
|
||||
│ │ │ ├── adapter/ # 系统能力适配层（桥接鸿蒙 API）
|
||||
│ │ │ │ ├── AccessibilityAdapter.ets # 无障碍适配
|
||||
│ │ │ │ ├── AppLifecycleAdapter.ets # 应用生命周期适配
|
||||
│ │ │ │ ├── AppWindowAdapter.ets # 应用窗口适配
|
||||
│ │ │ │ ├── BluetoothAdapter.ets # 蓝牙适配
|
||||
│ │ │ │ ├── BrowserPolicyAdapter.ets # 浏览器策略适配
|
||||
│ │ │ │ ├── ContextAdapter.ets # 上下文适配
|
||||
│ │ │ │ ├── CursorAdapter.ets # 光标适配
|
||||
│ │ │ │ ├── DeviceAdapter.ets # 设备信息适配
|
||||
│ │ │ │ ├── DialogAdapter.ets # 对话框适配
|
||||
│ │ │ │ ├── DisplayAdapter.ets # 显示适配（分辨率、DPI）
|
||||
│ │ │ │ ├── DragDropAdapter.ets # 拖拽适配
|
||||
│ │ │ │ ├── ElectronAppAdapter.ets # Electron 应用级适配（语言、通知等）
|
||||
│ │ │ │ ├── FileManagerAdapter.ets # 文件管理适配
|
||||
│ │ │ │ ├── IMFAdapter.ets # 输入法适配
|
||||
│ │ │ │ ├── MediaAdapter.ets # 媒体适配
|
||||
│ │ │ │ ├── NativeThemeAdapter.ets # 原生主题适配（深色/浅色模式）
|
||||
│ │ │ │ ├── NotificationAdapter.ets # 通知适配
|
||||
│ │ │ │ ├── PermissionManagerAdapter.ets # 权限管理适配
|
||||
│ │ │ │ ├── PrintAdapter.ets # 打印适配
|
||||
│ │ │ │ ├── ScreenshotAdapter.ets # 截图适配
|
||||
│ │ │ │ ├── StatusBarManager.ets # 状态栏管理
|
||||
│ │ │ │ └── ... (共 40+ 个适配器)
|
||||
│ │ │ ├── common/ # 公共基础设施
|
||||
│ │ │ │ ├── BaseAdapter.ets # 适配器基类（依赖注入、NativeContext 获取）
|
||||
│ │ │ │ ├── Constants.ets # 全局常量定义（枚举、配置）
|
||||
│ │ │ │ ├── InjectModule.ets # 依赖注入容器（基于 Inversify）
|
||||
│ │ │ │ ├── ModuleType.ts # 模块类型标识
|
||||
│ │ │ │ ├── AbilityManager.ets # Ability 管理器
|
||||
│ │ │ │ └── ...
|
||||
│ │ │ ├── components/ # UI 组件封装
|
||||
│ │ │ │ ├── WebWindow.ets # 主窗口组件（XComponent 封装）
|
||||
│ │ │ │ ├── WebSubWindow.ets # 子窗口组件
|
||||
│ │ │ │ ├── WebEmbeddedWindow.ets # 嵌入式窗口组件
|
||||
│ │ │ │ ├── WebWindowNode.ets # 窗口节点组件
|
||||
│ │ │ │ └── MessageBox.ets # 消息对话框组件
|
||||
│ │ │ ├── interface/ # 接口定义
|
||||
│ │ │ │ ├── CommonInterface.ts # 公共接口（NativeContext、窗口边界等）
|
||||
│ │ │ │ ├── Dependency.ets # 依赖接口
|
||||
│ │ │ │ └── WebProxy.ets # Web 代理接口
|
||||
│ │ │ ├── jsbindings/ # JS 绑定层（Ability -> Native 桥接）
|
||||
│ │ │ │ └── ...AdapterBind.ets # 各适配器的 JS 绑定入口
|
||||
│ │ │ ├── utils/ # 工具类
|
||||
│ │ │ │ ├── JsBindingUtils.ets # Native 绑定工具
|
||||
│ │ │ │ ├── LogUtil.ets # 日志工具
|
||||
│ │ │ │ └── ...
|
||||
│ │ │ └── process/
|
||||
│ │ │ └── WebChildProcess.ets # 子进程基类（渲染进程）
|
||||
│ │ ├── cpp/
|
||||
│ │ │ └── types/libadapter/ # Native 库类型声明
|
||||
│ │ │ ├── index.d.ts # libadapter.so NAPI 接口声明
|
||||
│ │ │ └── oh-package.json5 # Native 库包配置
|
||||
│ │ ├── resources/ # 模块资源
|
||||
│ │ └── module.json5 # 模块配置（权限声明等）
|
||||
│ ├── build-profile.json5 # 模块构建配置
|
||||
│ ├── oh-package.json5 # 模块包配置（依赖 inversify、reflect-metadata）
|
||||
│ ├── Index.ets # 模块入口导出
|
||||
│ ├── childProcess.ets # 子进程入口导出
|
||||
│ └── hvigorfile.ts # Hvigor 构建脚本
|
||||
│
|
||||
└── docs/ # 项目文档
|
||||
├── Electron框架命令行参数支持说明.zip
|
||||
├── callArkTSFunction接口文档与示例.zip
|
||||
├── electron调用ets指导文档0411.pdf
|
||||
└── ...
|
||||
|
||||
lib.unstripped/ # 【调试库目录】（与 ohos_hap 同级）
|
||||
├── libelectron.so # Electron 引擎未裁剪符号库（调试专用）
|
||||
└── libadapter.so # 鸿蒙适配层未裁剪符号库（调试专用）
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 四、模块详细说明
|
||||
|
||||
### 4.1 根目录配置 (`ohos_hap/`)
|
||||
|
||||
| 文件 | 功能说明 |
|
||||
|------|----------|
|
||||
| `build-profile.json5` | 工程级构建配置。定义了 `electron`（entry 模块）和 `web_engine`（HAR 模块）两个子模块，SDK 版本为 HarmonyOS 5.0.5(17)，目标版本 6.1.0(23) |
|
||||
| `oh-package.json5` | 工程级包配置，名称为 `ohos_hap`，版本 1.0.0 |
|
||||
| `AppScope/app.json5` | 应用全局配置。声明包名 `com.huawei.ohos_electron`，多实例模式 `multiInstance`，最大实例数 1 |
|
||||
|
||||
### 4.2 `electron` 模块（Entry HAP）
|
||||
|
||||
**模块类型**: `entry`（应用入口模块）
|
||||
**作用**: 提供应用的 Ability 入口、页面路由和资源，是用户直接交互的载体。
|
||||
|
||||
#### 核心 Ability
|
||||
|
||||
| Ability | 类型 | 进程 | 功能说明 |
|
||||
|---------|------|------|----------|
|
||||
| `EntryAbility` | UIAbility | 主进程 | 应用主入口。接收 `action.system.home` 和 `ohos.want.action.viewData` 意图，支持桌面图标启动和 URL 唤起 |
|
||||
| `BrowserAbility` | UIAbility | `:browser` | 浏览器模式 Ability。运行在独立进程，用于隔离网页渲染 |
|
||||
| `StatelessAbility` | UIAbility | `:browser` | 无状态辅助窗口 Ability，支持 `specified` 启动模式 |
|
||||
| `TaskManagerAbility` | UIAbility | 主进程 | 任务管理器 Ability |
|
||||
| `BrowserEmbeddedAbility` | EmbeddedUIExtensionAbility | - | 嵌入式 UI 扩展，支持在其他应用中嵌入 Electron 页面 |
|
||||
| `StatusBarEntryAbility` | UIExtensionAbility | - | 状态栏扩展 Ability |
|
||||
|
||||
#### 页面结构
|
||||
|
||||
| 页面 | 功能 |
|
||||
|------|------|
|
||||
| `Index.ets` | 主页面。使用 `WebWindow` 组件渲染 Web 内容，管理状态栏高度和样式 |
|
||||
| `WindowNode.ets` | 浏览器模式窗口页面（供 `BrowserAbility` 使用） |
|
||||
| `SubWindow.ets` | 子窗口页面 |
|
||||
| `NodeHandleWindow.ets` | 基于 NodeHandle 的窗口页面（新架构） |
|
||||
| `NodeHandleSubWindow.ets` | 基于 NodeHandle 的子窗口 |
|
||||
| `WebPage.ets` | 通用 Web 内容页面 |
|
||||
| `Login.ets` | 登录页面 |
|
||||
|
||||
#### 进程管理
|
||||
|
||||
- `CustomChildProcess.ets`: 继承 `WebChildProcess`，封装鸿蒙 `ChildProcess` 能力，用于启动独立的渲染进程。
|
||||
|
||||
### 4.3 `web_engine` 模块（HAR 库）
|
||||
|
||||
**模块类型**: `har`（静态共享库）
|
||||
**作用**: 封装 Electron 引擎核心能力，提供系统适配层，供 `electron` 模块或其他应用复用。
|
||||
|
||||
#### 核心类
|
||||
|
||||
| 类/文件 | 功能说明 |
|
||||
|---------|----------|
|
||||
| `WebAbilityStage` | 全局 `AbilityStage` 封装。管理应用生命周期、多实例路由（`onAcceptWant` 根据 `instanceKey` / `appId` 分发实例）、应用退出处理（`onPrepareTerminationAsync`） |
|
||||
| `WebBaseAbility` | Ability 基类。处理启动参数解析（`xcomponentId`、`cmdArgs`、`appId` 等）、初始化 Native 上下文、绑定 `XComponent` 渲染表面 |
|
||||
| `WebAbility` | 主窗口 Ability 封装。集成窗口管理、生命周期回调、主题切换、权限初始化等能力 |
|
||||
| `WebChildProcess` | 子进程基类。在渲染进程中初始化 Native 上下文并调用 `runOtherProcessType` |
|
||||
|
||||
#### 适配器层 (`adapter/`)
|
||||
|
||||
适配器层是 `web_engine` 的核心，负责将鸿蒙系统能力桥接到 Electron 引擎。采用 **依赖注入（Inversify）** 架构，所有适配器继承自 `BaseAdapter`。
|
||||
|
||||
| 适配器 | 功能 |
|
||||
|--------|------|
|
||||
| `AppLifecycleAdapter` | 应用生命周期事件（前后台切换） |
|
||||
| `AppWindowAdapter` | 应用窗口管理（创建、销毁、焦点） |
|
||||
| `ContextAdapter` | 应用上下文（Context）操作 |
|
||||
| `DisplayAdapter` | 显示管理（分辨率、DPI、字体缩放） |
|
||||
| `DragDropAdapter` | 拖拽与拖放事件处理 |
|
||||
| `ElectronAppAdapter` | 应用信息（包名、语言、版本） |
|
||||
| `IMFAdapter` | 输入法框架集成 |
|
||||
| `MediaAdapter` | 媒体播放控制 |
|
||||
| `NativeThemeAdapter` | 系统主题监听（深色/浅色模式） |
|
||||
| `NotificationAdapter` | 系统通知管理 |
|
||||
| `PermissionManagerAdapter` | 动态权限申请与管理 |
|
||||
| `PrintAdapter` | 打印功能 |
|
||||
| `ScreenshotAdapter` | 截图功能 |
|
||||
| `StatusBarManager` | 状态栏控制 |
|
||||
| `SubWindowAdapter` | 子窗口管理 |
|
||||
| `WebAppAdapter` | Web 应用管理（PWA 等） |
|
||||
| ... | 还有更多适配器覆盖蓝牙、文件、相机、定位、麦克风等系统能力 |
|
||||
|
||||
#### UI 组件层 (`components/`)
|
||||
|
||||
| 组件 | 功能 |
|
||||
|------|------|
|
||||
| `WebWindow` | 主窗口组件。内部使用 `XComponent` 加载 `libadapter.so`，初始化 Native 浏览器引擎 |
|
||||
| `WebSubWindow` | 子窗口组件 |
|
||||
| `WebEmbeddedWindow` | 嵌入式窗口 |
|
||||
| `WebWindowNode` | 基于 NodeHandle 的窗口节点 |
|
||||
| `MessageBox` | 系统风格消息对话框 |
|
||||
|
||||
#### Native 桥接 (`cpp/types/libadapter/`)
|
||||
|
||||
| 文件 | 说明 |
|
||||
|------|------|
|
||||
| `index.d.ts` | `libadapter.so` 的 TypeScript 类型声明。暴露 `getNativeContext`、`SetContextPaths` 等 NAPI 接口 |
|
||||
| `oh-package.json5` | Native 库本地依赖配置 |
|
||||
|
||||
---
|
||||
|
||||
## 五、Native 层说明
|
||||
|
||||
### 5.1 `libelectron.so`
|
||||
|
||||
Electron 核心引擎的动态库，包含：
|
||||
- **Chromium 内核**: Blink 渲染引擎、V8 JavaScript 引擎
|
||||
- **Electron 运行时**: Node.js 集成、IPC 通信、窗口管理
|
||||
- **网络栈**: HTTP/HTTPS、WebSocket、网络缓存
|
||||
|
||||
### 5.2 `libadapter.so`
|
||||
|
||||
鸿蒙平台 Native 适配层，基于 **NAPI（Native API）** 实现。职责：
|
||||
- 将鸿蒙系统事件（窗口、输入、生命周期）转发给 Electron 引擎
|
||||
- 将 Electron 引擎的系统调用转发到鸿蒙 API
|
||||
- 管理 `XComponent` 的 `Surface` 渲染表面
|
||||
|
||||
### 5.3 `lib.unstripped/` 目录
|
||||
|
||||
位于 `ohos/v34/libelectron/lib.unstripped/`，包含未裁剪符号表的调试版本 `.so` 文件：
|
||||
|
||||
| 文件 | 说明 |
|
||||
|------|------|
|
||||
| `libelectron.so` | 带完整调试符号的 Electron 引擎库 |
|
||||
| `libadapter.so` | 带完整调试符号的适配层库 |
|
||||
|
||||
**用途**: 仅在开发调试阶段使用。崩溃时可通过符号表定位到具体的函数名、文件名和代码行号。生产环境使用裁剪后的库以减小包体积。
|
||||
|
||||
---
|
||||
|
||||
## 六、关键技术特性
|
||||
|
||||
### 6.1 多进程架构
|
||||
|
||||
- **主进程**: `EntryAbility` / `WebAbility` 运行在应用主进程
|
||||
- **浏览器进程**: `BrowserAbility` / `StatelessAbility` 运行在 `:browser` 独立进程
|
||||
- **渲染进程**: 通过 `WebChildProcess` / `CustomChildProcess` 启动多个渲染子进程
|
||||
|
||||
### 6.2 多窗口管理
|
||||
|
||||
- 支持 `specified` 启动模式，通过 `onAcceptWant` 实现窗口实例复用
|
||||
- 使用 `xcomponentId` 唯一标识每个窗口
|
||||
- 支持主窗口、子窗口、嵌入式窗口、NodeHandle 窗口四种形态
|
||||
|
||||
### 6.3 系统能力桥接
|
||||
|
||||
- 通过 40+ 个 Adapter 完整覆盖鸿蒙系统能力
|
||||
- 使用 **Inversify** 实现依赖注入，便于测试和扩展
|
||||
- 通过 `NativeContext` 接口与 C++ 层双向通信
|
||||
|
||||
### 6.4 主题与样式
|
||||
|
||||
- 支持跟随系统深色/浅色模式（`NativeThemeAdapter`）
|
||||
- 支持系统字体大小缩放（`DisplayAdapter`）
|
||||
- 窗口支持自定义标题栏、背景色、透明度
|
||||
|
||||
---
|
||||
|
||||
## 七、构建与依赖关系
|
||||
|
||||
```
|
||||
electron (entry HAP)
|
||||
└─依赖─> web_engine (HAR)
|
||||
└─依赖─> libadapter.so (Native)
|
||||
└─运行时链接─> libelectron.so (Native)
|
||||
└─依赖─> inversify (JS 依赖注入)
|
||||
└─依赖─> reflect-metadata (JS 元数据反射)
|
||||
```
|
||||
|
||||
**构建流程**:
|
||||
1. `hvigor` 编译 `web_engine` HAR 模块
|
||||
2. `hvigor` 编译 `electron` Entry 模块，打包 `web_engine` 依赖
|
||||
3. Native 库 `libadapter.so` / `libelectron.so` 通过 `build-profile.json5` 的 `collectAllLibs: true` 自动收集到 HAP 包中
|
||||
|
||||
---
|
||||
|
||||
## 八、文档与参考资料
|
||||
|
||||
项目 `docs/` 目录提供了以下文档：
|
||||
|
||||
| 文档 | 内容 |
|
||||
|------|------|
|
||||
| `Electron框架命令行参数支持说明.zip` | Electron 启动参数文档 |
|
||||
| `callArkTSFunction接口文档与示例.zip` | Native 调用 ArkTS 接口说明 |
|
||||
| `electron调用ets指导文档0411.pdf` | Electron 调用 ETS 开发指南 |
|
||||
| `鸿蒙平台Electron加载addon（基于node-sqlite3-5.1.7）.pdf` | Native Addon 加载示例 |
|
||||
|
||||
---
|
||||
|
||||
> **说明**: 本项目为华为内部鸿蒙 Electron 移植项目，基于 BSD 许可证开源。代码中大量使用了鸿蒙系统 API（`@kit.*` 命名空间）和 ArkTS 语法特性。
|
||||
BIN
ohos_hap/docs/鸿蒙平台Electron加载addon（基于node-sqlite3-5.1.7）.pdf
Normal file
BIN
ohos_hap/docs/鸿蒙平台Electron加载addon（基于node-sqlite3-5.1.7）.pdf
Normal file
Binary file not shown.
Reference in New Issue
Block a user