标题
Flutter + 三方库在鸿蒙开发中的实践入门教程
一、前言
作为一名鸿蒙开发新手，跨端开发是提升开发效率、复用业务逻辑的重要方向。Flutter 作为热门跨端框架，搭配丰富的三方库生态，能快速在鸿蒙平台实现功能开发。本教程将以 「待办事项 App」 为案例，手把手教你完成 Flutter 鸿蒙项目搭建、三方库集成、功能开发与运行验证，帮你快速上手 Flutter 鸿蒙开发。
二、环境准备
2.1 基础环境要求
表格
工具 / 依赖 版本要求 说明
Flutter 3.10+ 需开启鸿蒙适配支持
OpenHarmony SDK 4.0+ 鸿蒙开发基础环境
DevEco Studio 4.0+ 鸿蒙应用调试工具
VS Code/Android Studio 任意 Flutter 开发 IDE
2.2 环境配置步骤
安装 Flutter 并启用鸿蒙支持
bash
运行

检查 Flutter 环境

flutter doctor

开启鸿蒙平台支持（Flutter 3.10+ 需手动开启）

flutter config --enable-harmonyos
配置鸿蒙开发环境
安装 DevEco Studio，配置 OpenHarmony SDK
配置鸿蒙设备调试权限，开启开发者模式与 USB 调试
验证环境
bash
运行

查看 Flutter 支持的平台，需包含 harmonyos

flutter devices
三、项目创建与基础配置
3.1 创建 Flutter 鸿蒙项目
bash
运行

创建 Flutter 项目，指定包名（与鸿蒙配置一致）

flutter create --org com.example.todo todo_harmony
cd todo_harmony
3.2 开启鸿蒙平台适配
进入项目根目录，修改 pubspec.yaml，开启鸿蒙平台支持：
yaml

pubspec.yaml

name: todo_harmony
description: Flutter + 三方库实现的鸿蒙待办App
version: 1.0.0+1

environment:
sdk: ‘>=3.0.0 <4.0.0’

dependencies:
flutter:
sdk: flutter

后续集成的三方库会添加在这里

执行命令生成鸿蒙平台目录：
bash
运行
flutter create . --platforms harmonyos
四、三方库选型与集成
本案例选择 sqflite_common_ffi（轻量本地数据库）和 provider（状态管理）两个常用三方库，实现待办数据的本地存储与状态同步。
4.1 安装三方库
修改 pubspec.yaml，添加依赖：
yaml
dependencies:
flutter:
sdk: flutter
provider: ^6.1.1 # 状态管理库，实现数据与UI同步
sqflite_common_ffi: ^2.3.0 # 适配鸿蒙的SQLite本地数据库
path_provider: ^2.1.1 # 获取文件路径，用于数据库存储
执行安装命令：
bash
运行
flutter pub get
五、项目核心代码实现（含详细注释）
5.1 数据库工具类实现（db_helper.dart）
负责待办数据的增删改查，封装数据库操作逻辑。
dart
import ‘dart:io’;
import ‘package:path/path.dart’;
import ‘package:sqflite_common_ffi/sqflite_ffi.dart’;
import ‘package:path_provider/path_provider.dart’;

// 数据库工具类：封装SQLite数据库的初始化与CRUD操作
class DbHelper {
// 单例模式，保证全局只有一个数据库实例
static final DbHelper instance = DbHelper._privateConstructor();
DbHelper._privateConstructor();
static Database? _database;

// 获取数据库实例，若未初始化则先初始化
Future get database async {
if (_database != null) return _database!;
_database = await _initDatabase();
return _database!;
}

// 初始化数据库
Future _initDatabase() async {
// 初始化sqflite_ffi（适配鸿蒙平台）
sqfliteFfiInit();
// 设置数据库工厂为ffi工厂
databaseFactory = databaseFactoryFfi;

// 获取鸿蒙应用的文档目录（数据库文件存储路径）
Directory appDir = await getApplicationDocumentsDirectory();
String dbPath = join(appDir.path, 'todo.db');

// 打开/创建数据库，版本为1，执行建表语句
return await openDatabase(
  dbPath,
  version: 1,
  onCreate: (db, version) async {
    // 创建待办表：id（主键自增）、title（待办标题）、isCompleted（完成状态）、createTime（创建时间）
    await db.execute('''
      CREATE TABLE todo (
        id INTEGER PRIMARY KEY AUTOINCREMENT,
        title TEXT NOT NULL,
        isCompleted INTEGER NOT NULL DEFAULT 0,
        createTime TEXT NOT NULL
      )
    ''');
  },
);

}

// 新增待办事项
Future insertTodo(Map<String, dynamic> todo) async {
Database db = await instance.database;
// 插入数据，返回自增的id
return await db.insert(‘todo’, todo);
}

// 查询所有待办事项
Future<List<Map<String, dynamic>>> getTodos() async {
Database db = await instance.database;
// 按创建时间倒序排列，最新的待办显示在最前面
return await db.query(‘todo’, orderBy: ‘createTime DESC’);
}

// 更新待办完成状态
Future updateTodoStatus(int id, bool isCompleted) async {
Database db = await instance.database;
// 更新指定id的待办状态，0为未完成，1为已完成
return await db.update(
‘todo’,
{‘isCompleted’: isCompleted ? 1 : 0},
where: ‘id = ?’,
whereArgs: [id],
);
}

// 删除待办事项
Future deleteTodo(int id) async {
Database db = await instance.database;
// 删除指定id的待办数据
return await db.delete(‘todo’, where: ‘id = ?’, whereArgs: [id]);
}
}
5.2 状态管理类实现（todo_provider.dart）
使用 provider 管理待办数据状态，实现数据变化时 UI 自动更新。
dart
import ‘package:flutter/foundation.dart’;
import ‘db_helper.dart’;

// 待办数据模型类
class Todo {
final int id;
final String title;
final bool isCompleted;
final String createTime;

Todo({
required this.id,
required this.title,
required this.isCompleted,
required this.createTime,
});

// 从数据库Map数据转换为Todo对象
factory Todo.fromMap(Map<String, dynamic> map) {
return Todo(
id: map[‘id’],
title: map[‘title’],
isCompleted: map[‘isCompleted’] == 1,
createTime: map[‘createTime’],
);
}
}

// 状态管理类：继承ChangeNotifier，可通知UI更新
class TodoProvider extends ChangeNotifier {
List _todos = [];
List get todos => _todos;

// 初始化时加载本地所有待办数据
Future loadTodos() async {
List<Map<String, dynamic>> todoMaps = await DbHelper.instance.getTodos();
// 将数据库Map数据转换为Todo对象列表
_todos = todoMaps.map((map) => Todo.fromMap(map)).toList();
// 通知UI刷新
notifyListeners();
}

// 添加新待办事项
Future addTodo(String title) async {
// 构造待办数据，包含当前时间作为创建时间
Map<String, dynamic> newTodo = {
‘title’: title,
‘isCompleted’: 0,
‘createTime’: DateTime.now().toIso8601String(),
};
// 插入数据库并获取自增id
int id = await DbHelper.instance.insertTodo(newTodo);
// 更新本地状态列表
_todos.insert(0, Todo(
id: id,
title: title,
isCompleted: false,
createTime: newTodo[‘createTime’],
));
notifyListeners();
}

// 切换待办完成状态
Future toggleTodoStatus(int id) async {
// 找到对应id的待办对象
Todo todo = _todos.firstWhere((t) => t.id == id);
bool newStatus = !todo.isCompleted;
// 更新数据库状态
await DbHelper.instance.updateTodoStatus(id, newStatus);
// 更新本地状态列表
int index = _todos.indexWhere((t) => t.id == id);
_todos[index] = Todo(
id: id,
title: todo.title,
isCompleted: newStatus,
createTime: todo.createTime,
);
notifyListeners();
}

// 删除待办事项
Future removeTodo(int id) async {
// 删除数据库数据
await DbHelper.instance.deleteTodo(id);
// 从本地状态列表移除
_todos.removeWhere((t) => t.id == id);
notifyListeners();
}
}
5.3 主界面实现（main.dart）
实现待办列表 UI、新增待办输入框，绑定状态管理。
dart
import ‘package:flutter/material.dart’;
import ‘package:provider/provider.dart’;
import ‘todo_provider.dart’;

void main() {
runApp(
// 全局注册TodoProvider，所有子组件均可访问状态
ChangeNotifierProvider(
create: (context) => TodoProvider(),
child: const MyApp(),
),
);
}

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

@override
Widget build(BuildContext context) {
return MaterialApp(
title: ‘鸿蒙Flutter待办App’,
theme: ThemeData(primarySwatch: Colors.blue),
home: const TodoHomePage(),
);
}
}

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

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

class _TodoHomePageState extends State {
final TextEditingController _controller = TextEditingController();

@override
void initState() {
super.initState();
// 页面初始化时加载本地待办数据
WidgetsBinding.instance.addPostFrameCallback((_) {
Provider.of(context, listen: false).loadTodos();
});
}

@override
Widget build(BuildContext context) {
return Scaffold(
appBar: AppBar(title: const Text(‘鸿蒙Flutter待办事项’)),
body: Column(
children: [
// 新增待办输入框区域
Padding(
padding: const EdgeInsets.all(16.0),
child: Row(
children: [
Expanded(
child: TextField(
controller: _controller,
decoration: const InputDecoration(
hintText: ‘输入新的待办事项’,
border: OutlineInputBorder(),
),
),
),
const SizedBox(width: 8),
ElevatedButton(
onPressed: () {
if (_controller.text.isNotEmpty) {
// 调用provider的addTodo方法添加待办
Provider.of(context, listen: false)
.addTodo(_controller.text);
// 清空输入框
_controller.clear();
}
},
child: const Text(‘添加’),
),
],
),
),
// 待办列表区域（监听provider状态变化自动刷新）
Expanded(
child: Consumer(
builder: (context, todoProvider, child) {
if (todoProvider.todos.isEmpty) {
return const Center(child: Text(‘暂无待办事项，添加一个吧！’));
}
return ListView.builder(
itemCount: todoProvider.todos.length,
itemBuilder: (context, index) {
Todo todo = todoProvider.todos[index];
return ListTile(
// 点击切换待办完成状态
onTap: () => todoProvider.toggleTodoStatus(todo.id),
// 长按删除待办
onLongPress: () => todoProvider.removeTodo(todo.id),
title: Text(
todo.title,
// 已完成的待办添加删除线
style: TextStyle(
decoration: todo.isCompleted
? TextDecoration.lineThrough
: null,
),
),
trailing: Icon(
todo.isCompleted
? Icons.check_circle
: Icons.circle_outlined,
color: todo.isCompleted ? Colors.green : Colors.grey,
),
);
},
);
},
),
),
],
),
);
}
}
六、鸿蒙平台适配与运行验证
6.1 鸿蒙平台权限配置
进入 harmonyos/entry/src/main/module.json5，添加数据库存储相关权限：
json
{
“module”: {
“requestPermissions”: [
{
“name”: “ohos.permission.READ_MEDIA”,
“reason”: “KaTeX parse error: Expected 'EOF', got '}' at position 170: … } }̲, { …string:permission_write_media_reason”,
“usedScene”: {
“abilities”: [
“.EntryAbility”
],
“when”: “inuse”
}
}
]
}
}
6.2 项目构建与运行
连接鸿蒙设备或启动 DevEco Studio 模拟器
执行构建命令：
bash
运行

构建鸿蒙平台安装包（hap包）

flutter build harmonyos
构建完成后，在 build/harmonyos/outputs/hap/ 目录找到 .hap 文件，通过 DevEco Studio 安装到设备
启动应用，验证功能：
新增待办事项，检查是否显示在列表
点击待办切换完成状态，检查 UI 是否同步更新
长按待办删除，检查列表是否移除对应项
重启应用，检查待办数据是否本地持久化保存
七、常见问题与解决
三方库在鸿蒙平台无法运行
检查三方库是否支持鸿蒙平台（优先选择带有 harmonyos 适配的库）
确保 sqflite_common_ffi 已替换原生 sqflite，原生库不支持鸿蒙
数据库文件无法创建
检查鸿蒙权限配置是否正确，是否添加了读写媒体权限
验证 path_provider 是否能正确获取应用文档目录
状态更新后 UI 不刷新
确认 ChangeNotifier 中修改数据后调用了 notifyListeners()
检查 Consumer 组件是否正确包裹了需要刷新的 UI
八、总结与拓展
本教程通过一个待办事项 App，完成了 Flutter 鸿蒙项目搭建、三方库集成、数据持久化与状态管理的完整流程。你可以在此基础上拓展更多功能：
集成 fluttertoast 实现操作提示
加入 shared_preferences 实现用户偏好设置
结合鸿蒙原生能力，实现通知提醒、文件分享等系统功能