欢迎加入开源鸿蒙跨平台社区： 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

目录

• 展示效果图片
• 功能代码实现
• 本次开发中容易遇到的问题
• 总结本次开发中用到的技术点

展示效果图片

flutter 实时预览 效果展示

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

功能代码实现

本次开发中，我们采用了组件化的开发方式，将待办事项清单功能拆分为多个独立的组件，提高了代码的可维护性和复用性。以下是各个组件的详细实现：

1. TodoItem 组件

组件概述

TodoItem 组件用于展示单个待办事项项，包含待办事项标题、完成状态和删除功能。

实现代码

import 'package:flutter/material.dart';

class TodoItem extends StatelessWidget {
  final String title;
  final bool isCompleted;
  final Function(bool?) onToggle;
  final Function() onDelete;

  const TodoItem({
    Key? key,
    required this.title,
    required this.isCompleted,
    required this.onToggle,
    required this.onDelete,
  }) : super(key: key);

  @override
  Widget build(BuildContext context) {
    return Container(
      margin: const EdgeInsets.symmetric(vertical: 6, horizontal: 16),
      padding: const EdgeInsets.all(12),
      decoration: BoxDecoration(
        color: Colors.white,
        borderRadius: BorderRadius.circular(8),
        boxShadow: [
          BoxShadow(
            color: Colors.grey.withOpacity(0.1),
            spreadRadius: 1,
            blurRadius: 3,
            offset: const Offset(0, 1),
          ),
        ],
      ),
      child: Row(
        children: [
          Checkbox(
            value: isCompleted,
            onChanged: onToggle,
            activeColor: Colors.deepPurple,
          ),
          Expanded(
            child: Text(
              title,
              style: TextStyle(
                fontSize: 16,
                decoration: isCompleted ? TextDecoration.lineThrough : null,
                color: isCompleted ? Colors.grey : Colors.black,
              ),
            ),
          ),
          IconButton(
            onPressed: onDelete,
            icon: const Icon(Icons.delete, color: Colors.red),
            splashRadius: 20,
          ),
        ],
      ),
    );
  }
}

技术要点

• 状态管理：通过构造函数接收外部传入的状态和回调函数
• 视觉反馈：根据 isCompleted 状态显示不同的文本样式（完成状态时显示划线效果）
• 交互设计：添加了复选框和删除按钮，提供直观的用户交互
• 布局优化：使用 Expanded 组件确保文本内容能够自适应布局

使用方法

TodoItem(
  title: todo['title'],
  isCompleted: todo['isCompleted'],
  onToggle: (value) => _toggleTodo(todo['id']),
  onDelete: () => _deleteTodo(todo['id']),
);

2. TodoInput 组件

组件概述

TodoInput 组件用于添加新的待办事项，包含文本输入框和添加按钮。

实现代码

import 'package:flutter/material.dart';

class TodoInput extends StatefulWidget {
  final Function(String) onAddTodo;

  const TodoInput({Key? key, required this.onAddTodo}) : super(key: key);

  @override
  _TodoInputState createState() => _TodoInputState();
}

class _TodoInputState extends State<TodoInput> {
  final TextEditingController _controller = TextEditingController();

  @override
  void dispose() {
    _controller.dispose();
    super.dispose();
  }

  void _addTodo() {
    final text = _controller.text.trim();
    if (text.isNotEmpty) {
      widget.onAddTodo(text);
      _controller.clear();
    } else {
      // 显示提示信息，当用户没有输入任何文本时
      ScaffoldMessenger.of(context).showSnackBar(
        const SnackBar(
          content: Text('请输入待办事项内容'),
          duration: Duration(seconds: 2),
        ),
      );
    }
  }

  @override
  Widget build(BuildContext context) {
    return Container(
      margin: const EdgeInsets.symmetric(vertical: 12, horizontal: 16),
      padding: const EdgeInsets.all(8),
      decoration: BoxDecoration(
        color: Colors.white,
        borderRadius: BorderRadius.circular(8),
        boxShadow: [
          BoxShadow(
            color: Colors.grey.withOpacity(0.1),
            spreadRadius: 1,
            blurRadius: 3,
            offset: const Offset(0, 1),
          ),
        ],
      ),
      child: Row(
        children: [
          Expanded(
            child: TextField(
              controller: _controller,
              decoration: const InputDecoration(
                hintText: '添加今日待办事项...',
                border: InputBorder.none,
                contentPadding: EdgeInsets.symmetric(horizontal: 12),
              ),
              onSubmitted: (value) {
                _addTodo();
              },
            ),
          ),
          ElevatedButton(
            onPressed: _addTodo,
            style: ElevatedButton.styleFrom(
              backgroundColor: Colors.deepPurple,
              foregroundColor: Colors.white,
              shape: RoundedRectangleBorder(
                borderRadius: BorderRadius.circular(6),
              ),
              padding: const EdgeInsets.symmetric(horizontal: 16, vertical: 10),
            ),
            child: const Text('添加'),
          ),
        ],
      ),
    );
  }
}

技术要点

• 状态管理：使用 StatefulWidget 管理输入框的状态
• 文本控制器：使用 TextEditingController 控制文本输入和清除
• 用户反馈：当用户未输入文本时，显示 SnackBar 提示信息
• 布局设计：使用 Row 和 Expanded 组件实现输入框和按钮的灵活布局

使用方法

TodoInput(onAddTodo: _addTodo);

3. 主页面集成

页面概述

主页面集成了 TodoInput 和 TodoItem 组件，实现了完整的待办事项清单功能。

实现代码

import 'package:flutter/material.dart';
import 'components/todo_input.dart';
import 'components/todo_item.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>> _todos = [
    {'id': 1, 'title': '完成 Flutter 项目开发', 'isCompleted': false},
    {'id': 2, 'title': '学习 OpenHarmony 基础知识', 'isCompleted': false},
    {'id': 3, 'title': '准备技术分享材料', 'isCompleted': false},
  ];

  int _nextId = 4;

  void _addTodo(String title) {
    setState(() {
      _todos.add({
        'id': _nextId++,
        'title': title,
        'isCompleted': false,
      });
    });
  }

  void _toggleTodo(int id) {
    setState(() {
      final todo = _todos.firstWhere((todo) => todo['id'] == id);
      todo['isCompleted'] = !todo['isCompleted'];
    });
  }

  void _deleteTodo(int id) {
    setState(() {
      _todos.removeWhere((todo) => todo['id'] == id);
    });
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text('今日待办事项'),
        backgroundColor: Colors.deepPurple,
        foregroundColor: Colors.white,
      ),
      body: Column(
        children: <Widget>[
          TodoInput(onAddTodo: _addTodo),
          Expanded(
            child: ListView.builder(
              itemCount: _todos.length,
              itemBuilder: (context, index) {
                final todo = _todos[index];
                return TodoItem(
                  title: todo['title'],
                  isCompleted: todo['isCompleted'],
                  onToggle: (value) => _toggleTodo(todo['id']),
                  onDelete: () => _deleteTodo(todo['id']),
                );
              },
            ),
          ),
        ],
      ),
    );
  }
}

技术要点

• 状态管理：使用 StatefulWidget 管理待办事项列表的状态
• 列表渲染：使用 ListView.builder 高效渲染待办事项列表
• 数据结构：使用 List<Map<String, dynamic>> 存储待办事项数据
• 状态更新：使用 setState 方法更新 UI 状态

核心功能

1. 添加待办事项：通过 TodoInput 组件输入待办事项内容，点击添加按钮或按回车键添加
2. 切换完成状态：点击待办事项前的复选框，切换待办事项的完成状态
3. 删除待办事项：点击待办事项后的删除按钮，删除对应的待办事项
4. 初始数据：内置了3条示例待办事项，方便直接查看效果

本次开发中容易遇到的问题

1. 点击添加按钮无反应

问题描述

用户在输入框中未输入任何文本时，点击添加按钮没有任何反应。

原因分析

代码中添加了条件判断，只有当输入文本不为空时才会执行添加操作：

if (text.isNotEmpty) {
  widget.onAddTodo(text);
  _controller.clear();
}

解决方案

添加用户反馈，当用户未输入文本时，显示提示信息：

if (text.isNotEmpty) {
  widget.onAddTodo(text);
  _controller.clear();
} else {
  // 显示提示信息，当用户没有输入任何文本时
  ScaffoldMessenger.of(context).showSnackBar(
    const SnackBar(
      content: Text('请输入待办事项内容'),
      duration: Duration(seconds: 2),
    ),
  );
}

2. 组件通信问题

问题描述

在开发过程中，需要在不同组件之间传递数据和回调函数。

原因分析

Flutter 中组件之间的通信需要通过构造函数传递参数和回调函数。

解决方案

使用构造函数参数传递回调函数：

// 在 TodoInput 组件中
final Function(String) onAddTodo;

// 在主页面中传递回调
TodoInput(onAddTodo: _addTodo);

3. 状态管理问题

问题描述

待办事项列表的状态需要在多个操作中保持一致。

原因分析

添加、切换完成状态和删除操作都会修改待办事项列表的状态。

解决方案

将状态管理集中在主页面，使用 setState 方法更新状态：

void _addTodo(String title) {
  setState(() {
    _todos.add({
      'id': _nextId++,
      'title': title,
      'isCompleted': false,
    });
  });
}

4. 列表渲染性能问题

问题描述

当待办事项数量较多时，可能会影响页面的渲染性能。

原因分析

直接使用 ListView 渲染大量数据会导致性能问题。

解决方案

使用 ListView.builder 高效渲染列表：

ListView.builder(
  itemCount: _todos.length,
  itemBuilder: (context, index) {
    final todo = _todos[index];
    return TodoItem(
      title: todo['title'],
      isCompleted: todo['isCompleted'],
      onToggle: (value) => _toggleTodo(todo['id']),
      onDelete: () => _deleteTodo(todo['id']),
    );
  },
);

总结本次开发中用到的技术点

1. 组件化开发

• 组件拆分：将待办事项清单功能拆分为 TodoItem 和 TodoInput 组件
• 组件通信：通过构造函数传递参数和回调函数
• 代码复用：提高了代码的可维护性和复用性

2. 状态管理

• StatefulWidget：使用 StatefulWidget 管理组件的状态
• setState：使用 setState 方法更新 UI 状态
• TextEditingController：使用 TextEditingController 管理文本输入

3. 布局设计

• Flex 布局：使用 Row、Column、Expanded 等组件实现灵活的布局
• 容器组件：使用 Container 组件添加边距、填充和装饰
• 列表渲染：使用 ListView.builder 高效渲染列表

4. 用户交互

• 点击事件：使用 onPressed 处理按钮点击事件
• 复选框：使用 Checkbox 组件实现完成状态的切换
• 文本输入：使用 TextField 组件实现文本输入
• 用户反馈：使用 SnackBar 组件显示提示信息

5. 数据结构

• List<Map<String, dynamic>>：使用列表和映射存储待办事项数据
• 唯一标识：为每个待办事项分配唯一的 ID，方便进行操作

6. 视觉设计

• 主题配置：使用 ThemeData 配置应用主题
• 阴影效果：为组件添加阴影效果，提升视觉层次感
• 颜色搭配：使用深紫色作为主题色，搭配白色和灰色
• 字体样式：根据待办事项的完成状态，使用不同的字体样式

7. 性能优化

• 列表渲染：使用 ListView.builder 实现懒加载，提高渲染性能
• 资源管理：在组件销毁时，正确释放 TextEditingController 资源

8. 平台适配

• Flutter for OpenHarmony：使用 Flutter 开发可在 OpenHarmony 平台运行的应用
• 跨平台兼容：代码可在 Android、iOS 和 OpenHarmony 平台运行

本次开发通过组件化的方式，实现了一个功能完整、交互友好的待办事项清单应用，展示了 Flutter for OpenHarmony 的开发能力。通过合理的代码组织和状态管理，确保了应用的性能和可维护性。

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