欢迎加入开源鸿蒙跨平台社区： https://openharmonycrossplatform.csdn.net
作为鸿蒙开发者，针对鸿蒙 API 20 及以上、HarmonyOS 6.0 及以上版本，Flutter 官方已完成深度适配，无需原生改造即可实现一套代码编译运行在鸿蒙最新系统上。本文专为鸿蒙最新版本定制，通过可直接运行的任务清单项目，手把手教你 Flutter 环境配置、鸿蒙 API20+/6.0+ 适配、三方库集成、编译运行全流程，代码带详细注释，新手直接上手。

文章核心关键词

Flutter、三方库、鸿蒙、API20+、HarmonyOS6.0+、跨端开发

---

一、项目需求与技术选型

1. 项目案例设计

开发适配鸿蒙 API20+/HarmonyOS6.0+ 的 Flutter 任务清单应用，核心功能：

1. 本地持久化存储任务清单（集成 Flutter 官方兼容鸿蒙最新版三方库）
2. 任务添加、标记完成、删除、一键清空
3. 完美兼容鸿蒙 API20、API21、HarmonyOS 6.0/6.1 真机/模拟器
4. 支持鸿蒙最新系统特性，无兼容报错

2. 核心技术栈

• Flutter 3.24.0+（强制要求，完美支持鸿蒙 API20+/6.0+）
• 三方库：shared_preferences: ^2.5.5（兼容鸿蒙 API20+/6.0+ 的本地存储）
• 开发工具：VS Code / Android Studio / DevEco Studio
• 运行平台：鸿蒙 API20+ 模拟器、HarmonyOS 6.0+ 真机
• 系统要求：OpenHarmony API 20 及以上 / HarmonyOS 6.0 及以上

---

二、环境准备（鸿蒙 API20+/6.0+ 专属配置）

1. 强制前置条件

1. 安装 Flutter 3.24.0 及以上版本（低版本不支持鸿蒙 API20+）
2. 安装 DevEco Studio（创建鸿蒙 API20+/6.0+ 模拟器）
3. 电脑已配置 Flutter 系统环境变量

2. 检查环境与开启鸿蒙支持

打开终端，依次执行命令：

# 1. 查看Flutter版本（必须≥3.24.0）
flutter --version

# 2. 检查环境依赖
flutter doctor

# 3. 强制开启鸿蒙最新平台支持（API20+/6.0+必备）
flutter config --enable-openharmony

3. 验证鸿蒙最新版本支持

执行命令，查看是否启用成功：

flutter config

显示 openharmony: true 即配置成功。

---

三、创建 Flutter 项目（适配鸿蒙 API20+/6.0+）

步骤1：创建项目

flutter create flutter_harmony_todo
cd flutter_harmony_todo

步骤2：配置鸿蒙最低 API 版本（核心！）

打开项目目录：openharmony/build-profile.json5
修改最低 API 版本为 20，适配鸿蒙 6.0+：

{
  "product": "default",
  "compileSdkVersion": 21,
  "compatSdkVersion": 21,
  "minSdkVersion": 20,
  "targetSdkVersion": 21
}

---

四、集成兼容鸿蒙 API20+/6.0+ 的三方库

本项目使用 shared_preferences 最新版，原生支持鸿蒙 API20+/6.0+，无需任何改造。

步骤1：添加三方库依赖

打开根目录 pubspec.yaml，添加依赖：

name: flutter_harmony_todo
description: Flutter适配鸿蒙API20+/6.0+任务清单项目
version: 1.0.0+1

environment:
  sdk: '>=3.24.0 <4.0.0'

dependencies:
  flutter:
    sdk: flutter
  shared_preferences: ^2.5.5
  cupertino_icons: ^1.0.8

dev_dependencies:
  flutter_test:
    sdk: flutter
  flutter_lints: ^4.0.0

flutter:
  uses-material-design: true

步骤2：安装三方库

flutter pub get

无报错即集成成功，可直接在鸿蒙 API20+/6.0+ 上调用。

---

五、完整项目代码（适配鸿蒙 API20+/6.0+）

替换 lib/main.dart 全部代码：

import 'package:flutter/material.dart';
import 'package:shared_preferences/shared_preferences.dart';

void main() => runApp(const MyApp());

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

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

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

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

class _TodoPageState extends State<TodoPage> {
  List<String> _todoList = [];
  final TextEditingController _todoController = TextEditingController();
  late SharedPreferences _prefs;

  @override
  void initState() {
    super.initState();
    _initStorage();
  }

  Future<void> _initStorage() async {
    _prefs = await SharedPreferences.getInstance();
    setState(() {
      _todoList = _prefs.getStringList('harmony_todos') ?? [];
    });
  }

  Future<void> _saveData() async {
    await _prefs.setStringList('harmony_todos', _todoList);
  }

  void _addTodo() {
    if (_todoController.text.trim().isNotEmpty) {
      setState(() {
        _todoList.add(_todoController.text.trim());
        _saveData();
        _todoController.clear();
      });
    }
  }

  void _deleteTodo(int index) {
    setState(() {
      _todoList.removeAt(index);
      _saveData();
    });
  }

  void _clearAll() {
    setState(() {
      _todoList.clear();
      _saveData();
    });
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text("Flutter × 鸿蒙 任务清单"),
        actions: [
          IconButton(icon: const Icon(Icons.delete_sweep), onPressed: _clearAll)
        ],
      ),
      body: Padding(
        padding: const EdgeInsets.all(16),
        child: Column(
          children: [
            Row(
              children: [
                Expanded(child: TextField(
                  controller: _todoController,
                  decoration: const InputDecoration(hintText: "输入任务内容", border: OutlineInputBorder()),
                  onSubmitted: (v) => _addTodo(),
                )),
                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: (ctx, index) {
                  return Card(
                    child: ListTile(
                      title: Text(_todoList[index]),
                      trailing: IconButton(
                        icon: const Icon(Icons.delete, color: Colors.red),
                        onPressed: () => _deleteTodo(index),
                      ),
                    ),
                  );
                },
              ),
            ),
          ],
        ),
      ),
    );
  }
}

---

六、运行到鸿蒙 API20+/6.0+ 设备

方式1：运行在鸿蒙 API20+ 模拟器

1. 打开 DevEco Studio → 设备管理器 → 创建 API20 及以上模拟器
2. 启动模拟器
3. 终端执行：

flutter run

方式2：运行在 HarmonyOS 6.0+ 真机

1. 鸿蒙 6.0+ 真机开启开发者模式
2. 开启 USB 调试
3. 连接电脑，执行：

flutter run

打包 HAP

flutter build openharmony

路径：build/openharmony/outputs/hap/release/

---

七、项目效果展示

1. 启动无兼容报错
2. 任务添加、删除、清空正常
3. 应用重启数据不丢失
4. 完美运行在鸿蒙 6.0+ 设备

---

八、常见问题解决

1. 不支持当前 API 版本：修改 minSdkVersion: 20
2. 设备不显示：重新执行 flutter config --enable-openharmony
3. 存储失效：升级三方库与 Flutter 版本
4. 安装失败：开启调试、信任电脑

---

九、总结

本文围绕 Flutter + 三方库 + 鸿蒙 三大核心，完成任务清单项目开发与适配。
Flutter 已原生支持鸿蒙最新系统，三方库可直接使用，一套代码多端运行。
项目可直接用于学习、毕业设计、小型开发，结构完整、可直接运行。

---