鸿蒙原生 Todo 应用开发实战：从零到模拟器运行

踩坑记录 | DevEco Studio 6.1.1 + HarmonyOS API 24 + ArkTS 状态管理 V2

---

前言

本文记录了一次完整的鸿蒙原生应用开发过程——从零开始创建一个带本地持久化的 Todo 待办事项应用，并在模拟器上成功运行。过程中遇到了各种配置、版本、编译问题，逐一解决，希望能帮到同样在路上的开发者。

---

一、项目选型

项目	内容
应用类型	Todo 待办事项
IDE	DevEco Studio 6.1.1.280
目标 API	HarmonyOS API 24 (6.1.1)
开发语言	ArkTS
UI 框架	ArkUI 声明式 UI
状态管理	V2 (@ObservedV2 / @Trace / @ComponentV2)
数据持久化	Preferences (@kit.ArkData)

---

二、功能清单

• ✅ 新增待办 — TextInput + Button，支持回车提交
• ✅ 勾选完成/取消 — 圆形按钮切换 @Trace completed 状态，完成文字加删除线
• ✅ 左滑删除 — ListItem.swipeAction() 露出红色删除按钮
• ✅ 筛选切换 — 全部 / 进行中 / 已完成，三种 Chip 按钮高亮状态
• ✅ 底部统计 — 显示"X 项待办" + 清除已完成按钮
• ✅ 数据持久化 — Preferences 自动存储，重启不丢失
• ✅ 空状态提示 — 不同筛选下显示不同的空态文案
• ✅ 新增动画 — 列表项插入时渐入 + 平移过渡

---

三、架构设计

采用 MVVM + Repository 模式，遵循数据单向流动原则：

Service → Repository → ViewModel → View

目录结构

entry/src/main/ets/
├── models/
│   └── TodoItem.ets          # 数据模型 (@ObservedV2 + @Trace)
├── viewmodel/
│   └── TodoViewModel.ets     # 业务逻辑 + 状态管理 + Preferences 持久化
├── pages/
│   └── Index.ets             # 主界面 UI
└── entryability/
    └── EntryAbility.ets      # Ability 生命周期入口

核心模型

@ObservedV2
export class TodoItem {
  @Trace id: string = '';
  @Trace title: string = '';
  @Trace completed: boolean = false;
  @Trace createdAt: number = 0;
}

ViewModel 设计

@ObservedV2
export class TodoViewModel {
  @Trace todos: TodoItem[] = [];        // 全部待办
  @Trace filter: FilterType;            // 筛选状态
  @Trace newTodoTitle: string = '';     // 输入框绑定

  // 计算属性
  get filteredTodos(): TodoItem[] { /* 按筛选条件过滤 */ }
  get activeCount(): number { /* 未完成数 */ }
  get completedCount(): number { /* 已完成数 */ }

  // 操作方法
  async addTodo(): Promise<void>        // 新增
  async toggleTodo(id: string)          // 切换状态
  async deleteTodo(id: string)          // 删除
  async clearCompleted(): Promise<void> // 清除已完成
}

---

四、踩坑实录

💥 坑1：「Select an OpenHarmony or HarmonyOS project」

现象：DevEco Studio 打开项目时报无法识别。

原因：缺少 hvigorfile.ts 文件，这是 DevEco Studio 识别项目入口的关键标记。

解决：在项目根目录和 entry/ 模块下各创建一个 hvigorfile.ts：

// 根目录 hvigorfile.ts
import { appTasks, OhosPlugin } from '@ohos/hvigor-ohos-plugin';
export default { system: appTasks, plugins: [] } as OhosPlugin;

// entry/hvigorfile.ts
import { hapTasks, OhosPlugin } from '@ohos/hvigor-ohos-plugin';
export default { system: hapTasks, plugins: [] } as OhosPlugin;

💥 坑2：Schema 校验失败 — build-profile.json5 结构不对

现象：

Schema validate failed - instancePath: 'app', keyword: 'enum'
'compileSdkVersion' property name must be valid

原因：新版 hvigor 的 schema 中，compileSdkVersion 和 compatibleSdkVersion 必须放在 products 数组内部，不能放在 app 级别。

修复后的正确结构：

{
  "app": {
    "signingConfigs": [],
    "products": [
      {
        "name": "default",
        "signingConfig": "default",
        "compileSdkVersion": 24,
        "compatibleSdkVersion": 24
      }
    ],
    "buildModeSet": [
      { "name": "debug" },
      { "name": "release" }
    ]
  },
  "modules": [
    { "name": "entry", "srcPath": "./entry" }
  ]
}

💥 坑3：ArkTS 严格模式编译错误

编译时报了 6 个错误，涉及 ArkTS 严格模式的限制：

错误	原因	修复
arkts-no-untyped-obj-literals	对象字面量需要显式类型	定义 interface TodoData 并标注类型
arkts-no-obj-literals-as-types	内联对象不能用作类型声明	改用已定义的类型 TodoData[]
arkts-no-implicit-return-types	函数需要显式返回类型	给 emptyMessage() 加 : string
'Context' 不能赋值给 'UIAbilityContext'	getContext() 返回类型变更	getContext(this) as common.UIAbilityContext
swipeAction 参数格式错误	API 更新	end: (): void => { this.deleteButton(item) }

💥 坑4：compileSdkVersion 版本匹配问题

现象：

Unsupported compileSdkVersion 20 - Please modify to 6.0.1(21)

后来又变成要求 22、23……

原因：DevEco Studio 6.1.1 自带的 hvigor 版本是 6.21.2-rc.37，它绑定的 SDK 版本比用户安装的 SDK 版本新。

教训：用 DevEco Studio 的 File → New → Create Project 创建空白项目，让 IDE 自动配置好 SDK 版本，再把自己的代码迁进去，这是最稳妥的方式。

💥 坑5：SDK 结构与 hvigor 不匹配

现象：

Unable to find the following components: toolchains:24, ArkTS:24, js:24, native:24, previewer:24

原因：SDK 是扁平结构（openharmony/ets/），但新版 hvigor 需要版本化结构（openharmony/24/ets/）。

解决：重新用 DevEco Studio 新建项目，自动安装匹配的 SDK。

---

五、最终项目结构

D:\harmonyos\deepseekv4\project2/
├── .gitignore
├── AppScope/app.json5            # 应用配置
├── build-profile.json5           # 全局构建配置
├── hvigor/hvigor-config.json5    # 构建引擎配置
├── hvigorfile.ts                 # 根构建入口
├── hvigorw / hvigorw.bat         # 构建脚本
├── oh-package.json5              # 依赖清单
└── entry/
    ├── build-profile.json5       # 模块构建配置
    ├── hvigorfile.ts             # 模块构建入口
    ├── oh-package.json5
    └── src/main/
        ├── module.json5
        ├── ets/
        │   ├── entryability/EntryAbility.ets
        │   ├── models/TodoItem.ets
        │   ├── viewmodel/TodoViewModel.ets
        │   └── pages/Index.ets
        └── resources/
            ├── base/element/{string,color}.json
            └── base/profile/main_pages.json

---

六、给新手的建议

1. 直接用 DevEco Studio 新建项目，不要手写配置文件——IDE 会自动匹配正确的 SDK 版本和构建配置
2. 注意 DevEco Studio 版本和 SDK 版本的匹配，新版 IDE 可能只支持新版 SDK
3. ArkTS 严格模式很严格，对象字面量必须有类型标注，JSON.parse 需要用 as 断言
4. 状态管理推荐用 V2（@ObservedV2/@Trace/@ComponentV2/@Local），是官方推荐的新版方案
5. 数据持久化用 Preferences 很简单，适合轻量数据存储

---

七、运行效果

启动后在模拟器中可以看到：

• 顶部标题栏 “📋 待办事项”
• 输入框 + “添加” 按钮
• 三个筛选 Chip（全部 / 进行中 / 已完成）
• 待办列表，带圆形勾选框和删除线效果
• 底部统计 “X 项待办” + 清除已完成

---