Flutter 三方库与鸿蒙开发入门实战教程

欢迎加入开源鸿蒙PC社区（https://harmonypc.csdn.net/）

Flutter 三方库与鸿蒙开发入门实战教程

一、教程概述

本教程面向零基础开发者，全程以实战为核心，手把手带领开发者完成从 Flutter 开发环境搭建、常用三方库集成，到鸿蒙系统适配、应用打包运行的完整流程。教程步骤详细、代码可直接复制使用，跟随操作即可完成一个可在鸿蒙设备上运行、具备网络请求和状态管理功能的 Flutter 应用，快速入门 Flutter 与鸿蒙的跨平台开发。

二、环境准备（前置必做步骤）

2.1 安装 Flutter 开发环境

  1. 下载 Flutter SDK：访问 Flutter 官方下载页面，根据自身操作系统（Windows/Mac/Linux）选择对应版本的 SDK，下载后解压至无中文、无空格、无特殊字符的路径（例如 Windows 路径：D:\flutter\，Mac 路径：/Users/用户名/flutter/）。

  2. 配置环境变量：

  • Windows 系统：右键点击“此电脑”→“属性”→“高级系统设置”→“环境变量”，在“系统变量”中找到“Path”，点击“编辑”，添加 Flutter SDK 的 bin 目录路径（例如 D:\flutter\bin），点击确定保存。

  • Mac/Linux 系统：打开终端，执行命令 export PATH="$PATH:/你的flutter路径/flutter/bin"，为确保永久生效，需将该命令写入 .bashrc（Mac 旧版本）或 .zshrc（Mac 新版本、Linux）文件，执行 vim ~/.zshrc 打开文件，粘贴命令后保存退出，再执行 source ~/.zshrc 生效。

  1. 验证安装：打开新的终端，执行命令 flutter doctor，终端会检测当前开发环境的缺失依赖（如 Android Studio、Xcode、Git 等），按照提示逐一安装缺失组件，直至所有必要项显示“✓”（可选项可忽略）。

2.2 安装鸿蒙开发工具（DevEco Studio）

  1. 下载 DevEco Studio：访问 鸿蒙开发者官网，下载最新版本的 DevEco Studio，根据操作系统选择对应安装包（Windows/Mac）。

  2. 安装工具：运行安装包，按照向导完成安装，过程中可默认勾选“自动配置鸿蒙 SDK”，若未勾选，后续需手动配置。

  3. 配置鸿蒙 SDK：打开 DevEco Studio，进入“Settings”（Windows）/“DevEco Studio”（Mac）→“Appearance & Behavior”→“System Settings”→“HarmonyOS SDK”，勾选 API 10 及以上版本的 SDK（推荐 API 10，兼容性最佳），点击“Apply”完成安装配置。

2.3 配置 Flutter 鸿蒙适配环境

  1. 开启 Flutter 鸿蒙支持：打开终端，执行以下命令，启用 Flutter 对鸿蒙系统的开发支持：
flutter config --enable-harmonyos
  1. 验证适配配置：执行命令 flutter doctor -v，查看输出结果，确保“HarmonyOS toolchain”相关项显示“✓”，若显示异常，检查 DevEco Studio 安装路径是否正确，或重新配置鸿蒙 SDK 环境变量。

三、创建基础 Flutter 项目

3.1 新建 Flutter 项目

  1. 打开终端，切换至想要存放项目的目录（例如 Windows：cd D:\projects\，Mac：cd ~/projects/）。

  2. 执行以下命令，创建名为“harmony_flutter_demo”的 Flutter 项目（项目名可自定义，建议小写，用下划线分隔）：

flutter create harmony_flutter_demo
  1. 项目创建完成后，切换至项目目录：
cd harmony_flutter_demo

3.2 运行基础项目验证环境

  1. 启动鸿蒙设备或模拟器：

  • 真实设备：开启鸿蒙手机/平板的开发者模式（设置→关于手机→连续点击版本号 7 次），开启“USB 调试”，用 USB 数据线连接电脑，确保电脑能识别设备。

  • 模拟器：打开 DevEco Studio，点击顶部“Tools”→“Device Manager”，创建鸿蒙模拟器（选择 API 10 版本，按需选择设备型号），启动模拟器。

  1. 终端执行以下命令，将基础 Flutter 项目运行到鸿蒙设备/模拟器上：
flutter run -d harmonyos
  1. 验证成功：若设备/模拟器上成功显示 Flutter 默认的计数器页面（点击“+”按钮可增加计数），说明基础环境配置完成，可进入下一步操作。

四、集成常用三方库（实战核心）

本教程以最常用的“网络请求库（Dio）”和“状态管理库（Provider）”为例，讲解三方库的集成与使用，后续可根据需求扩展其他库。

4.1 添加三方库依赖

  1. 打开项目根目录下的 pubspec.yaml 文件（该文件用于管理 Flutter 项目的依赖）。

  2. 在 dependencies 节点下，添加 Dio 和 Provider 的依赖（版本可参考 pub.dev 最新版本，本教程使用稳定版本）：

dependencies:

flutter:

sdk: flutter

dio: ^5.4.0          # 网络请求库，用于发送 HTTP 请求

provider: ^6.1.1     # 状态管理库，用于管理页面数据和状态
  1. 保存 pubspec.yaml 文件，终端执行以下命令，下载并安装依赖：
flutter pub get
  1. 依赖安装成功：终端显示“Process finished with exit code 0”，无报错即说明依赖安装完成。

4.2 实现 Dio 网络请求功能

  1. 在项目 lib/ 目录下，新建 services 文件夹（用于存放服务类代码），在该文件夹下新建 api_service.dart 文件。

  2. 在 api_service.dart 中编写网络请求逻辑，示例为获取公开接口数据（接口可直接访问，无需注册）：

import 'package:dio/dio.dart';



class ApiService {

// 初始化 Dio 实例

final Dio _dio = Dio();



// 示例：获取公开接口的单条数据（可根据需求修改接口地址和请求方式）

Future<Map<String, dynamic>> fetchData() async {

try {

// 发送 GET 请求，接口地址为公开测试接口

final response = await _dio.get('https://jsonplaceholder.typicode.com/todos/1');

// 返回请求到的 JSON 数据（Map 类型）

return response.data;

} catch (e) {

// 捕获请求异常，抛出错误提示

throw Exception('网络请求失败，请检查网络连接或接口地址：$e');

}

}

}

4.3 实现 Provider 状态管理

  1. 在 lib/ 目录下，新建 providers 文件夹（用于存放状态管理类代码），在该文件夹下新建 data_provider.dart 文件。

  2. 在 data_provider.dart 中编写状态管理逻辑，关联上一步的网络请求服务：

import 'package:flutter/foundation.dart';

import '../services/api_service.dart';



// 继承 ChangeNotifier，用于通知页面状态变化

class DataProvider extends ChangeNotifier {

// 实例化网络请求服务

final ApiService _apiService = ApiService();



// 存储请求到的数据（可为 null）

Map<String, dynamic>? _data;

// 加载状态（true：加载中，false：加载完成/未加载）

bool _isLoading = false;



// 提供外部访问数据的 getter 方法（禁止外部直接修改数据）

Map<String, dynamic>? get data => _data;

bool get isLoading => _isLoading;



// 加载数据的方法（供页面调用）

Future<void> loadData() async {

// 开始加载，更新加载状态并通知页面

_isLoading = true;

notifyListeners();



try {

// 调用网络请求方法，获取数据

_data = await _apiService.fetchData();

} catch (e) {

// 打印错误信息（仅调试模式显示）

if (kDebugMode) {

print('数据加载失败：$e');

}

} finally {

// 加载完成，更新加载状态并通知页面

_isLoading = false;

notifyListeners();

}

}

}

4.4 在页面中使用三方库功能

修改项目根目录 lib/main.dart 文件，集成状态管理和网络请求，实现一个简单的页面，点击按钮加载数据并显示：

import 'package:flutter/material.dart';

import 'package:provider/provider.dart';

import 'providers/data_provider.dart';



void main() {

// 启动应用，通过 ChangeNotifierProvider 注入状态管理

runApp(

ChangeNotifierProvider(

create: (context) => DataProvider(), // 实例化 DataProvider

child: const MyApp(),

),

);

}



// 应用根组件

class MyApp extends StatelessWidget {

const MyApp({super.key});



@override

Widget build(BuildContext context) {

return MaterialApp(

title: 'Flutter 鸿蒙三方库实战',

theme: ThemeData(

primarySwatch: Colors.blue, // 应用主题色

visualDensity: VisualDensity.adaptivePlatformDensity,

),

home: const HomePage(), // 首页

);

}

}



// 首页组件

class HomePage extends StatelessWidget {

const HomePage({super.key});



@override

Widget build(BuildContext context) {

// 通过 Consumer 监听 DataProvider 的状态变化

return Consumer<DataProvider>(

builder: (context, provider, child) {

return Scaffold(

appBar: AppBar(

title: const Text('Flutter + 鸿蒙 + 三方库'),

),

body: Center(

child: provider.isLoading

? // 加载中：显示圆形加载框

const CircularProgressIndicator()

: // 加载完成：显示数据或提示

Column(

mainAxisAlignment: MainAxisAlignment.center,

children: [

// 显示请求到的数据（取 title 字段，无数据时显示提示）

Text(

'接口返回数据：${provider.data?['title'] ?? '暂无数据，请点击按钮加载'}',

textAlign: TextAlign.center,

style: const TextStyle(fontSize: 16),

),

const SizedBox(height: 30), // 间距

// 点击按钮加载数据

ElevatedButton(

onPressed: () => provider.loadData(),

child: const Text('加载数据'),

),

],

),

),

);

},

);

}

}

五、鸿蒙系统适配与打包运行

Flutter 项目集成三方库后，需进行简单的鸿蒙适配，确保应用能在鸿蒙设备上正常运行并打包生成安装包。

5.1 配置鸿蒙项目基本信息

  1. 打开项目根目录下的 harmonyos 文件夹（创建 Flutter 项目时自动生成，用于存放鸿蒙相关配置）。

  2. 打开 harmonyos/oh-package.json5 文件，配置应用的包名、版本、描述等信息（包名需唯一，可自定义）：

{

"name": "com.example.harmony_flutter_demo", // 应用包名（唯一标识）

"version": "1.0.0", // 应用版本号

"description": "Flutter 集成三方库并适配鸿蒙系统的实战 Demo", // 应用描述

"main": "index.ets", // 鸿蒙入口文件

"author": "", // 开发者信息（可选）

"license": "Apache-2.0", // 许可证（默认即可）

"dependencies": {} // 鸿蒙相关依赖（暂无）

}

5.2 适配鸿蒙应用权限（以网络权限为例）

由于项目中使用了网络请求，需在鸿蒙配置中声明网络权限，否则应用无法正常联网。

  1. 打开 harmonyos/entry/src/main/module.json5 文件。

  2. 在 "module" 节点下，添加 "requestPermissions" 数组，声明网络权限：

{

"module": {

"package": "com.example.harmony_flutter_demo",

"name": ".entry",

"mainAbility": "EntryAbility",

"deviceTypes": ["phone", "tablet"],

// 新增：权限声明

"requestPermissions": [

{

"name": "ohos.permission.INTERNET", // 网络权限

"reason": "应用需要联网获取数据", // 权限申请原因（用户可见）

"usedScene": {

"abilities": ["EntryAbility"], // 关联的能力

"when": "inuse" // 权限使用场景（inuse：应用使用时）

}

}

]

}

}

5.3 在鸿蒙设备上运行应用

  1. 确保鸿蒙设备/模拟器已连接并正常识别（终端执行 flutter devices 可查看已连接设备）。

  2. 终端执行以下命令，构建并运行应用：

flutter run -d harmonyos
  1. 运行成功：等待构建完成（首次构建时间较长，耐心等待），设备/模拟器上会自动安装并启动应用，点击“加载数据”按钮，可成功获取并显示接口数据，说明三方库集成和鸿蒙适配均正常。

5.4 打包生成鸿蒙应用安装包（HAP）

应用开发完成后，可打包生成鸿蒙的 HAP 安装包，用于安装到其他鸿蒙设备或发布。

  1. 终端切换至 Flutter 项目根目录，执行以下命令，打包鸿蒙应用：
flutter build harmonyos

  1. 查找安装包：打包完成后，在项目根目录的 build/harmonyos/outputs/hap/ 目录下，可找到生成的 entry-debug.hap（调试版）或 entry-release.hap（发布版）文件。

  2. 安装测试：将 HAP 文件复制到鸿蒙设备中，点击文件即可完成安装，安装后可正常运行应用。

六、常见问题与解决方案

| 问题场景 | 解决方案 |

| — | — |

| 执行 flutter doctor 显示“HarmonyOS toolchain not found” | 1. 检查 DevEco Studio 是否安装成功；2. 配置环境变量 HUAWEI_SDK_ROOT，指向鸿蒙 SDK 目录（DevEco Studio 安装目录下的 sdk 文件夹）；3. 重新执行 flutter config --enable-harmonyos 命令。 |

| 三方库集成后，运行报错“Could not find package xxx” | 1. 检查 pubspec.yaml 中依赖的版本是否正确；2. 重新执行 flutter pub get 命令；3. 关闭 IDE 重新打开项目，清除缓存（File → Invalidate Caches…）。 |

| 应用运行后，点击“加载数据”无反应，控制台报错“无网络权限” | 检查 module.json5 文件中是否添加了 ohos.permission.INTERNET 权限，添加后重新运行应用；若仍有问题，重启设备/模拟器重试。 |

| 打包 HAP 文件失败，提示“构建异常” | 1. 检查鸿蒙 SDK 版本是否为 API 10 及以上；2. 确保项目中无语法错误，先执行 flutter run -d harmonyos 验证应用可正常运行，再进行打包；3. 清理项目缓存，执行 flutter clean 后重新打包。 |

七、拓展学习方向

  1. 集成更多鸿蒙适配的三方库：例如本地存储库 shared_preferences（用于存储简单数据）、图片加载库 cached_network_image（用于加载网络图片）、UI 组件库 flutter_screenutil（用于屏幕适配）等，可在 pub.dev 搜索“harmonyos”筛选适配鸿蒙的库。

  2. 学习 Flutter 与鸿蒙原生交互：例如调用鸿蒙原生的相机、相册、传感器等能力，实现更丰富的功能，可参考鸿蒙官方文档中的“Flutter 与鸿蒙原生交互”章节。

  3. 多端适配实战：基于当前项目，扩展适配 Android、iOS 系统，实现一套代码多端运行，掌握跨平台开发的核心技巧。

  4. 发布鸿蒙应用：学习鸿蒙应用的发布流程，注册鸿蒙开发者账号，完成应用备案、签名、发布等操作，将自己的应用上线到鸿蒙应用市场。

八、教程总结

通过本教程的学习和实战，你已掌握以下核心技能：

  • Flutter 开发环境、鸿蒙开发环境的完整搭建，以及 Flutter 与鸿蒙的适配配置；

  • Flutter 项目的创建、运行，以及常用三方库（Dio、Provider）的集成与使用；

  • Flutter 应用的鸿蒙系统适配、权限配置，以及鸿蒙安装包（HAP）的打包与安装；

  • 常见问题的排查与解决方法，为后续开发打下基础。

本教程为入门实战内容，后续可基于当前项目，不断拓展功能、集成更多三方库，深入学习 Flutter 与鸿蒙开发的进阶知识，打造更完整、更实用的跨平台应用。

# flutter # 鸿蒙
Logo
人工智能6S服务平台

作为“人工智能6S店”的官方数字引擎，为AI开发者与企业提供一个覆盖软硬件全栈、一站式门户。

更多推荐

cover

HarmonyOS 5.0车机应用开发实战：基于方舟引擎的智能座舱多模态交互系统

avatar 人工智能6S服务平台

Flutter 三方库在鸿蒙应用开发中的基础项目实践

在lib/bloc目录新建@override// 加载本地待办列表事件// 添加待办事项事件@override// 切换待办完成状态事件@override// 删除待办事项事件@override在lib/bloc目录新建@override// 初始状态// 加载中状态// 加载完成状态（携带待办列表）@override// 错误状态@overrideFlutter三方库鸿蒙适配。

avatar 人工智能6S服务平台

Flutter鸿蒙三方库适配实战指南

本文分享了Flutter应用在鸿蒙系统上的三方库适配实战经验。针对鸿蒙生态的特殊性，提出了"可用、可稳、可维护"的适配目标，详细介绍了从项目准备到代码改造的完整流程。文章重点分析了常见问题解决方案，对比了不同功能库在鸿蒙上的表现，并推荐了开发工具链。通过实际案例展示了如何将普通Flutter项目改造为兼容鸿蒙设备的高质量应用，为开发者提供了实用的技术指导。

avatar 人工智能6S服务平台