欢迎加入开源鸿蒙跨平台社区： https://openharmonycrossplatform.csdn.net
Flutter + 三方库 + 鸿蒙：从零开始的跨端实战教程

本教程将带你从零搭建一个 Flutter 项目，引入常用的三方库（网络请求 dio、状态管理 provider），并最终将应用运行在鸿蒙（HarmonyOS NEXT）设备上。通过详细的步骤，你可以亲手完成一次完整的跨端开发实践。

目录

1. 环境准备
2. 创建 Flutter 项目
3. 引入三方库
4. 编写示例代码
5. 配置鸿蒙支持
6. 运行到鸿蒙设备
7. 常见问题与解决

---

1. 环境准备

1.1 基础工具

· Flutter SDK（≥3.22.0）：官方下载
· DevEco Studio（≥5.0.0）：华为开发者联盟下载
· Node.js（用于鸿蒙工具链）
· Git（可选）

1.2 配置 Flutter 鸿蒙支持

目前 Flutter 官方尚未完全合入鸿蒙支持，但社区已提供方案。推荐使用 flutter-ohos 项目提供的工具链。

打开终端，执行以下命令添加鸿蒙支持：

# 克隆 flutter-ohos 工具（或使用已有 Flutter SDK 打补丁）
git clone https://gitee.com/openharmony-sig/flutter_ohos.git
cd flutter_ohos
./install.sh   # 自动配置 Flutter 环境，添加鸿蒙编译能力

若使用官方 Flutter SDK，需替换 engine 和 flutter 目录，具体参考 flutter_ohos 文档。

配置完成后，运行 flutter doctor 应能看到 HarmonyOS 相关选项。

---

2. 创建 Flutter 项目

在终端中创建一个新的 Flutter 项目：

flutter create my_harmony_app
cd my_harmony_app

此时生成的是标准 Android/iOS/Web 项目，接下来我们要添加鸿蒙支持。

---

3. 引入三方库

编辑 pubspec.yaml，在 dependencies 下添加：

dependencies:
  flutter:
    sdk: flutter
  dio: ^5.4.0          # 网络请求
  provider: ^6.1.1     # 状态管理

执行 flutter pub get 安装。

---

4. 编写示例代码

我们将实现一个简单的功能：点击按钮，从免费 API 获取一条随机笑话，并展示在界面上。同时使用 provider 管理状态。

4.1 创建 Model 和 Service

新建 lib/models/joke.dart：

class Joke {
  final String content;
  Joke({required this.content});
  factory Joke.fromJson(Map<String, dynamic> json) {
    return Joke(content: json['joke'] ?? '无笑话');
  }
}

新建 lib/services/joke_service.dart：

import 'package:dio/dio.dart';
import '../models/joke.dart';

class JokeService {
  final Dio _dio = Dio(BaseOptions(baseUrl: 'https://v2.jokeapi.dev/'));

  Future<Joke> fetchRandomJoke() async {
    final response = await _dio.get('joke/Any?type=single');
    if (response.statusCode == 200) {
      return Joke.fromJson(response.data);
    } else {
      throw Exception('获取笑话失败');
    }
  }
}

4.2 使用 Provider 管理状态

新建 lib/providers/joke_provider.dart：

import 'package:flutter/material.dart';
import '../services/joke_service.dart';
import '../models/joke.dart';

class JokeProvider extends ChangeNotifier {
  final JokeService _service = JokeService();
  Joke? _currentJoke;
  bool _isLoading = false;

  Joke? get currentJoke => _currentJoke;
  bool get isLoading => _isLoading;

  Future<void> fetchJoke() async {
    _isLoading = true;
    notifyListeners();
    try {
      _currentJoke = await _service.fetchRandomJoke();
    } catch (e) {
      _currentJoke = Joke(content: '加载失败：$e');
    } finally {
      _isLoading = false;
      notifyListeners();
    }
  }
}

4.3 编写 UI

替换 lib/main.dart：

import 'package:flutter/material.dart';
import 'package:provider/provider.dart';
import 'providers/joke_provider.dart';

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

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return ChangeNotifierProvider(
      create: (_) => JokeProvider(),
      child: MaterialApp(
        title: '鸿蒙笑话助手',
        theme: ThemeData(primarySwatch: Colors.blue),
        home: JokePage(),
      ),
    );
  }
}

class JokePage extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    final provider = Provider.of<JokeProvider>(context);
    return Scaffold(
      appBar: AppBar(title: Text('Flutter + 三方库 + 鸿蒙')),
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: [
            if (provider.isLoading)
              CircularProgressIndicator()
            else if (provider.currentJoke != null)
              Padding(
                padding: const EdgeInsets.all(20.0),
                child: Text(
                  provider.currentJoke!.content,
                  textAlign: TextAlign.center,
                  style: TextStyle(fontSize: 18),
                ),
              ),
            SizedBox(height: 30),
            ElevatedButton(
              onPressed: provider.isLoading ? null : () => provider.fetchJoke(),
              child: Text('点我获取笑话'),
            ),
          ],
        ),
      ),
    );
  }
}

至此，一个简单的 Flutter 应用已经完成，接下来将其适配鸿蒙。

---

5. 配置鸿蒙支持

5.1 添加鸿蒙平台目录

在项目根目录执行：

flutter create --platforms=ohos .

此命令会生成 ohos 文件夹，包含鸿蒙原生工程。

5.2 配置签名（如需真机调试）

在 DevEco Studio 中打开 ohos 目录，按照官方指引配置签名。简单调试可用模拟器，无需签名。

5.3 修改 Flutter 模块版本（可选）

打开 ohos/build-profile.json5，确保 compileSdkVersion 与你的鸿蒙 SDK 版本匹配（通常 5.0+）。

---

6. 运行到鸿蒙设备

6.1 使用命令行

连接鸿蒙设备（真机或模拟器），执行：

flutter run -d ohos

如果设备列表为空，请确保已启动模拟器或连接真机并开启 USB 调试。

6.2 使用 DevEco Studio

1. 用 DevEco Studio 打开项目根目录（不是 ohos 子目录）。
2. 等待项目同步完成，点击运行按钮（选择鸿蒙设备）。

首次运行会编译 Flutter 引擎和鸿蒙插件，可能需要几分钟。

成功运行后，你将看到应用界面，点击按钮即可通过网络请求获取笑话。

---

7. 常见问题与解决

Q1: 运行 flutter run -d ohos 提示找不到设备？

· 确保鸿蒙模拟器已启动，或真机已开启“开发者模式”和“USB调试”。
· 执行 hdc list targets（鸿蒙设备连接工具）检查设备是否识别。

Q2: 三方库在鸿蒙上编译失败？

部分原生插件可能未适配鸿蒙。本教程使用的 dio 和 provider 是纯 Dart 库，无需原生代码，因此完美兼容。如需使用原生插件，请查阅该插件是否提供鸿蒙支持。

Q3: 网络请求失败？

鸿蒙模拟器默认网络可能受限，可尝试使用真机调试，或在模拟器设置中启用网络。

Q4: 构建时提示 “ohos 目录不存在”？

确保已执行 flutter create --platforms=ohos . 生成鸿蒙工程。