1. 背景与目标

随着 HarmonyOS 4 的发布，ArkTS 已成为官方推荐的主力开发语言。其融合 TypeScript 静态类型优势与声明式 UI 框架 ArkUI，极大简化了跨设备应用开发流程。本文将引导开发者完成一个功能完整的 本地任务管理应用（Todo List），涵盖：

• ArkTS 基础语法
• 状态管理机制（@State / @Link / @Prop）
• 组件封装与复用
• 本地数据持久化（Preferences）

2. 开发环境准备

• DevEco Studio 4.0+
• SDK API Version ≥ 10
• 模拟器或真机（HarmonyOS 3.1+）

3. 项目结构设计

text编辑entry/
├── src/main/ets/
│   ├── entryability/EntryAbility.ts
│   ├── pages/
│   │   ├── Main.ets          // 主页面
│   │   └── TaskItem.ets      // 任务项组件
│   └── model/
│       └── TaskModel.ts      // 数据模型与持久化

4. 核心实现详解

4.1 数据模型与持久化（TaskModel.ts）

typescript编辑import preferences from '@ohos.data.preferences';

const PREF_NAME = 'todo_prefs';
let pref: preferences.Preferences | null = null;

export class Task {
  title: string;
  completed: boolean;
  id: string;

  constructor(title: string) {
    this.title = title;
    this.completed = false;
    this.id = Date.now().toString();
  }
}

// 初始化偏好设置
async function initPref() {
  if (!pref) {
    pref = await preferences.getPreferences(PREF_NAME);
  }
}

// 保存任务列表
export async function saveTasks(tasks: Task[]): Promise<void> {
  await initPref();
  const jsonStr = JSON.stringify(tasks);
  pref?.putSync('tasks', jsonStr);
  await pref?.flush();
}

// 加载任务列表
export async function loadTasks(): Promise<Task[]> {
  await initPref();
  const jsonStr = pref?.getSync('tasks', '[]');
  try {
    return JSON.parse(jsonStr || '[]').map((item: any) => {
      const task = new Task(item.title);
      task.completed = item.completed;
      task.id = item.id;
      return task;
    });
  } catch (e) {
    console.error('Failed to parse tasks:', e);
    return [];
  }
}

4.2 自定义任务项组件（TaskItem.ets）

typescript编辑@Component
struct TaskItem {
  @Link task: Task;
  private onDelete: () => void;

  build() {
    Row() {
      Checkbox()
        .select(this.task.completed)
        .onChange((isChecked) => {
          this.task.completed = isChecked;
        })
      Text(this.task.title)
        .fontSize(16)
        .decoration({ type: this.task.completed ? TextDecorationType.LineThrough : TextDecorationType.None })
        .layoutWeight(1)
        .margin({ left: 10 })
      Button('删除')
        .fontColor(Color.Red)
        .onClick(this.onDelete)
    }
    .width('100%')
    .padding(12)
    .borderRadius(8)
    .backgroundColor('#f5f5f5')
  }
}

4.3 主页面逻辑（Main.ets）

typescript编辑import { Task, loadTasks, saveTasks } from '../model/TaskModel';

@Entry
@Component
struct TodoApp {
  @State tasks: Task[] = [];
  @State newTaskTitle: string = '';

  aboutToAppear() {
    this.loadAllTasks();
  }

  async loadAllTasks() {
    this.tasks = await loadTasks();
  }

  async addTask() {
    if (this.newTaskTitle.trim() === '') return;
    this.tasks.push(new Task(this.newTaskTitle));
    this.newTaskTitle = '';
    await saveTasks(this.tasks);
  }

  async removeTask(index: number) {
    this.tasks.splice(index, 1);
    await saveTasks(this.tasks);
  }

  build() {
    Column() {
      Text('我的任务清单')
        .fontSize(24)
        .fontWeight(FontWeight.Bold)
        .margin({ top: 20, bottom: 20 })

      Row() {
        TextInput({ placeholder: '输入新任务...' })
          .onChange((value) => {
            this.newTaskTitle = value;
          })
          .width('70%')
        Button('添加')
          .onClick(() => this.addTask())
          .width('25%')
      }
      .width('90%')
      .margin({ bottom: 20 })

      List() {
        ForEach(this.tasks, (task: Task, index: number) => {
          ListItem() {
            TaskItem({
              task: this.tasks[index],
              onDelete: () => this.removeTask(index)
            })
          }
        }, (task: Task) => task.id)
      }
      .layoutWeight(1)
      .width('100%')
    }
    .width('100%')
    .height('100%')
    .padding(10)
  }
}

5. 常见问题与调试技巧

• 状态未更新？ 确保使用 @State 修饰数组，并通过 .push() / splice() 等可检测方式修改。
• 数据未持久化？ 检查 preferences.flush() 是否被调用。
• UI 卡顿？ 避免在 build() 中执行异步操作，应移至 aboutToAppear()。

6. 小结

本项目虽小，但完整覆盖了 HarmonyOS 应用开发的核心范式：声明式 UI + 状态驱动 + 本地存储。掌握此模式后，可快速迁移到更复杂场景（如网络请求、多页面导航等）。