本项目是专为鸿蒙6.0及以上版本（API Level 20+） 打造的Flutter跨端实战项目，面向鸿蒙原生开发者新手，无需深厚跨端基础，通过集成鸿蒙6.0专属适配的Flutter三方库，实现一套代码运行在鸿蒙6.0设备上的TODO待办清单应用，具备数据本地持久化、状态管理、轻量交互提示等核心功能，全程贴合鸿蒙6.0+API20最新开发规范，可直接部署运行。

一、开发环境适配：鸿蒙6.0(API20+)专属配置

1.1 核心工具与SDK版本要求

本次开发严格基于鸿蒙6.0正式版、API Level 20及以上版本，需安装对应适配工具，杜绝版本兼容问题：

1. DevEco Studio：安装最新版DevEco Studio 5.0 Beta2及以上，内置HarmonyOS 6.0（API20） SDK，必须在SDK Manager中勾选API20版本SDK、OHPM包管理器、模拟器镜像（鸿蒙6.0手机/平板镜像）。

2. Flutter SDK：选用适配鸿蒙6.0+API20的Flutter官方稳定版，版本≥3.28.0，该版本已完成鸿蒙6.0全平台适配，支持API20接口调用。

3. 环境依赖：Git 2.45+、Dart SDK 3.5.0+，同步配置系统环境变量，确保终端可直接调用Flutter、HarmonyOS命令。

1.2 环境校验（API20+专属）

打开终端，执行以下命令，校验鸿蒙6.0+API20环境是否配置成功：

校验Flutter整体环境

flutter doctor

精准校验鸿蒙6.0(API20)环境适配

flutter doctor --android-licenses
flutter config --enable-ohos

执行后若显示[✓] HarmonyOS 6.0 (API20)相关标识，代表环境配置达标，可进入项目创建环节。

二、创建适配鸿蒙6.0(API20)的Flutter项目

2.1 项目创建命令（API20专属参数）

打开终端，进入项目存储目录，执行适配鸿蒙6.0+API20的项目创建命令，指定仅支持鸿蒙平台，避免冗余端适配：

创建Flutter项目，指定鸿蒙6.0(API20+)为目标平台，项目名：flutter_harmony6_todo

flutter create flutter_harmony6_todo --platforms=ohos --ohos-api-level=20

进入项目根目录

cd flutter_harmony6_todo

2.2 鸿蒙6.0项目核心配置修改

进入项目ohos目录，打开module.json5配置文件，将SDK版本强制指定为API20，适配鸿蒙6.0系统，核心配置如下：

{
“module”: {
“name”: “entry”,
“type”: “entry”,
“srcEntry”: “./ets/entryability/EntryAbility.ets”,
“description”: “Flutter鸿蒙6.0 TODO项目”,
“mainElement”: “EntryAbility”,
“deviceTypes”: [
“phone”,
“tablet”
],
“deliveryWithInstall”: true,
“installationFree”: false,
“pages”: “$profile:pages”,
“abilities”: [
{
“name”: “EntryAbility”,
“srcEntry”: “./ets/entryability/EntryAbility.ets”,
“description”: “MainAbility”,
“type”: “page”,
“launchType”: “standard”,
“orientation”: “unspecified”,
“supportWindowMode”: [“windowed”, “fullscreen”],
“priority”: 3,
“labels”: [
{
“value”: “Flutter鸿蒙TODO”,
“language”: “zh-CN”
}
]
}
]
},
“app”: {
“apiVersion”: {
“compatible”: 20,
“target”: 20,
“releaseType”: “Release”
},
“bundleName”: “com.example.flutterharmony6todo”,
“vendor”: “example”,
“versionCode”: 1,
“versionName”: “1.0.0”
}
}

关键说明：compatible和target均设置为20，确保项目仅兼容鸿蒙6.0及以上系统，低版本鸿蒙设备无法安装，保证运行稳定性。

三、鸿蒙6.0(API20+)适配三方库选型与集成

针对鸿蒙6.0+API20系统，选用官方认证、API20专属适配的Flutter三方库，无兼容问题，直接集成即可调用，本次项目核心三方库：

1. provider: ^6.2.0：Flutter状态管理库，适配鸿蒙6.0线程模型，实现TODO数据跨组件同步

2. shared_preferences_ohos: ^2.3.0：鸿蒙6.0专属本地存储三方库，基于API20数据存储接口开发，替代通用版shared_preferences，兼容性拉满

3. fluttertoast_ohos: ^8.3.0：鸿蒙6.0系统弹窗适配三方库，遵循鸿蒙6.0 UI设计规范，替代通用版fluttertoast，避免弹窗样式错乱

3.1 pubspec.yaml三方库配置

打开项目根目录pubspec.yaml文件，严格按照YAML语法，添加鸿蒙6.0(API20)专属三方库依赖，配置如下：

name: flutter_harmony6_todo
description: 适配鸿蒙6.0(API20+)的Flutter跨端TODO待办清单项目
version: 1.0.0+1

适配API20的Dart与Flutter版本约束

environment:
sdk: ‘>=3.5.0<4.0.0’
flutter: ‘>=3.28.0’

dependencies:
flutter:
sdk: flutter

鸿蒙6.0适配 状态管理三方库

provider: ^6.2.0

鸿蒙6.0(API20)专属 本地持久化三方库

shared_preferences_ohos: ^2.3.0

鸿蒙6.0(API20)专属 轻量提示三方库

fluttertoast_ohos: ^8.3.0

dev_dependencies:
flutter_test:
sdk: flutter
flutter_lints: ^4.0.0

启用Material3，适配鸿蒙6.0扁平化UI风格

flutter:
uses-material-design: true

3.2 三方库安装与OHPM同步

终端执行命令，完成Flutter三方库安装，并同步鸿蒙6.0 OHPM包依赖，确保API20接口调用正常：

安装Flutter三方库

flutter pub get

同步鸿蒙6.0 OHPM依赖（API20专属步骤）

cd ohos
ohpm install
cd …

执行完成后，三方库完成全量集成，可直接在代码中调用鸿蒙6.0专属接口。

四、核心代码实现：鸿蒙6.0(API20+)TODO项目

4.1 数据状态管理类（Provider+鸿蒙本地存储）

在lib目录下创建todo_model.dart文件，基于provider三方库实现状态管理，调用shared_preferences_ohos三方库完成鸿蒙6.0本地数据持久化，代码带详细注释，适配API20规范：

import ‘package:flutter/foundation.dart’;
// 导入鸿蒙6.0专属本地存储三方库
import ‘package:shared_preferences_ohos/shared_preferences_ohos.dart’;

// TODO数据状态管理类，继承ChangeNotifier，适配鸿蒙6.0线程机制
class TodoModel extends ChangeNotifier {
// 存储待办事项 _todoList = [];

// 对外提供待办列表的只读 get todoList => _todoList;

// 构造函数：初始化时加载鸿蒙6.0本地存储的TODO数据
TodoModel() {
loadLocalTodoData();
}

/// 添加待办事项
/// [todo]：输入的待办内容
void addTodoItem(String todo) {
// 过滤空内容
if (todo.trim().isEmpty) return;
_todoList.add(todo.trim());
// 保存到鸿蒙6.0本地存储
saveTodoToLocal();
// 通知UI刷新（provider三方库核心机制）
notifyListeners();
}

/// 删除待办事项
/// [index]：待办事项在列表中的索引
void deleteTodoItem(int index) {
_todoList.removeAt(index);
// 同步更新鸿蒙6.0本地存储
saveTodoToLocal();
// 通知UI刷新
notifyListeners();
}

/// 保存TODO数据到鸿蒙6.0本地（shared_preferences_ohos三方库调用）
saveTodoToLocal() async {
// 获取鸿蒙6.0专属本地存储实例
final SharedPreferencesOhos prefs = await SharedPreferencesOhos.getInstance();
// 以键值对形式存储列表数据，键名：harmony6_todo_list
await prefs.setStringList(‘harmony6_todo_list’, _todoList);
}

/// 从鸿蒙6.0本地加载TODO数据（shared_preferences_ohos三方库调用） loadLocalTodoData() async {
final SharedPreferencesOhos prefs = await SharedPreferencesOhos.getInstance();
// 读取本地数据，无数据时返回空列表
_todoList = prefs.getStringList(‘harmony6_todo_list’) ?? [];
// 加载完成后通知UI刷新
notifyListeners();
}

/// 清空所有待办事项（拓展功能）
void clearAllTodo() {
_todoList.clear();
saveTodoToLocal();
notifyListeners();
}
}

4.2 主页面UI与交互实现

修改lib/main.dart文件，编写适配鸿蒙6.0 UI风格的主页面，集成三大三方库，实现TODO添加、删除、提示功能，代码适配API20交互规范：

import ‘package:flutter/material.dart’;
import ‘package:provider/provider.dart’;
// 导入鸿蒙6.0专属提示框三方库
import ‘package:fluttertoast_ohos/fluttertoast_ohos.dart’;
import ‘todo_model.dart’;

void main() {
runApp(
// 绑定状态管理Provider，全局共享TODO数据
ChangeNotifierProvider(
create: (context) => TodoModel(),
child: const FlutterHarmony6TodoApp(),
),
);
}

// 项目主应用组件
class FlutterHarmony6TodoApp extends StatelessWidget {
const FlutterHarmony6TodoApp({super.key});

@override
Widget build(BuildContext context) {
return MaterialApp(
title: ‘Flutter鸿蒙6.0 TODO清单’,
// 适配鸿蒙6.0系统主题，跟随系统深色/浅色模式
theme: ThemeData(
colorScheme: ColorScheme.fromSeed(
seedColor: Colors.blueAccent,
brightness: Brightness.light,
),
useMaterial3: true,
),
darkTheme: ThemeData(
colorScheme: ColorScheme.fromSeed(
seedColor: Colors.blueAccent,
brightness: Brightness.dark,
),
useMaterial3: true,
),
// 适配鸿蒙6.0系统主题模式
themeMode: ThemeMode.system,
home: const TodoMainPage(),
debugShowCheckedModeBanner: false,
);
}
}

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

createState() => _TodoMainPageState();
}

class _TodoMainPageState extends {
// 输入框控制器，获取待办事项输入内容
final TextEditingController _todoInputController = TextEditingController();
// 鸿蒙6.0专属Toast实例
final FToastOhos _fToast = FToastOhos();

@override
void initState() {
super.initState();
// 初始化Toast，绑定当前上下文，适配鸿蒙6.0弹窗层级
_fToast.init(context);
}

@override
Widget build(BuildContext context) {
// 获取Provider状态管理实例
final TodoModel todoModel = Provider(context);

return Scaffold(
  // 适配鸿蒙6.0顶部状态栏样式
  appBar: AppBar(
    title: const Text('Flutter+三方库+鸿蒙6.0 TODO清单'),
    centerTitle: true,
    elevation: 0,
  ),
  body: Padding(
    padding: const EdgeInsets.symmetric(horizontal: 18, vertical: 20),
    child: Column(
      children: [
        // 待办事项输入区域
        Row(
          crossAxisAlignment: CrossAxisAlignment.center,
          children: [
            Expanded(
              child: TextField(
                controller: _todoInputController,
                decoration: InputDecoration(
                  hintText: '请输入待办事项（鸿蒙6.0专属）',
                  border: const OutlineInputBorder(
                    borderRadius: BorderRadius.all(Radius.circular(12)),
                  ),
                  filled: true,
                  fillColor: Colors.grey.shade50,
                ),
                style: const TextStyle(fontSize: 16),
              ),
            ),
            const SizedBox(width: 12),
            // 添加待办按钮
            ElevatedButton(
              onPressed: () {
                String inputContent = _todoInputController.text.trim();
                if (inputContent.isEmpty) {
                  // 空内容提示
                  showHarmonyToast('请输入有效待办内容');
                  return;
                }
                // 调用添加方法
                todoModel.addTodoItem(inputContent);
                // 添加成功提示
                showHarmonyToast('待办事项添加成功');
                // 清空输入框
                _todoInputController.clear();
              },
              style: ElevatedButton.styleFrom(
                padding: const EdgeInsets.symmetric(horizontal: 20, vertical: 16),
                shape: RoundedRectangleBorder(
                  borderRadius: BorderRadius.circular(12),
                ),
              ),
              child: const Text('添加', style: TextStyle(fontSize: 16)),
            ),
          ],
        ),
        const SizedBox(height: 25),
        // 待办列表展示区域
        Expanded(
          child: todoModel.todoList.isEmpty
              ? const Center(
                  child: Text(
                    '暂无待办事项，快来添加吧～',
                    style: TextStyle(fontSize: 18, color: Colors.grey),
                  ),
                )
              : ListView.builder(
                  itemCount: todoModel.todoList.length,
                  itemBuilder: (context, index) {
                    return Card(
                      margin: const EdgeInsets.only(bottom: 10),
                      shape: RoundedRectangleBorder(
                        borderRadius: BorderRadius.circular(12),
                      ),
                      elevation: 2,
                      child: ListTile(
                        title: Text(
                          todoModel.todoList[index],
                          style: const TextStyle(fontSize: 17),
                        ),
                        trailing: IconButton(
                          icon: const Icon(Icons.delete_outline, color: Colors.redAccent, size: 24),
                          onPressed: () {
                            // 调用删除方法
                            todoModel.deleteTodoItem(index);
                            // 删除成功提示
                            showHarmonyToast('待办事项已删除');
                          },
                        ),
                        contentPadding: const EdgeInsets.symmetric(horizontal: 16, vertical: 8),
                      ),
                    );
                  },
                ),
        ),
      ],
    ),
  ),
);

}

/// 封装鸿蒙6.0专属Toast提示方法（fluttertoast_ohos三方库）
/// [msg]：提示文字内容
void showHarmonyToast(String msg) {
_fToast.showToast(
child: Container(
padding: const EdgeInsets.symmetric(horizontal: 24, vertical: 12),
decoration: BoxDecoration(
color: Colors.blueAccent.withOpacity(0.9),
borderRadius: BorderRadius.circular(8),
),
child: Text(msg, style: const TextStyle(color: Colors.white, fontSize: 16)),
),
gravity: ToastGravityOhos.CENTER,
toastDuration: const Duration(seconds: 1),
);
}

@override
void dispose() {
// 释放输入框控制器资源
_todoInputController.dispose();
super.dispose();
}
}

五、鸿蒙6.0(API20+)设备运行与部署

5.1 运行环境准备

1. 鸿蒙6.0模拟器：打开DevEco Studio，创建API20/鸿蒙6.0手机模拟器，启动并保持运行状态。

2. 鸿蒙6.0真机：将鸿蒙6.0及以上版本手机开启开发者模式、USB调试、允许安装未知来源应用，通过USB连接电脑，DevEco Studio可识别设备。

5.2 项目运行命令（API20专属）

终端执行以下命令，直接将项目部署到鸿蒙6.0(API20)设备，支持热重载：

运行项目到鸿蒙6.0设备，指定API20

flutter run -d ohos --ohos-api-level=20

首次运行会编译鸿蒙6.0相关资源，等待2-3分钟，项目成功启动后，即可在设备上看到完整的TODO应用界面。

5.3 功能验证（鸿蒙6.0专属）

1. 输入待办内容点击添加，列表实时更新，弹出鸿蒙6.0样式提示框；

2. 删除待办事项，数据同步移除，本地存储持久化生效；

3. 关闭应用重新打开，待办数据不丢失，验证shared_preferences_ohos三方库适配正常；

4. 切换系统深色/浅色模式，应用主题同步变化，适配鸿蒙6.0系统规范。

六、项目核心亮点与适配说明

1. 版本精准适配：全程基于鸿蒙6.0+API20开发，SDK版本无降级，贴合最新鸿蒙生态规范；

2. 三方库专属优化：摒弃通用版三方库，采用鸿蒙6.0(API20)专属适配版，解决跨端兼容痛点；

3. 鸿蒙原生体验：UI风格、弹窗样式、数据存储均遵循鸿蒙6.0设计规范，无跨端违和感；

4. 新手友好：代码全注释，步骤无省略，鸿蒙原生开发者可零门槛上手Flutter跨端开发。

七、常见问题排查（鸿蒙6.0+API20专属）

1. 三方库报错：确认使用shared_preferences_ohos和fluttertoast_ohos，而非通用版，重新执行flutter pub get && ohpm install；

2. 无法运行：检查DevEco Studio是否配置API20 SDK，项目module.json5中API版本是否为20；

3. 热重载失效：执行flutter clean清理缓存，重新运行flutter run -d ohos --ohos-api-level=20。