一、教程说明

• 标题：Flutter 三方库集成鸿蒙开发实战：TODO 清单跨端应用完整教程
• 适用人群：鸿蒙原生开发者、想入门 Flutter 跨端开发人员
• 核心关键词：Flutter、三方库、鸿蒙
• 项目：TODO 待办清单（增、删、改、查、状态切换、本地持久化）
• 兼容平台：HarmonyOS NEXT / Android / iOS 通用

---

二、核心技术栈

• Flutter 3.19+
• 鸿蒙（HarmonyOS）
• 核心三方库：
  • provider：状态管理
  • shared_preferences：鸿蒙本地数据持久化
  • flutter_slidable：侧滑删除
  • fluttertoast：轻提示

---

三、项目初始化

1. 创建 Flutter 项目

flutter create flutter_harmony_todo
cd flutter_harmony_todo

2. 配置 pubspec.yaml（关键：三方库依赖）

name: flutter_harmony_todo
description: Flutter 鸿蒙 TODO 清单实战
version: 1.0.0+1

environment:
  sdk: '>=3.10.0 <4.0.0'

dependencies:
  flutter:
    sdk: flutter

  # 👇 Flutter 三方库（全部兼容鸿蒙）
  provider: ^6.1.1          # 状态管理
  shared_preferences: ^2.5.2 # 本地存储（鸿蒙可用）
  flutter_slidable: ^3.1.2   # 侧滑删除
  fluttertoast: ^8.2.12      # 轻提示

dev_dependencies:
  flutter_test:
    sdk: flutter
  flutter_lints: ^3.0.0

flutter:
  uses-material-design: true

3. 安装依赖

flutter pub get

---

四、项目结构

lib/
├── main.dart                 # 程序入口
├── models/
│   └── todo_item.dart        # TODO 数据模型
├── provider/
│   └── todo_provider.dart    # 状态管理 + 本地存储
└── pages/
    └── todo_page.dart        # 主页面 UI

---

五、代码实现（全注释）

1. 模型：todo_item.dart

定义单个待办事项结构

class TodoItem {
  final String id;      // 唯一标识
  final String title;   // 待办标题
  bool isDone;          // 是否完成

  TodoItem({
    required this.id,
    required this.title,
    this.isDone = false,
  });
}

---

2. 状态管理 + 本地存储：todo_provider.dart

使用 shared_preferences 实现鸿蒙本地持久化

import 'package:flutter/material.dart';
import 'package:shared_preferences/shared_preferences.dart';
import 'dart:convert';
import '../models/todo_item.dart';

class TodoProvider extends ChangeNotifier {
  List<TodoItem> _todoList = [];

  List<TodoItem> get todoList => _todoList;

  // 构造函数：启动时加载鸿蒙本地存储数据
  TodoProvider() {
    loadTodoList();
  }

  // 加载本地存储的 TODO 列表
  Future<void> loadTodoList() async {
    final prefs = await SharedPreferences.getInstance();
    // 从鸿蒙本地获取字符串数据
    final String? todoString = prefs.getString('todo_list');
    if (todoString != null) {
      // 转成 List<Map>
      final List<dynamic> decoded = jsonDecode(todoString);
      _todoList = decoded.map((item) {
        return TodoItem(
          id: item['id'],
          title: item['title'],
          isDone: item['isDone'],
        );
      }).toList();
      notifyListeners();
    }
  }

  // 保存到鸿蒙本地存储
  Future<void> _saveToLocal() async {
    final prefs = await SharedPreferences.getInstance();
    // 转为可存储的字符串
    final List<Map<String, dynamic>> encoded = _todoList.map((todo) {
      return {
        'id': todo.id,
        'title': todo.title,
        'isDone': todo.isDone,
      };
    }).toList();
    await prefs.setString('todo_list', jsonEncode(encoded));
  }

  // 添加 TODO
  void addTodo(String title) {
    if (title.isEmpty) return;
    final newTodo = TodoItem(
      id: DateTime.now().millisecondsSinceEpoch.toString(),
      title: title,
    );
    _todoList.add(newTodo);
    _saveToLocal();
    notifyListeners();
  }

  // 切换完成状态
  void toggleStatus(String id) {
    final index = _todoList.indexWhere((item) => item.id == id);
    if (index != -1) {
      _todoList[index].isDone = !_todoList[index].isDone;
      _saveToLocal();
      notifyListeners();
    }
  }

  // 删除 TODO
  void deleteTodo(String id) {
    _todoList.removeWhere((item) => item.id == id);
    _saveToLocal();
    notifyListeners();
  }
}

---

3. 主页面 UI：todo_page.dart

使用 flutter_slidable 实现侧滑删除

import 'package:flutter/material.dart';
import 'package:flutter_slidable/flutter_slidable.dart';
import 'package:fluttertoast/fluttertoast.dart';
import 'package:provider/provider.dart';
import '../provider/todo_provider.dart';
import '../models/todo_item.dart';

class TodoPage extends StatefulWidget {
  const TodoPage({super.key});

  @override
  State<TodoPage> createState() => _TodoPageState();
}

class _TodoPageState extends State<TodoPage> {
  final TextEditingController _controller = TextEditingController();

  @override
  Widget build(BuildContext context) {
    final todoProvider = Provider.of<TodoProvider>(context);

    return Scaffold(
      appBar: AppBar(
        title: const Text('Flutter 鸿蒙 TODO 清单'),
        centerTitle: true,
        backgroundColor: const Color(0xFF007DFF),
      ),
      body: Padding(
        padding: const EdgeInsets.all(16.0),
        child: Column(
          children: [
            // 输入框 + 添加按钮
            Row(
              children: [
                Expanded(
                  child: TextField(
                    controller: _controller,
                    decoration: const InputDecoration(
                      hintText: '请输入待办事项',
                      border: OutlineInputBorder(),
                    ),
                  ),
                ),
                const SizedBox(width: 10),
                ElevatedButton(
                  onPressed: () {
                    final text = _controller.text.trim();
                    if (text.isEmpty) {
                      Fluttertoast.showToast(msg: '请输入内容');
                      return;
                    }
                    todoProvider.addTodo(text);
                    _controller.clear();
                    Fluttertoast.showToast(msg: '添加成功');
                  },
                  child: const Text('添加'),
                ),
              ],
            ),
            const SizedBox(height: 20),
            // 待办列表
            Expanded(
              child: todoProvider.todoList.isEmpty
                  ? const Center(child: Text('暂无待办事项，快去添加吧~'))
                  : ListView.builder(
                      itemCount: todoProvider.todoList.length,
                      itemBuilder: (ctx, index) {
                        final todo = todoProvider.todoList[index];
                        return Slidable(
                          // 侧滑删除（flutter_slidable 三方库）
                          endActionPane: ActionPane(
                            motion: const ScrollMotion(),
                            children: [
                              SlidableAction(
                                onPressed: (_) {
                                  todoProvider.deleteTodo(todo.id);
                                  Fluttertoast.showToast(msg: '已删除');
                                },
                                backgroundColor: Colors.red,
                                icon: Icons.delete,
                                label: '删除',
                              ),
                            ],
                          ),
                          // 列表项
                          child: ListTile(
                            leading: Checkbox(
                              value: todo.isDone,
                              onChanged: (_) {
                                todoProvider.toggleStatus(todo.id);
                              },
                            ),
                            title: Text(
                              todo.title,
                              style: TextStyle(
                                fontSize: 16,
                                decoration: todo.isDone
                                    ? TextDecoration.lineThrough
                                    : null,
                                color: todo.isDone ? Colors.grey : null,
                              ),
                            ),
                          ),
                        );
                      },
                    ),
            ),
          ],
        ),
      ),
    );
  }
}

---

4. 入口文件：main.dart

import 'package:flutter/material.dart';
import 'package:provider/provider.dart';
import 'pages/todo_page.dart';
import 'provider/todo_provider.dart';

void main() {
  runApp(
    // 全局状态管理
    ChangeNotifierProvider(
      create: (context) => TodoProvider(),
      child: const MyApp(),
    ),
  );
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Flutter 鸿蒙 TODO',
      theme: ThemeData(
        primarySwatch: Colors.blue,
        useMaterial3: true,
      ),
      debugShowCheckedModeBanner: false,
      home: const TodoPage(),
    );
  }
}