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

本文专为鸿蒙入门开发者打造，以可直接运行的 TODO 清单项目为实战案例，手把手教你用 Flutter 跨端框架开发鸿蒙应用，全程包含Flutter 核心配置、三方库集成、鸿蒙真机 / 模拟器调试，零基础也能跟着实现完整功能。

一、项目核心说明

技术栈：Flutter（跨端框架）+ 鸿蒙 OpenHarmony（目标平台）+ 实用三方库

项目功能：待办事项添加、标记完成、删除、本地持久化存储

必用三方库：

• shared_preferences：本地数据持久化（保存 TODO 数据，重启不丢失）

• fluttertoast：轻量级提示弹窗（操作反馈）

适配目标：鸿蒙手机 / 平板 / 模拟器全兼容

二、前置环境准备（新手必看）

1. 基础环境安装

• 安装 Flutter SDK（≥3.19.0，推荐稳定版）

• 安装 DevEco Studio（鸿蒙官方 IDE，用于运行模拟器 / 真机）

• 配置 Flutter 鸿蒙编译环境：
  终端执行：flutter config --enable-openharmony

2. 验证环境

终端输入：flutter devices，若显示鸿蒙设备 / 模拟器，说明环境配置成功。

三、创建 Flutter 鸿蒙项目

步骤 1：新建 Flutter 项目

终端执行命令，创建项目：

flutter create flutter_harmony_todo
cd flutter_harmony_todo

步骤 2：启用鸿蒙平台支持

项目根目录执行：

flutter create --platforms=openharmony .

执行后，项目会自动生成openharmony适配目录，完成鸿蒙基础配置。

四、集成三方库（核心步骤）

步骤 1：修改pubspec.yaml配置

打开项目根目录的pubspec.yaml文件，在dependencies节点下添加三方库：

dependencies:
  flutter:
    sdk: flutter
  # 本地持久化三方库（保存TODO数据）
  shared_preferences: ^2.5.2
  # 提示弹窗三方库（操作反馈）
  fluttertoast: ^8.2.12

步骤 2：安装三方库

终端执行命令，拉取依赖：

flutter pub get

等待依赖下载完成，无报错即集成成功。

五、完整项目代码实现（带详细注释）

替换项目lib/main.dart文件的全部代码，以下是可直接运行的完整代码：

import 'package:flutter/material.dart';
// 导入本地持久化三方库
import 'package:shared_preferences/shared_preferences.dart';
// 导入提示弹窗三方库
import 'package:fluttertoast/fluttertoast.dart';

void main() {
  runApp(const MyApp());
}

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

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Flutter鸿蒙TODO清单',
      // 关闭调试标签
      debugShowCheckedModeBanner: false,
      theme: ThemeData(primarySwatch: Colors.blue),
      home: const TodoPage(),
    );
  }
}

// TODO主页面
class TodoPage extends StatefulWidget {
  const TodoPage({super.key});

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

class _TodoPageState extends State<TodoPage> {
  // 输入框控制器：获取输入的待办内容
  final TextEditingController _todoController = TextEditingController();
  // 待办数据列表：存储所有TODO项
  List<String> _todoList = [];
  // 已完成项标记列表：记录哪些TODO被勾选
  List<bool> _isCompletedList = [];

  @override
  void initState() {
    super.initState();
    // 页面初始化时，加载本地存储的TODO数据
    _loadTodoData();
  }

  // ------------------- 核心方法：本地数据操作（三方库使用） -------------------
  // 1. 从本地加载TODO数据（shared_preferences三方库）
  Future<void> _loadTodoData() async {
    // 获取本地存储实例
    final prefs = await SharedPreferences.getInstance();
    // 读取本地存储的待办列表，无数据则返回空数组
    setState(() {
      _todoList = prefs.getStringList('todoList') ?? [];
      _isCompletedList = prefs
              .getStringList('isCompletedList')
              ?.map((e) => e == 'true')
              .toList() ??
          List.generate(_todoList.length, (index) => false);
    });
  }

  // 2. 保存TODO数据到本地（shared_preferences三方库）
  Future<void> _saveTodoData() async {
    final prefs = await SharedPreferences.getInstance();
    // 存储待办内容列表
    await prefs.setStringList('todoList', _todoList);
    // 存储完成状态列表
    await prefs.setStringList(
      'isCompletedList',
      _isCompletedList.map((e) => e.toString()).toList(),
    );
  }

  // ------------------- 业务功能方法 -------------------
  // 添加待办事项
  void _addTodo() {
    String todoContent = _todoController.text.trim();
    // 校验输入内容不能为空
    if (todoContent.isEmpty) {
      Fluttertoast.showToast(msg: "请输入待办内容");
      return;
    }

    setState(() {
      _todoList.add(todoContent);
      _isCompletedList.add(false);
      // 清空输入框
      _todoController.clear();
    });

    // 保存到本地
    _saveTodoData();
    Fluttertoast.showToast(msg: "添加成功");
  }

  // 切换待办完成状态
  void _toggleComplete(int index) {
    setState(() {
      _isCompletedList[index] = !_isCompletedList[index];
    });
    _saveTodoData();
  }

  // 删除待办事项
  void _deleteTodo(int index) {
    setState(() {
      _todoList.removeAt(index);
      _isCompletedList.removeAt(index);
    });
    _saveTodoData();
    Fluttertoast.showToast(msg: "删除成功");
  }

  // ------------------- UI页面布局 -------------------
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text("Flutter鸿蒙TODO清单"),
      ),
      body: Padding(
        padding: const EdgeInsets.all(16.0),
        child: Column(
          children: [
            // 输入框 + 添加按钮
            Row(
              children: [
                Expanded(
                  child: TextField(
                    controller: _todoController,
                    decoration: const InputDecoration(
                      hintText: "请输入待办事项",
                      border: OutlineInputBorder(),
                    ),
                  ),
                ),
                const SizedBox(width: 10),
                ElevatedButton(
                  onPressed: _addTodo,
                  child: const Text("添加"),
                ),
              ],
            ),
            const SizedBox(height: 20),
            // 待办列表展示区域
            Expanded(
              child: _todoList.isEmpty
                  ? const Center(child: Text("暂无待办事项，快去添加吧~"))
                  : ListView.builder(
                      itemCount: _todoList.length,
                      itemBuilder: (context, index) {
                        return Card(
                          margin: const EdgeInsets.only(bottom: 8),
                          child: ListTile(
                            // 勾选框：标记完成状态
                            leading: Checkbox(
                              value: _isCompletedList[index],
                              onChanged: (value) => _toggleComplete(index),
                            ),
                            // 待办内容：已完成则添加删除线
                            title: Text(
                              _todoList[index],
                              style: TextStyle(
                                decoration: _isCompletedList[index]
                                    ? TextDecoration.lineThrough
                                    : TextDecoration.none,
                                color: _isCompletedList[index]
                                    ? Colors.grey
                                    : Colors.black,
                              ),
                            ),
                            // 删除按钮
                            trailing: IconButton(
                              icon: const Icon(Icons.delete, color: Colors.red),
                              onPressed: () => _deleteTodo(index),
                            ),
                          ),
                        );
                      },
                    ),
            ),
          ],
        ),
      ),
    );
  }
}

六、Flutter 应用运行到鸿蒙设备

步骤 1：启动鸿蒙模拟器 / 连接真机

• 打开 DevEco Studio → 设备管理器 → 启动鸿蒙手机模拟器

• 或用数据线连接鸿蒙真机，开启USB 调试

步骤 2：运行 Flutter 项目

终端执行命令，自动编译并安装到鸿蒙设备：

flutter run -d openharmony

等待编译完成，鸿蒙设备上会自动打开 TODO 清单应用。

七、功能测试（验证效果）

• 添加待办：输入内容点击添加，弹出「添加成功」提示

• 标记完成：勾选复选框，文字自动添加灰色删除线

• 删除待办：点击删除按钮，移除对应事项

• 持久化验证：关闭应用重新打开，数据不会丢失（shared_preferences三方库生效）

• 鸿蒙适配：界面完美适配鸿蒙系统风格，无卡顿、无兼容问题

八、核心知识点总结

• Flutter 鸿蒙适配：通过flutter create \-\-platforms=openharmony快速启用鸿蒙平台支持

• 三方库集成：在pubspec.yaml声明依赖，flutter pub get一键安装，鸿蒙平台完美兼容

• 核心三方库作用：

  • shared_preferences：轻量级本地存储，无需数据库即可保存数据

  • fluttertoast：极简提示弹窗，提升用户体验

• 跨端优势：一套 Flutter 代码，同时运行在 Android、iOS、鸿蒙设备，无需重复开发

九、常见问题解决

• 三方库安装失败：检查网络，执行flutter clean后重新flutter pub get

• 无法运行到鸿蒙设备：确认开启 USB 调试，执行flutter devices查看设备是否识别

• 数据不持久化：检查\_saveTodoData方法是否在增删改后调用

结语

本案例是Flutter + 鸿蒙 + 三方库的入门级实战，覆盖了跨端开发、三方库集成、鸿蒙适配三大核心技能。作为鸿蒙开发者，掌握 Flutter 跨端技术后，可快速实现一套代码多端运行，大幅提升开发效率。后续可扩展更多三方库（如网络请求、图片加载），开发更复杂的鸿蒙跨端应用！