diff --git a/.gitignore b/.gitignore index d0f442a..7b8b350 100644 --- a/.gitignore +++ b/.gitignore @@ -22,7 +22,7 @@ python/dist/ *DS_Store # 忽略鸿蒙相关文件 -ohos_hap/docs/ +#ohos_hap/docs/ ohos_hap/.idea ohos_hap/.appanalyzer ohos_hap/.hvigor diff --git a/ohos_hap/docs/Electron框架命令行参数支持说明.zip b/ohos_hap/docs/Electron框架命令行参数支持说明.zip new file mode 100644 index 0000000..ce73d28 Binary files /dev/null and b/ohos_hap/docs/Electron框架命令行参数支持说明.zip differ diff --git a/ohos_hap/docs/callArkTSFunction接口文档与示例.zip b/ohos_hap/docs/callArkTSFunction接口文档与示例.zip new file mode 100644 index 0000000..926a99c Binary files /dev/null and b/ohos_hap/docs/callArkTSFunction接口文档与示例.zip differ diff --git a/ohos_hap/docs/electron-example.zip b/ohos_hap/docs/electron-example.zip new file mode 100644 index 0000000..43335fd Binary files /dev/null and b/ohos_hap/docs/electron-example.zip differ diff --git a/ohos_hap/docs/electron-napi-library.zip b/ohos_hap/docs/electron-napi-library.zip new file mode 100644 index 0000000..089531d Binary files /dev/null and b/ohos_hap/docs/electron-napi-library.zip differ diff --git a/ohos_hap/docs/electron调用ets指导文档0411.pdf b/ohos_hap/docs/electron调用ets指导文档0411.pdf new file mode 100644 index 0000000..23ee851 Binary files /dev/null and b/ohos_hap/docs/electron调用ets指导文档0411.pdf differ diff --git a/ohos_hap/docs/ets-adapter.zip b/ohos_hap/docs/ets-adapter.zip new file mode 100644 index 0000000..38f2d5f Binary files /dev/null and b/ohos_hap/docs/ets-adapter.zip differ diff --git a/ohos_hap/docs/目录结构.md b/ohos_hap/docs/目录结构.md new file mode 100644 index 0000000..7ead510 --- /dev/null +++ b/ohos_hap/docs/目录结构.md @@ -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 构建脚本 +│ +└── ... + +--- + + + + diff --git a/ohos_hap/docs/项目导读.md b/ohos_hap/docs/项目导读.md new file mode 100644 index 0000000..ca55ce9 --- /dev/null +++ b/ohos_hap/docs/项目导读.md @@ -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 语法特性。 diff --git a/ohos_hap/docs/鸿蒙平台Electron加载addon（基于node-sqlite3-5.1.7）.pdf b/ohos_hap/docs/鸿蒙平台Electron加载addon（基于node-sqlite3-5.1.7）.pdf new file mode 100644 index 0000000..c651770 Binary files /dev/null and b/ohos_hap/docs/鸿蒙平台Electron加载addon（基于node-sqlite3-5.1.7）.pdf differ