Flutter+鸿蒙6.0+三方库实战：跨端简易待办清单APP（API20+）

开源鸿蒙跨平台社区项目摘要本项目为鸿蒙开发者提供Flutter跨平台开发入门教程，基于HarmonyOS 6.0+（API 20+）和定制版Flutter 3.10.0 SDK，开发简易待办清单APP。

catcatcat-17

48人浏览 · 2026-04-15 13:17:11

catcatcat-17 · 2026-04-15 13:17:11 发布

欢迎加入开源鸿蒙跨平台社区： https://openharmonycrossplatform.csdn.net

适配：HarmonyOS 6.0+ / API Level 20+（兼容API20及以上）
技术栈：Flutter 3.10.0 + 鸿蒙定制版Flutter SDK + 3个核心三方库
适用人群：鸿蒙新手开发者（Flutter跨端入门，零基础可上手）
核心特色：无需复杂配置、代码全注释、可直接复制运行、适配鸿蒙设备

一、项目介绍

本项目专为鸿蒙新手开发者设计，基于鸿蒙6.0+系统、API20及以上SDK，使用Flutter跨端框架，整合3个高频实用三方库，从零搭建一个可在鸿蒙设备直接运行的简易待办清单APP。

项目功能简洁实用，涵盖待办事项的添加、删除、标记完成/未完成，全程步骤拆解细致，每段代码均附带详细注释，无需申请任何密钥、无需复杂环境配置，新手可一步一步对照操作，快速掌握Flutter与鸿蒙跨端开发的核心逻辑，以及三方库在鸿蒙生态中的集成与使用方法。

核心三方库说明（均适配鸿蒙6.0+，新手易上手）

provider：轻量级状态管理库，简化待办数据的管理与页面刷新，替代繁琐的setState，上手成本极低；
shared_preferences：轻量级本地存储库，适配鸿蒙生态，用于持久化保存待办数据（关闭APP后数据不丢失）；
fluttertoast：轻量级弹窗提示库，用于用户操作反馈（如“待办添加成功”“请输入待办内容”），提升APP交互体验。

最低适配要求（严格满足需求）

鸿蒙系统版本：6.0及以上（如鸿蒙6.0、6.1、6.2）；
鸿蒙SDK API Level：20及以上（实际配置API23，兼容API20+，避免低版本兼容问题）；
Flutter版本：3.10.0及以上（必须使用鸿蒙定制版Flutter SDK，不可用官方原生SDK）；
开发工具：DevEco Studio（支持鸿蒙6.0+开发，自带鸿蒙SDK配置功能）。

二、环境准备（新手必做，一步不落，附排查方法）

2.1 基础环境安装与配置

安装DevEco Studio：前往鸿蒙官方网站下载，选择支持鸿蒙6.0+的版本（建议最新版），安装过程中默认勾选“鸿蒙SDK”，安装完成后打开IDE，根据提示补充下载鸿蒙6.0+ SDK（API23及以上）。
安装鸿蒙定制版Flutter SDK：

克隆官方适配仓库：终端执行命令 git clone https://gitcode.com/openharmony/flutter_ohos（国内仓库，下载速度快）；
解压克隆后的文件夹，找到Flutter SDK所在路径（如：D:\flutter_ohos\flutter）；
配置系统环境变量：右键「此电脑」→「属性」→「高级系统设置」→「环境变量」，在「系统变量」中找到「Path」，添加解压后的Flutter SDK的bin目录（如：D:\flutter_ohos\flutter\bin）；

验证环境：关闭所有终端，重新打开，输入命令 flutter --version，若输出包含“HarmonyOS”相关标识（如“Flutter 3.10.0 for HarmonyOS”），说明配置成功；若提示“flutter不是内部或外部命令”，重新检查环境变量配置。

2.2 创建Flutter鸿蒙跨端项目

打开终端，进入想要创建项目的文件夹（如：D:\HarmonyProjects），执行以下命令，创建指定ohos平台的Flutter项目（项目名自定义，此处以“flutter_harmony_todo”为例）：
# 初始化项目，指定平台为ohos（鸿蒙），项目名为flutter_harmony_todo
flutter create --platforms=ohos flutter_harmony_todo

进入项目目录

cd flutter_harmony_todo注释：–platforms=ohos 是核心参数，用于指定项目支持鸿蒙平台，若省略该参数，项目默认不支持鸿蒙设备运行。

导入项目：打开DevEco Studio，点击「File」→「Open」，选择创建好的“flutter_harmony_todo”项目，等待项目初始化完成（首次初始化可能需要3-5分钟，耐心等待，确保网络正常）。

三、pubspec.yaml 配置（核心依赖，直接复制替换）

pubspec.yaml是Flutter项目的核心配置文件，用于管理三方库依赖、项目信息和鸿蒙平台配置。打开项目根目录下的pubspec.yaml文件，删除原有内容，复制以下配置（带详细注释，新手无需修改），配置完成后执行依赖安装。

name: flutter_harmony_todo
description: Flutter+鸿蒙6.0+三方库实战：跨端简易待办清单APP（API20+）
version: 1.0.0+1

指定Dart SDK版本，适配Flutter 3.10.0+，兼容鸿蒙定制版Flutter

environment:
sdk: ‘>=3.0.0<4.0.0’

dependencies:
flutter:
sdk: flutter # Flutter核心依赖，不可删除

核心三方库（均适配鸿蒙6.0+，选择稳定版本，避免兼容性问题）

provider: ^6.1.1 # 状态管理库，管理待办数据
shared_preferences: ^2.2.2 # 本地存储库，持久化保存待办数据
fluttertoast: ^8.2.2 # 弹窗提示库，用户操作反馈

dev_dependencies:
flutter_test:
sdk: flutter # Flutter测试依赖，新手可默认
flutter_lints: ^2.0.0 # 代码规范检查，新手可默认

flutter:
uses-material-design: true # 启用Material Design组件，用于构建UI

鸿蒙平台专属配置（关键！必须配置，否则无法在鸿蒙设备/模拟器运行）

ohos:
package: com.example.flutterharmonytodo # 应用包名（自定义，格式为com.xxx.xxx，不可重复）
compileSdkVersion: 23 # 编译SDK版本，适配鸿蒙6.0+，兼容API20+
minSdkVersion: 20 # 最低SDK版本，严格满足API20+要求
targetSdkVersion: 23 # 目标SDK版本，与编译SDK版本一致
label: 简易待办清单 # 应用名称（显示在鸿蒙设备桌面）
icon: mipmap/ic_launcher # 应用图标（新手可默认，后续可自行替换）

3.1 安装三方库依赖

配置完成后，点击DevEco Studio顶部的「Pub get」按钮（或在终端执行以下命令），安装三方库依赖：

flutter pub get

安装成功提示：终端会显示「Process finished with exit code 0」；若安装失败，可尝试以下解决方法：

检查网络连接，确保能正常访问pub.dev仓库；
降低三方库版本（如将provider改为^6.0.0），修改后重新执行「Pub get」；
重启DevEco Studio，重新导入项目后再安装依赖。

四、项目目录结构（新手对照创建，避免出错）

为了方便新手理解和维护，采用简单的分层架构，不引入复杂概念，项目目录结构如下（创建后对照检查，确保无误）：

flutter_harmony_todo/
├─ lib/ # 项目核心代码目录（所有代码都在这里编写）
│ ├─ main.dart # 项目入口文件（程序启动的入口）
│ ├─ model/ # 数据模型层（规范待办数据格式）
│ │ └── todo_model.dart # 待办数据模型（存储待办标题、状态等字段）
│ ├─ provider/ # 状态管理层（管理待办数据和业务逻辑）
│ │ └── todo_provider.dart # 待办状态管理（添加、删除、标记完成等操作）
│ └─ pages/ # 页面层（展示UI和用户交互）
│ └── todo_page.dart # 主页面（待办清单展示、添加、操作）
├─ pubspec.yaml # 依赖配置文件（管理三方库和项目信息）
└─ ohos/ # 鸿蒙平台相关配置（自动生成，新手无需修改）

创建步骤：在lib目录下，依次新建model、provider、pages三个文件夹，再在每个文件夹下创建对应的dart文件（文件名严格对应，避免拼写错误）。

五、完整代码实现（全注释，可直接复制，新手零修改）

以下所有代码均附带详细注释，解释每一行代码的作用，新手可直接复制到对应文件中，无需修改，确保代码可正常运行，重点关注注释中的“新手注意”部分。

5.1 数据模型：lib/model/todo_model.dart

定义待办数据模型，规范待办事项的数据格式，统一管理待办的ID、标题、完成状态，避免数据混乱，方便后续存储和展示。

/// 待办数据模型
/// 用于规范待办事项的数据格式，统一管理待办的核心字段
class TodoModel {
// 待办ID（唯一标识，用于删除、修改待办时定位数据）
final String id;
// 待办标题（用户输入的待办内容）
final String title;
// 待办完成状态（true：已完成，false：未完成，默认未完成）
final bool isCompleted;

// 构造方法：初始化待办数据
// required表示必填参数（id、title），isCompleted有默认值false
TodoModel({
required this.id,
required this.title,
this.isCompleted = false,
});

// 复制方法：用于修改待办状态（不修改原数据，返回新的待办对象，避免数据混乱）
TodoModel copyWith({
String? id,
String? title,
bool? isCompleted,
}) {
return TodoModel(
id: id ?? this.id, // 若传入id则使用新id，否则使用原id
title: title ?? this.title, // 若传入title则使用新title，否则使用原title
isCompleted: isCompleted ?? this.isCompleted, // 同理，修改完成状态
);
}

// 序列化方法：将TodoModel对象转为Map（用于shared_preferences本地存储）
// shared_preferences只能存储基本数据类型，因此需要将对象转为Map
Map<String, dynamic> toMap() {
return {
‘id’: id,
‘title’: title,
‘isCompleted’: isCompleted,
};
}

// 反序列化方法：将Map转为TodoModel对象（用于从本地存储读取数据）
static TodoModel fromMap(Map<String, dynamic> map) {
return TodoModel(
id: map[‘id’],
title: map[‘title’],
isCompleted: map[‘isCompleted’] ?? false, // 若读取不到，默认未完成
);
}
}

5.2 状态管理：lib/provider/todo_provider.dart

使用provider管理待办数据，结合shared_preferences实现数据持久化，封装待办事项的添加、删除、标记完成/未完成等核心操作，统一管理业务逻辑，让页面只负责展示和交互。

// 导入依赖包
import ‘package:flutter/foundation.dart’; // 用于kDebugMode调试输出
import ‘package:shared_preferences/shared_preferences.dart’; // 本地存储库
import ‘…/model/todo_model.dart’; // 导入待办数据模型
import ‘package:uuid/uuid.dart’; // 用于生成唯一ID（已在pubspec.yaml中添加依赖）

/// 待办状态管理类
/// 继承ChangeNotifier，用于通知页面数据变化（provider的核心功能）
class TodoProvider extends ChangeNotifier {
// 存储所有待办事项的列表
List _todoList = [];
// 对外提供只读的待办列表，避免外部直接修改数据，保证数据安全性
List get todoList => _todoList;

// 初始化方法：APP启动时，从本地存储读取待办数据
Future initTodo() async {
// 获取shared_preferences实例（本地存储核心对象）
SharedPreferences prefs = await SharedPreferences.getInstance();
// 从本地存储读取数据（key为todo_list，默认值为空列表）
List todoStringList = prefs.getStringList(‘todo_list’) ?? [];
// 将读取到的字符串列表，转为TodoModel列表（反序列化）
_todoList = todoStringList
.map((todoString) => TodoModel.fromMap(Map.fromJson(todoString)))
.toList();
// 通知所有监听的页面，数据已更新，页面进行刷新
notifyListeners();
}

/// 添加待办事项
/// 参数：title（待办标题，用户输入）
Future addTodo(String title) async {
// 生成唯一ID（使用uuid库，确保每个待办的ID不重复）
String id = const Uuid().v4();
// 创建新的待办对象（默认未完成）
TodoModel newTodo = TodoModel(
id: id,
title: title,
);
// 将新待办添加到待办列表中
_todoList.add(newTodo);
// 将更新后的待办列表，同步到本地存储
await _saveTodoToLocal();
// 通知页面数据更新，刷新UI
notifyListeners();
}

/// 删除待办事项
/// 参数：id（待办ID，用于定位要删除的待办）
Future deleteTodo(String id) async {
// 从待办列表中，删除指定ID的待办
_todoList.removeWhere((todo) => todo.id == id);
// 同步到本地存储
await _saveTodoToLocal();
// 通知页面刷新
notifyListeners();
}

/// 标记待办完成/未完成
/// 参数：id（待办ID）、isCompleted（完成状态）
Future toggleTodoCompleted(String id, bool isCompleted) async {
// 找到指定ID的待办，修改其完成状态（使用copyWith方法，不修改原数据）
_todoList = _todoList.map((todo) {
if (todo.id == id) {
return todo.copyWith(isCompleted: isCompleted);
}
return todo; // 未匹配到的待办，保持不变
}).toList();
// 同步到本地存储
await _saveTodoToLocal();
// 通知页面刷新
notifyListeners();
}

/// 私有方法：将待办列表同步到本地存储（封装起来，避免代码冗余）
Future _saveTodoToLocal() async {
SharedPreferences prefs = await SharedPreferences.getInstance();
// 将TodoModel列表转为字符串列表（序列化）
List todoStringList = _todoList
.map((todo) => json.encode(todo.toMap()))
.toList();
// 存储到本地（key为todo_list，覆盖原有数据）
await prefs.setStringList(‘todo_list’, todoStringList);
}
}

新手注意：uuid库已在pubspec.yaml中添加依赖，无需额外配置，执行「Pub get」后即可使用，用于生成唯一的待办ID，避免删除待办时出错。

5.3 主页面：lib/pages/todo_page.dart

实现APP主页面，包含待办输入框、添加按钮、待办清单展示、删除按钮、完成状态切换，结合fluttertoast实现操作提示，适配鸿蒙设备屏幕，交互简洁友好，新手易理解。

// 导入依赖包
import ‘package:flutter/material.dart’;
import ‘package:provider/provider.dart’; // 状态管理相关
import ‘package:fluttertoast/fluttertoast.dart’; // 弹窗提示相关
import ‘…/provider/todo_provider.dart’; // 导入待办状态管理

/// 待办清单主页面（有状态组件，需管理输入框内容）
class TodoPage extends StatefulWidget {
const TodoPage({super.key});

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

class _TodoPageState extends State {
// 待办输入框控制器，用于获取用户输入的待办标题
final TextEditingController _todoController = TextEditingController();

@override
Widget build(BuildContext context) {
// 获取待办状态管理实例（监听数据变化，数据更新时页面自动刷新）
final todoProvider = Provider.of(context);

// 页面渲染完成后，初始化待办数据（从本地存储读取）
WidgetsBinding.instance.addPostFrameCallback((_) {
  todoProvider.initTodo();
});

return Scaffold(
  // 页面标题栏
  appBar: AppBar(
    title: const Text("Flutter鸿蒙待办清单"),
    centerTitle: true, // 标题居中
    backgroundColor: Colors.greenAccent, // 标题栏颜色（新手可自定义）
    elevation: 0, // 取消标题栏阴影，更简洁
  ),
  // 页面主体（可滚动，避免键盘遮挡输入框）
  body: Padding(
    padding: const EdgeInsets.all(16.0), // 页面内边距，避免内容贴边
    child: Column(
      children: [
        // 待办输入框 + 添加按钮（横向排列）
        Row(
          children: [
            // 待办输入框（占满大部分屏幕宽度）
            Expanded(
              child: TextField(
                controller: _todoController, // 绑定输入框控制器
                decoration: const InputDecoration(
                  labelText: "请输入待办事项", // 提示文字
                  labelStyle: TextStyle(color: Colors.grey, fontSize: 16),
                  border: OutlineInputBorder(), // 输入框边框
                  contentPadding: EdgeInsets.symmetric(horizontal: 12, vertical: 10),
                ),
                style: const TextStyle(fontSize: 16),
                keyboardType: TextInputType.text, // 输入类型为文本
                onSubmitted: (value) {
                  // 点击键盘回车，触发添加待办操作
                  _addTodo(todoProvider);
                },
              ),
            ),
            const SizedBox(width: 10), // 输入框与按钮之间的间距
            // 添加按钮
            ElevatedButton(
              onPressed: () {
                // 点击按钮，添加待办
                _addTodo(todoProvider);
              },
              style: ElevatedButton.styleFrom(
                backgroundColor: Colors.greenAccent,
                padding: const EdgeInsets.symmetric(horizontal: 20, vertical: 16),
                shape: RoundedRectangleBorder(
                  borderRadius: BorderRadius.circular(8),
                ),
              ),
              child: const Text(
                "添加",
                style: TextStyle(fontSize: 16, color: Colors.white),
              ),
            ),
          ],
        ),

        const SizedBox(height: 20), // 输入框区域与待办列表之间的间距

        // 待办清单展示（无待办时显示提示，有待办时显示列表）
        todoProvider.todoList.isEmpty
            ? // 无待办时，显示提示文字
            const Center(
                child: Text(
                  "暂无待办事项，添加你的第一个待办吧～",
                  style: TextStyle(fontSize: 16, color: Colors.grey),
                ),
              )
            : // 有待办时，显示待办列表
            Expanded(
                child: ListView.builder(
                  // 列表长度 = 待办数量
                  itemCount: todoProvider.todoList.length,
                  // 构建每个待办项
                  itemBuilder: (context, index) {
                    // 获取当前索引的待办对象
                    final todo = todoProvider.todoList[index];
                    return Container(
                      margin: const EdgeInsets.only(bottom: 10), // 待办项之间的间距
                      padding: const EdgeInsets.all(12),
                      decoration: BoxDecoration(
                        border: Border.all(color: Colors.grey.shade200),
                        borderRadius: BorderRadius.circular(8),
                      ),
                      child: Row(
                        children: [
                          // 完成状态复选框
                          Checkbox(
                            value: todo.isCompleted, // 绑定待办的完成状态
                            onChanged: (value) {
                              // 点击复选框，切换待办完成状态
                              if (value != null) {
                                todoProvider.toggleTodoCompleted(todo.id, value);
                              }
                            },
                            activeColor: Colors.greenAccent, // 选中时的颜色
                          ),
                          const SizedBox(width: 10),
                          // 待办标题（已完成时，文字加删除线）
                          Expanded(
                            child: Text(
                              todo.title,
                              style: TextStyle(
                                fontSize: 16,
                                // 已完成时，文字加删除线、变灰色
                                decoration: todo.isCompleted
                                    ? TextDecoration.lineThrough
                                    : TextDecoration.none,
                                color: todo.isCompleted ? Colors.grey : Colors.black,
                              ),
                            ),
                          ),
                          // 删除按钮
                          IconButton(
                            icon: const Icon(Icons.delete, color: Colors.redAccent),
                            onPressed: () {
                              // 点击删除按钮，删除当前待办
                              todoProvider.deleteTodo(todo.id);
                              // 弹窗提示删除成功
                              Fluttertoast.showToast(
                                msg: "待办删除成功",
                                toastLength: Toast.LENGTH_SHORT,
                                gravity: ToastGravity.BOTTOM,
                                backgroundColor: Colors.grey,
                                textColor: Colors.white,
                                fontSize: 14,
                              );
                            },
                          ),
                        ],
                      ),
                    );
                  },
                ),
              ),
      ],
    ),
  ),
);

}

/// 封装添加待办方法（避免代码冗余）
void _addTodo(TodoProvider todoProvider) {
// 获取用户输入的待办标题（去除前后空格）
String title = _todoController.text.trim();
// 校验：若待办标题为空，弹出提示
if (title.isEmpty) {
Fluttertoast.showToast(
msg: “请输入待办事项内容”,
toastLength: Toast.LENGTH_SHORT,
gravity: ToastGravity.BOTTOM,
backgroundColor: Colors.redAccent,
textColor: Colors.white,
fontSize: 14,
);
return;
}
// 调用状态管理的addTodo方法，添加待办
todoProvider.addTodo(title);
// 弹窗提示添加成功
Fluttertoast.showToast(
msg: “待办添加成功”,
toastLength: Toast.LENGTH_SHORT,
gravity: ToastGravity.BOTTOM,
backgroundColor: Colors.greenAccent,
textColor: Colors.white,
fontSize: 14,
);
// 清空输入框
_todoController.clear();
}

// 页面销毁时，释放输入框控制器资源，避免内存泄漏（新手必加）
@override
void dispose() {
_todoController.dispose();
super.dispose();
}
}

5.4 项目入口：lib/main.dart

项目入口文件，配置全局状态管理（provider），设置APP主题和首页面，确保整个APP能正常启动，所有页面都能访问待办状态管理实例。

// 导入依赖包
import ‘package:flutter/material.dart’;
import ‘package:provider/provider.dart’; // 状态管理相关
import ‘provider/todo_provider.dart’; // 导入待办状态管理
import ‘pages/todo_page.dart’; // 导入主页面

// 项目入口函数（程序启动的入口，所有代码从这里开始执行）
void main() {
runApp(const MyApp());
}

/// APP根组件（无状态组件）
class MyApp extends StatelessWidget {
const MyApp({super.key});

@override
Widget build(BuildContext context) {
// 使用ChangeNotifierProvider包裹整个APP，实现全局状态管理
// 让所有子页面都能访问TodoProvider实例，实现数据共享
return ChangeNotifierProvider(
// 创建TodoProvider实例，供全局使用
create: (context) => TodoProvider(),
child: MaterialApp(
title: ‘Flutter鸿蒙待办清单’, // APP标题（显示在设备任务栏）
debugShowCheckedModeBanner: false, // 关闭调试模式横幅（发布时必须关闭）
// APP主题配置（新手可自定义颜色）
theme: ThemeData(
primarySwatch: Colors.green, // 主题色
visualDensity: VisualDensity.adaptivePlatformDensity, // 适配不同设备密度
),
home: const TodoPage(), // 首页面设置为待办主页面
),
);
}
}

六、运行到鸿蒙设备/模拟器（新手详细步骤）

6.1 配置鸿蒙设备/模拟器

打开DevEco Studio，点击顶部菜单栏「Tools」→「Device Manager」，打开设备管理器（若没有该选项，需更新DevEco Studio到最新版）；
创建鸿蒙模拟器：

点击设备管理器中的「New Device」，选择「Phone」（手机型号）；
选择鸿蒙系统版本（必须6.0及以上，如HarmonyOS 6.2.0）；
点击「Next」，自定义模拟器名称（如“HarmonyOS 6.2 Phone”），点击「Finish」；
等待模拟器启动（首次启动可能需要5-10分钟，耐心等待，启动成功后会显示鸿蒙系统桌面）。

真机测试（可选）：

将鸿蒙6.0+系统的手机连接电脑，开启开发者模式（设置→关于手机→连续点击版本号7次）；
开启“USB调试”（设置→系统和更新→开发者选项→开启USB调试）；
在DevEco Studio的设备管理器中，会自动识别手机，选择手机作为运行设备即可。

6.2 运行项目

在DevEco Studio中，选择已启动的鸿蒙模拟器/真机作为运行设备（顶部设备选择栏，下拉选择）；
点击顶部的「Run」按钮（绿色三角形图标），或在终端执行命令 flutter run，开始编译项目；
编译成功后，鸿蒙设备/模拟器上会自动打开APP，即可进行以下操作测试：

在输入框中输入待办内容（如“学习Flutter鸿蒙开发”），点击「添加」，可看到待办添加成功，弹窗提示；
点击待办项前的复选框，可标记待办为“已完成”（文字加删除线）或“未完成”；
点击待办项右侧的删除按钮，可删除待办，弹窗提示删除成功；
关闭APP后重新打开，之前添加的待办仍存在（验证本地存储功能）。

七、常见问题排查（新手必看，避免踩坑）

问题1：编译报错“Could not find the Flutter SDK”
解决：重新检查鸿蒙定制版Flutter SDK的环境变量配置，确保Path中添加了SDK的bin目录，关闭终端重新打开，执行flutter --version验证。
问题2：三方库安装失败，提示“version solving failed”
解决：降低三方库版本（如将provider改为^{6.0.0、shared_preferences改为}2.2.0），修改pubspec.yaml后重新执行「Pub get」。
问题3：APP无法在鸿蒙设备上运行，提示“device not found”
解决：确保模拟器已启动，或真机已正确连接并开启USB调试，重新选择设备后，重启项目运行。
问题4：打开APP后，待办数据不显示/无法添加待办
解决：检查shared_preferences的使用方法，确保toMap()和fromMap()方法正确，重启项目，或清除APP缓存后重新运行。
问题5：弹窗提示不显示
解决：检查fluttertoast的版本是否适配鸿蒙6.0+，若版本过高，可降低至^8.2.0，重新安装依赖后运行。