# HarmonyDemo

**Repository Path**: TTGF/harmony-demo

## Basic Information

- **Project Name**: HarmonyDemo
- **Description**: 鸿蒙学习简单demo
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-03
- **Last Updated**: 2026-10-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# HarmonyArkTSTutorial

把 28 天鸿蒙学习笔记整理成一个可运行的 ArkTS / ArkUI 教程 App。

通过主题目录、交互案例、源码讲解和动手实验，学习状态管理、组件通信、网络四态及工程边界。适合鸿蒙初学者，也适合从 iOS / Flutter 转向 HarmonyOS 的开发者。

> 项目用于学习和实验，部分能力采用 Mock 或内存实现，具体范围见下文。

## 项目特点

这是一个面向“有移动端经验但刚开始做 HarmonyOS”的 ArkTS + ArkUI 教程项目。基础内容包括数组、字符串、组件、布局仍然从可运行 demo 讲起；但案例配有进阶讲解，重点解释 ArkUI 的状态刷新边界、组件数据所有权、路由栈、网络四态和 iOS/Flutter 迁移时最容易误判的地方。

每个详情页固定包含：

1. 基础用法：先把 API 和最小写法跑起来。
2. 机制拆解：解释为什么这样写，以及刷新/传值/布局背后的边界。
3. iOS / Flutter 对照：把 HarmonyOS 概念放到你熟悉的 UINavigationController、SwiftUI、Flutter Widget、Navigator、Repository/ViewModel 里比较。
4. 常见坑：列出实际项目里最容易踩的状态污染、key 不稳定、竞态请求、隐藏依赖等问题。
5. 动手实验：给你一个可以直接改代码验证机制的小任务。

## 快速开始

### 环境要求

以下版本来自当前工程配置：

| 配置项 | 当前值 |
| --- | --- |
| 开发语言与 UI | ArkTS / ArkUI |
| 应用模型 | Stage |
| 工程模型版本 | `6.0.2` |
| 目标 SDK | `6.0.2(22)` |
| 兼容 SDK | `6.0.2(22)` |
| 运行模块 | `entry` |

使用支持上述工程与 SDK 的 DevEco Studio，并准备匹配 SDK 要求的模拟器或真机。后续版本调整以 `build-profile.json5` 和 `hvigor/hvigor-config.json5` 为准。

### 运行步骤

1. 克隆或下载本仓库，使用 DevEco Studio 打开工程根目录。
2. 安装对应 SDK，等待依赖安装和工程同步完成。
3. 检查本机 SDK 路径；使用真机时，通过 IDE 配置自己的调试签名。
4. 选择 `entry` 模块和目标设备，运行项目。
5. 从首页选择案例，阅读讲解、操作演示，再修改源码验证结果。

`local.properties` 中的路径与调试签名属于本机配置，不应直接沿用其他开发者的路径或证书。构建缓存会在工程同步、编译或预览时重新生成，无需从 Git 获取。

## 推荐学习顺序

1. ArkTS 基础区：变量类型、空安全、数组、字符串、控制流、集合管道、对象、函数、class、enum、泛型、联合类型、Result、异步和 ArkUI 装饰器。重点看 ArkTS 和 Swift/Dart 在集合、类型、异步、响应式约束上的差异。
2. UI 组件区：Text、Button、Image、TextInput、Checkbox、Radio、Toggle、List、Grid、Tabs、Dialog、Swiper，并补充文本体系、按钮状态、输入态、头像、媒体卡片、卡片边框阴影、列表 item 样式库。重点看声明式 UI 如何从“控件实例思维”切到“状态映射 UI”。
3. 布局区：Row、Column、Stack、Flex、间距、对齐、自适应。重点看约束、尺寸和溢出。
4. 状态与传值区：状态所有权决策、`@State`、`@Prop`、callback、`@Link`、`@Provide/@Consume`、`@Watch`、局部刷新、`@Observed/@ObjectLink`、`@ObservedV2/@Trace`。这里是本项目主菜。
5. 页面路由区：Navigation、NavPathStack、NavDestination、页面栈、页面参数。对照 iOS NavigationController 和 Flutter Navigator。
6. 网络区：请求结构、loading/error/empty/content 四态、刷新、重试和竞态保护。
7. 生命周期与状态进阶区：UIAbility、WindowStage、页面组件生命周期、`@Observed/@ObjectLink`、全局状态和持久状态。重点看 HarmonyOS 应用入口和 ArkUI 页面状态不是同一层东西。
8. 性能与长列表区：LazyForEach、稳定 key、局部刷新边界、图片缓存。重点看什么状态变化会触发什么 UI 重新构建。
9. 持久化与离线区：Preferences、RDB、缓存和离线策略。重点看 UI -> Repository -> Storage 的分层，不让页面直接吞存储 API。
10. 权限与安全区：权限声明、运行时申请、拒绝降级、敏感数据、WebView 安全边界。重点看“用户触发功能时再解释和申请”。
11. 交互、动画与适配区：animateTo、手势、断点、深色模式、多语言资源。重点看同一业务在手机、平板、深色模式和不同语言下如何保持稳定布局。
12. 工程化、调试与系统能力区：网络封装、超时重试取消、工程分层、HAR/HSP、签名构建、HiLog、Profiler、测试、Web 组件桥接、通知后台、文件媒体、分布式和元服务卡片。
13. 综合实战区：计数器、表单、收藏列表、父子组件联动、网络列表。

## 重点案例


- 类型系统与空安全：`arkts-type-system`
- 控制流与类型收窄：`arkts-control-flow`
- 集合管道与不可变更新：`arkts-collection-pipeline`
- class / enum：`arkts-class-enum`
- 泛型 / 联合类型 / Result：`arkts-generics-union`
- ArkUI 装饰器响应式：`arkts-decorator-state`
- 文本样式体系：`ui-text-styles`
- 按钮样式与状态：`ui-button-styles`
- 输入框状态样式：`ui-input-states`
- 选择控件与开关：`ui-selection-controls`
- 图片头像与媒体卡片：`ui-image-avatar`
- 卡片边框与阴影：`ui-card-decoration`
- 列表 item 样式库：`ui-list-item-styles`
- 正向传值：`state-forward`
- 反向传值：`state-reverse`
- 双向绑定：`state-link`
- 跨层传值：`state-provide-consume`
- 局部刷新：`state-watch-refresh`
- 状态所有权决策表：`state-ownership-matrix`
- 对象 item 局部刷新：`state-observed-objectlink`
- 深层字段追踪：`state-observedv2-trace`
- 网络四态：`network-states`
- UIAbility 生命周期：`lifecycle-uiability`
- Context 与 WindowStage：`lifecycle-context-window`
- 页面与组件生命周期：`lifecycle-page-component`
- 全局状态与持久状态：`state-global-persisted`
- LazyForEach 长列表：`perf-lazyforeach`
- 重建边界与局部刷新：`perf-rebuild-boundary`
- Preferences 用户设置：`storage-preferences`
- Preferences 收藏与局部刷新：`storage-preferences-refresh`
- RDB 表结构与查询：`storage-rdb`
- 缓存与离线优先：`storage-cache-offline`
- 权限申请完整流程：`security-permission-flow`
- animateTo 显式动画：`motion-animate-to`
- 断点适配：`adaptive-breakpoints`
- HTTP 封装边界：`network-http-wrapper`
- HAR / HSP 模块化：`engineering-har-hsp`
- HiLog 日志分层：`debug-hilog`
- Web 组件桥接：`web-component-bridge`
- 元服务卡片：`atomic-widget`
- Tabs 与弹窗：`ui-tabs-dialog`
- Swiper 轮播：`ui-swiper`
- Flex 自适应：`layout-flex`
- 父子组件联动：`practice-parent-child`
- 网络列表实战：`practice-network-list`

## 给有 iOS / Flutter 经验的你怎么看

- 不要把 ArkUI 当 UIKit：这里没有“拿到 Button 实例然后改属性”的主线，核心是状态变化后重新描述 UI。
- 可以迁移 Flutter 的声明式经验：`@State` 类似局部状态源，组件拆分类似拆 Widget，但 ArkTS 用装饰器把状态关系写得更显式。
- 可以迁移 SwiftUI 的绑定经验：`@Link` 很像 `@Binding`，`@Provide/@Consume` 接近 Environment，但都不应该滥用。
- UI 样式要从设计系统角度拆：文本层级、按钮语义、输入状态、列表 item 形态都应该形成小型样式库，而不是每页现写一遍。
- ArkTS 要按应用语言学：类型、集合、class/enum、泛型、Result、async 和装饰器都和 UI 架构相关，不是孤立语法点。
- 路由不要只理解成页面跳转：`NavPathStack` 是页面栈数据，栈变了，`Navigation` 根据栈构建目的页。
- 网络页面先建状态机：loading、error、empty、content 比“请求成功后 set 数据”更重要。
- 生命周期要分层：UIAbility 管系统入口和窗口，页面组件管 UI 状态，Repository/SystemAdapter 管数据和系统能力。
- 性能先看刷新边界：把高频变化状态压到小组件，把长列表交给 LazyForEach 和稳定 key。
- 存储和权限不要写在 UI 事件里：页面发意图，业务层决定读写、授权、降级和错误处理。

## 项目结构

```text
entry/src/main/ets/pages/Index.ets
  首页目录、详情切换、案例路由

entry/src/main/ets/data/TutorialCatalog.ets
  教程分区和 item 元数据，routeId 决定进入哪个 demo 组件

entry/src/main/ets/components/demos
  每个教学区的可运行 demo

entry/src/main/ets/components/demos/AdvancedTopicsDemo.ets
  生命周期、性能、存储、权限、适配、工程化与系统能力的教学案例入口

entry/src/main/ets/network/NetworkRepository.ets
  mock 网络仓库，后续可替换为 @ohos.net.http

entry/src/main/ets/data/ArkTsSamples.ets
  纯 ArkTS 数组、字符串、对象、异步示例

entry/src/main/ets/data/StorageRefreshModels.ets
  Preferences 收藏案例的纯 ArkTS model、cache 接口和 store，演示缓存封装与局部刷新

entry/src/main/ets/data/StorageRdbModels.ets
  RDB 最近学习案例的表接口、内存表和 store，演示 upsert、倒序查询和结构化存储边界

entry/src/main/ets/data/DownloadQueueModels.ets
  下载队列案例的任务状态机、内存缓存和 store，演示离线缓存与失败重试边界
```

## 教学实现与能力边界

目录中的主题覆盖不等于所有系统能力都已完成生产级接入。阅读时应区分交互演示、代码讲解和真实系统调用。

| 案例或模型 | 当前实现 | 主要学习目标 |
| --- | --- | --- |
| `NetworkRepository.ets` | 延迟返回的 Mock 数据 | 加载、成功、空数据、失败和过期响应处理 |
| `StorageRdbModels.ets` | 表接口，默认使用 `CourseHistoryMemoryTable` | 记录更新、查询排序与存储边界 |
| `StorageRefreshModels.ets` | 默认使用 `CourseFavoriteMemoryCache` | 收藏状态、缓存接口与局部刷新 |
| `DownloadQueueModels.ets` | 任务模型与默认内存缓存 | 下载队列状态和重试逻辑建模 |

内存模型不代表数据已经写入系统 Preferences 或 RDB，也不保证应用重启后的恢复。模拟下载不等于完成真实文件下载。接入实际业务时，需要补充真实数据源、平台适配、错误处理与设备验证。

## 测试与验证

- `entry/src/test/`：目录、状态、存储、下载队列等模型的测试代码。
- `entry/src/ohosTest/ets/test/`：设备侧测试入口与示例。
- 项目使用 Hypium；可在 DevEco Studio 中根据测试类型选择对应运行方式。

建议先验证目录和纯逻辑模型，再检查页面交互；涉及权限、媒体、后台任务等系统能力时，单独进行目标设备验证。测试文件的存在不代表所有测试已经通过，也不代表所有设备能力都已验证。

## 提交到 Git 前的配置整理

- 保留源码、资源、工程配置和依赖锁文件。
- `.gitignore` 已配置忽略依赖目录、构建目录、预览缓存、`.hvigor` 和本机 IDE 配置等生成内容。
- 检查 `build-profile.json5` 的 `signingConfigs`，移除个人证书路径、签名凭据及其他机器专属信息，并相应整理产品的签名引用。使用者通过 IDE 配置自己的签名。
- 当前配置整理不能代替历史检查：如果敏感签名信息曾提交到 Git，还需检查提交历史，不能只删除工作区中的字段。

## 官方文档入口

- [ArkTS 语言概述](https://developer.huawei.com/consumer/en/doc/harmonyos-guides/arkts-overview)
- [ArkUI 声明式组件](https://developer.huawei.com/consumer/en/doc/harmonyos-references/arkui-declarative-comp)
- [ArkTS 状态管理概述](https://developer.huawei.com/consumer/en/doc/harmonyos-guides/arkts-state-management-overview)
- [Navigation 组件](https://developer.huawei.com/consumer/en/doc/harmonyos-references/ts-basic-components-navigation)
- [HTTP 请求接口](https://developer.huawei.com/consumer/en/doc/harmonyos-references/js-apis-http)
- [UIAbility 组件概述](https://developer.huawei.com/consumer/en/doc/harmonyos-guides/uiability-overview)
- [应用权限开发概述](https://developer.huawei.com/consumer/en/doc/harmonyos-guides/accesstoken-overview)
- [LazyForEach 渲染控制](https://developer.huawei.com/consumer/en/doc/harmonyos-references/ts-rendering-control-lazyforeach)
- [Preferences 键值存储](https://developer.huawei.com/consumer/en/doc/harmonyos-references/js-apis-data-preferences)
- [RDB 关系型数据库](https://developer.huawei.com/consumer/en/doc/harmonyos-references/js-apis-data-rdb)
- [显式动画 animateTo](https://developer.huawei.com/consumer/en/doc/harmonyos-references/ts-explicit-animation)

## 怎么继续扩展

新增一个案例通常做三件事：

1. 在 `data/catalog/` 对应分区中增加案例元数据，设置唯一 `id`、所属分区和 `routeId`；目录由 `TutorialCatalog.ets` 统一装配。
2. 在 `components/demos` 里增加或扩展对应 demo。
3. 在 `Index.ets` 的 `SelectedDemo()` 中把 `routeId` 路由到对应 demo。

在 `data/catalog/TutorialLessonDepth.ets` 的讲解生成逻辑中补充相应内容，并按需增加 `entry/src/test/` 下的目录或逻辑测试。

建议每个案例仍然只讲一个核心知识点，但讲解要分层：先跑基础，再讲机制，再给对照和实验。这样新手能跟上，有经验的开发者也不会觉得只是在看 API 列表。

## 学习建议

先读一个知识点，再运行一个案例，每次只改变一个条件。对照 iOS / Flutter 可以帮助理解，但装饰器约束、生命周期和系统 API 的行为应以当前实现及对应 SDK 文档为准。

本项目承载基础学习与实验；后续音频 App 实战将通过独立项目展开。