59 lines
2.8 KiB
Markdown
59 lines
2.8 KiB
Markdown
# Architecture（架构）
|
||
|
||
HarmonyOS NEXT 单 HAP 应用，API 22（HarmonyOS 6.0）。技术栈：ArkTS + ArkUI 声明式 UI + hvigor。
|
||
Single-HAP HarmonyOS NEXT app, API 22 (HarmonyOS 6.0). Stack: ArkTS + ArkUI declarative UI + hvigor.
|
||
|
||
## 模块结构 Module Structure
|
||
|
||
- **AppScope/** — 应用级信息：`app.json5` 里定义 `bundleName`（`com.mingyuan.harmony_client`）、应用图标/标签（`$media:layered_image` / `$string:app_name`）。
|
||
- **entry/** — 唯一主模块（HAP）。`module.json5` 声明 Ability、权限、入口。
|
||
|
||
## Ability 生命周期 Ability Lifecycle
|
||
|
||
**EntryAbility**（`entry/src/main/ets/entryability/EntryAbility.ets`）是应用入口，继承 `UIAbility`。关键回调：
|
||
|
||
| 回调 Callback | 用途 Purpose |
|
||
|--------------|-------------|
|
||
| `onCreate` | Ability 创建，初始化状态（**此时不要做 UI 操作**） |
|
||
| `onWindowStageCreate` | 窗口创建，在这里 `loadContent('pages/Index')` 加载首页 |
|
||
| `onForeground` / `onBackground` | 前后台切换 |
|
||
| `onDestroy` | 销毁，释放资源 |
|
||
|
||
**EntryBackupAbility** — 应用备份扩展 Ability（备份/恢复数据）。
|
||
|
||
## 页面与路由 Pages & Routing
|
||
|
||
- 页面组件用 `@Entry` 装饰，在 `entry/src/main/resources/base/profile/main_pages.json` 注册。
|
||
- 页面跳转：`router.pushUrl()`（栈式导航），或 `Navigation` 组件（推荐，用于复杂导航）。
|
||
|
||
## 目录分层 Layering Convention
|
||
|
||
```
|
||
entry/src/main/ets/
|
||
├── entryability/ # Ability 入口（生命周期）
|
||
├── entrybackupability/ # 备份扩展
|
||
├── pages/ # 页面（@Entry 组件，只做 UI 编排）
|
||
├── components/ # 可复用 UI 组件（@Component / @Reusable）
|
||
├── viewmodel/ # 状态管理（连接 model 与 UI）
|
||
├── service/ # 业务逻辑、数据访问（网络/存储）
|
||
├── model/ # 数据模型、类型定义
|
||
└── common/ # 公共常量、工具函数
|
||
```
|
||
|
||
依赖方向（只能从右往左引，禁止反向）：
|
||
Dependency direction (only right→left, never reverse):
|
||
`pages → viewmodel → service → model`；`components` 不依赖业务层。
|
||
|
||
## 状态管理 State Management
|
||
|
||
- 组件内：`@State`（本地）、`@Prop`（父传子单向）、`@Link`（父子双向）。
|
||
- 跨组件：`@Provide` / `@Consume`，或 `AppStorage`（全局）/ `LocalStorage`（页面级）。
|
||
- 持久化：`PersistentStorage`（简单键值）。
|
||
- 原则：**UI 由状态驱动**，不在组件外手动改 UI。
|
||
|
||
## 关键约定速查 Key Contracts
|
||
|
||
- 所有字符串/颜色/媒体走 `$r()` 资源引用。
|
||
- 页面只做 UI 编排；数据获取/业务判断在 `service/`，类型在 `model/`。
|
||
- 新增页面必须同步注册到 `main_pages.json`。
|