欢迎加入开源鸿蒙跨平台社区： https://openharmonycrossplatform.csdn.net

前言：跨生态开发的新机遇

在移动开发领域，我们总是面临着选择与适配。今天，你的Flutter应用在Android和iOS上跑得正欢，明天可能就需要考虑一个新的平台：HarmonyOS（鸿蒙）。这不是一道选答题，而是很多团队正在面对的现实。

Flutter的优势很明确——写一套代码，就能在两个主要平台上运行，开发体验流畅。而鸿蒙代表的是下一个时代的互联生态，它不仅仅是手机系统，更着眼于未来全场景的体验。将现有的Flutter应用适配到鸿蒙，听起来像是一个“跨界”任务，但它本质上是一次有价值的技术拓展：让产品触达更多用户，也让技术栈覆盖更广。

不过，这条路走起来并不像听起来那么简单。Flutter和鸿蒙，从底层的架构到上层的工具链，都有着各自的设计逻辑。会遇到一些具体的问题：代码如何组织？原有的功能在鸿蒙上如何实现？那些平台特有的能力该怎么调用？更实际的是，从编译打包到上架部署，整个流程都需要重新摸索。
这篇文章想做的，就是把这些我们趟过的路、踩过的坑，清晰地摊开给你看。我们不会只停留在“怎么做”，还会聊到“为什么得这么做”，以及“如果出了问题该往哪想”。这更像是一份实战笔记，源自真实的项目经验，聚焦于那些真正卡住过我们的环节。

无论你是在为一个成熟产品寻找新的落地平台，还是从一开始就希望构建能面向多端的应用，这里的思路和解决方案都能提供直接的参考。理解了两套体系之间的异同，掌握了关键的衔接技术，不仅能完成这次迁移，更能积累起应对未来技术变化的能力。

混合工程结构深度解析

项目目录架构

当Flutter项目集成鸿蒙支持后，典型的项目结构会发生显著变化。以下是经过ohos_flutter插件初始化后的项目结构：

my_flutter_harmony_app/
├── lib/                          # Flutter业务代码（基本不变）
│   ├── main.dart                 # 应用入口
│   ├── home_page.dart           # 首页
│   └── utils/
│       └── platform_utils.dart  # 平台工具类
├── pubspec.yaml                  # Flutter依赖配置
├── ohos/                         # 鸿蒙原生层（核心适配区）
│   ├── entry/                    # 主模块
│   │   └── src/main/
│   │       ├── ets/              # ArkTS代码
│   │       │   ├── MainAbility/
│   │       │   │   ├── MainAbility.ts       # 主Ability
│   │       │   │   └── MainAbilityContext.ts
│   │       │   └── pages/
│   │       │       ├── Index.ets           # 主页面
│   │       │       └── Splash.ets          # 启动页
│   │       ├── resources/        # 鸿蒙资源文件
│   │       │   ├── base/
│   │       │   │   ├── element/  # 字符串等
│   │       │   │   ├── media/    # 图片资源
│   │       │   │   └── profile/  # 配置文件
│   │       │   └── en_US/        # 英文资源
│   │       └── config.json       # 应用核心配置
│   ├── ohos_test/               # 测试模块
│   ├── build-profile.json5      # 构建配置
│   └── oh-package.json5         # 鸿蒙依赖管理
└── README.md

目录

• 展示效果图片
• 功能代码实现
  • FlPieChart 组件实现
  • 主页面集成
• 开发中容易遇到的问题
• 总结开发中用到的技术点

展示效果图片

flutter 实时预览 效果展示

运行到鸿蒙虚拟设备中效果展示

功能代码实现

FlPieChart 组件实现

FlPieChart 是一个基于 fl_chart 库实现的饼图组件，具有以下特性：

• 支持自定义标题和数据
• 实现点击交互效果
• 包含图例说明
• 响应式布局设计

核心代码实现

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

class FlPieChart extends StatefulWidget {
  final String title;
  final List<Map<String, dynamic>> data;
  final double? width;
  final double? height;

  const FlPieChart({
    Key? key,
    required this.title,
    required this.data,
    this.width,
    this.height,
  }) : super(key: key);

  @override
  State<FlPieChart> createState() => _FlPieChartState();
}

class _FlPieChartState extends State<FlPieChart> {
  int? _touchedIndex;
  String _clickInfo = '';

  // 颜色列表
  final List<Color> colors = [
    Colors.blue,
    Colors.green,
    Colors.orange,
    Colors.purple,
    Colors.red,
    Colors.yellow,
    Colors.teal,
    Colors.pink,
  ];

  void _onChartTap(PieTouchResponse? response) {
    if (response != null && response.touchedSection != null) {
      setState(() {
        _touchedIndex = response.touchedSection!.touchedSectionIndex;
        final dataItem = widget.data[_touchedIndex!];
        _clickInfo = '点击了: ${dataItem['name']} (${dataItem['value']})';
      });
      // 显示点击信息提示
      ScaffoldMessenger.of(context).showSnackBar(
        SnackBar(
          content: Text('${widget.data[_touchedIndex!]['name']}: ${widget.data[_touchedIndex!]['value']}'),
          duration: const Duration(seconds: 1),
        ),
      );
    }
  }

  @override
  Widget build(BuildContext context) {
    return Container(
      width: widget.width ?? double.infinity,
      height: widget.height ?? 400,
      margin: const EdgeInsets.all(16),
      padding: const EdgeInsets.all(16),
      decoration: BoxDecoration(
        borderRadius: BorderRadius.circular(8),
        color: Colors.white,
        boxShadow: [
          BoxShadow(
            color: Colors.grey.withOpacity(0.2),
            spreadRadius: 1,
            blurRadius: 3,
            offset: const Offset(0, 1),
          ),
        ],
      ),
      child: Column(
        crossAxisAlignment: CrossAxisAlignment.start,
        children: [
          Text(
            widget.title,
            style: const TextStyle(
              fontSize: 18,
              fontWeight: FontWeight.bold,
              color: Colors.black87,
            ),
          ),
          const SizedBox(height: 16),
          Expanded(
            child: Row(
              children: [
                // 饼图
                Expanded(
                  child: PieChart(
                    PieChartData(
                      pieTouchData: PieTouchData(
                        touchCallback: (event, response) => _onChartTap(response),
                      ),
                      borderData: FlBorderData(
                        show: false,
                      ),
                      sectionsSpace: 0,
                      centerSpaceRadius: 60,
                      sections: widget.data.asMap().entries.map((entry) {
                        final index = entry.key;
                        final data = entry.value;
                        final isTouched = index == _touchedIndex;
                        final radius = isTouched ? 100.0 : 80.0;
                        
                        return PieChartSectionData(
                          value: data['value'] as double? ?? (data['value'] as int).toDouble(),
                          title: data['name'] as String,
                          color: colors[index % colors.length],
                          radius: radius,
                          titleStyle: TextStyle(
                            fontSize: isTouched ? 14 : 12,
                            fontWeight: FontWeight.bold,
                            color: Colors.white,
                          ),
                        );
                      }).toList(),
                    ),
                  ),
                ),
                // 图例
                Container(
                  width: 100,
                  child: ListView.builder(
                    itemCount: widget.data.length,
                    itemBuilder: (context, index) {
                      final data = widget.data[index];
                      return Padding(
                        padding: const EdgeInsets.symmetric(vertical: 4),
                        child: Row(
                          children: [
                            Container(
                              width: 12,
                              height: 12,
                              decoration: BoxDecoration(
                                color: colors[index % colors.length],
                                shape: BoxShape.circle,
                              ),
                            ),
                            const SizedBox(width: 8),
                            Expanded(
                              child: Text(
                                data['name'] as String,
                                style: const TextStyle(
                                  fontSize: 12,
                                  color: Colors.black87,
                                ),
                                overflow: TextOverflow.ellipsis,
                              ),
                            ),
                          ],
                        ),
                      );
                    },
                  ),
                ),
              ],
            ),
          ),
          if (_clickInfo.isNotEmpty)
            Padding(
              padding: const EdgeInsets.only(top: 12),
              child: Text(
                _clickInfo,
                style: const TextStyle(
                  fontSize: 14,
                  color: Colors.grey,
                ),
              ),
            ),
        ],
      ),
    );
  }
}

组件参数说明

参数	类型	必填	描述
title	String	是	饼图标题
data	List<Map<String, dynamic>>	是	饼图数据，每个元素包含 name 和 value 字段
width	double?	否	组件宽度，默认充满父容器
height	double?	否	组件高度，默认 400

使用方法

FlPieChart(
  title: '访问来源分析',
  data: [
    {'value': 335, 'name': '直接访问'},
    {'value': 310, 'name': '邮件营销'},
    {'value': 234, 'name': '联盟广告'},
    {'value': 135, 'name': '视频广告'},
    {'value': 1548, 'name': '搜索引擎'}
  ],
)

主页面集成

主页面使用 MyHomePage 组件实现，集成了两个 FlPieChart 实例，分别展示访问来源分析和产品销售分布数据。

核心代码实现

import 'package:flutter/material.dart';
import 'package:aa/widgets/fl_pie_chart.dart';

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

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

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Flutter for openHarmony',
      theme: ThemeData(
        colorScheme: ColorScheme.fromSeed(seedColor: Colors.deepPurple),
        useMaterial3: true,
      ),
      debugShowCheckedModeBanner: false,
      home: const MyHomePage(title: 'Flutter for openHarmony'),
    );
  }
}

class MyHomePage extends StatefulWidget {
  const MyHomePage({super.key, required this.title});

  final String title;

  @override
  State<MyHomePage> createState() => _MyHomePageState();
}

class _MyHomePageState extends State<MyHomePage> {
  // 饼图数据
  final List<Map<String, dynamic>> pieData1 = [
    {'value': 335, 'name': '直接访问'},
    {'value': 310, 'name': '邮件营销'},
    {'value': 234, 'name': '联盟广告'},
    {'value': 135, 'name': '视频广告'},
    {'value': 1548, 'name': '搜索引擎'}
  ];

  final List<Map<String, dynamic>> pieData2 = [
    {'value': 120, 'name': 'A产品'},
    {'value': 200, 'name': 'B产品'},
    {'value': 150, 'name': 'C产品'},
    {'value': 80, 'name': 'D产品'},
    {'value': 70, 'name': 'E产品'}
  ];

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text(widget.title),
      ),
      body: SingleChildScrollView(
        padding: const EdgeInsets.all(16),
        child: Column(
          crossAxisAlignment: CrossAxisAlignment.center,
          children: <Widget>[
            const SizedBox(height: 20),
            // 第一个饼图
            FlPieChart(
              title: '访问来源分析',
              data: pieData1,
            ),
            const SizedBox(height: 40),
            // 第二个饼图
            FlPieChart(
              title: '产品销售分布',
              data: pieData2,
            ),
            const SizedBox(height: 40),
            const Text(
              '交互说明：点击饼图扇区查看详细信息',
              style: TextStyle(
                fontSize: 16,
                color: Colors.grey,
              ),
            ),
            const SizedBox(height: 40),
          ],
        ),
      ),
    );
  }
}

开发中容易遇到的问题

1. WebView 依赖问题

   • 问题：初始使用 flutter_echarts 库时，在 OpenHarmony 平台上遇到 WebViewPlatform 初始化失败的错误
   • 原因：flutter_echarts 库依赖 WebView 实现图表渲染，而 OpenHarmony 平台对 WebView 的支持不完善
   • 解决方案：改用纯 Flutter 实现的 fl_chart 库，避免 WebView 依赖

2. fl_chart API 调用问题

   • 问题：使用 fl_chart 库时，PieTouchData 的 touchCallback 方法签名与预期不符
   • 原因：不同版本的 fl_chart 库 API 可能存在差异
   • 解决方案：使用适配的回调方式，通过匿名函数转换参数格式

3. 数据格式问题

   • 问题：饼图数据中的 value 字段类型需要为 double
   • 原因：fl_chart 库的 PieChartSectionData.value 参数要求为 double 类型
   • 解决方案：在构建 PieChartSectionData 时，对 int 类型的 value 进行类型转换

4. 布局适配问题

   • 问题：在不同屏幕尺寸下，饼图和图例的布局可能出现异常
   • 原因：固定宽度的图例可能在小屏幕上显示不全
   • 解决方案：使用 Expanded 组件和响应式布局，确保在不同屏幕尺寸下的良好显示效果

总结开发中用到的技术点

1. Flutter 状态管理

   • 使用 StatefulWidget 和 setState 管理组件状态，实现饼图点击交互效果
   • 通过状态变量 _touchedIndex 跟踪当前点击的饼图扇区

2. Flutter 布局系统

   • 使用 Container、Column、Row、Expanded 等布局组件构建响应式界面
   • 运用 BoxDecoration 实现卡片阴影效果，提升视觉体验

3. fl_chart 图表库

   • 基于 fl_chart 库实现饼图渲染
   • 配置 PieChartData、PieChartSectionData 等参数实现自定义饼图效果
   • 使用 PieTouchData 实现饼图点击交互

4. 数据处理

   • 使用 List<Map<String, dynamic>> 存储和管理饼图数据
   • 通过 asMap().entries.map() 方法转换数据格式，适配图表库要求

5. 用户交互

   • 实现饼图点击事件处理，显示详细信息
   • 使用 ScaffoldMessenger 显示 SnackBar 提示信息

6. 代码组织

   • 采用组件化开发方式，将饼图封装为独立的 FlPieChart 组件
   • 分离业务逻辑和 UI 展示，提高代码可维护性

7. 跨平台适配

   • 选择跨平台兼容性好的 fl_chart 库，避免平台特定依赖
   • 确保代码在 Flutter 支持的所有平台（包括 OpenHarmony）上正常运行

欢迎加入开源鸿蒙跨平台社区： https://openharmonycrossplatform.csdn.net