Flutter for OpenHarmony 实战：步骤导航实现

问题描述：在自定义步骤导航组件的样式时，可能会遇到颜色、大小等样式不符合预期的问题。解决方案仔细阅读组件的参数说明，了解每个参数的作用对于颜色自定义，确保使用的颜色值在 Flutter 中是有效的对于大小自定义，注意保持指示器大小和连接线高度的比例协调核心思想：将步骤导航功能封装为独立的组件，提高代码复用性和可维护性实现方式：创建组件，通过参数传递实现灵活配置优势：简化了主应用代码，便于在不同场景

2501_93894871

519人浏览 · 2026-02-02 23:17:07

2501_93894871 · 2026-02-02 23:17:07 发布

欢迎加入开源鸿蒙跨平台社区： 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 实时预览效果展示
在这里插入图片描述

运行到鸿蒙虚拟设备中效果展示
在这里插入图片描述

功能代码实现

步骤项数据模型

步骤导航组件的核心是步骤项数据模型，它定义了每个步骤的基本信息。在 step_navigation.dart 文件中，我们创建了 StepItem 类：

/// 步骤导航项数据模型
class StepItem {
  final String title;
  final String? description;

  const StepItem({
    required this.title,
    this.description,
  });
}

这个模型包含两个属性：

title：步骤的标题，必填项
description：步骤的描述信息，可选参数

通过这个简洁的数据模型，我们可以灵活地定义每个步骤的内容，支持有描述和无描述两种情况。

步骤导航主组件

StepNavigation 是整个功能的核心组件，它负责渲染步骤列表、当前激活状态以及步骤间的连接线：

/// 步骤导航组件
class StepNavigation extends StatelessWidget {
  /// 步骤项列表
  final List<StepItem> steps;
  
  /// 当前激活的步骤索引（从0开始）
  final int currentStep;
  
  /// 步骤点击回调
  final Function(int index)? onStepTap;
  
  /// 激活状态颜色
  final Color activeColor;
  
  /// 完成状态颜色
  final Color completedColor;
  
  /// 未激活状态颜色
  final Color inactiveColor;
  
  /// 步骤指示器大小
  final double indicatorSize;
  
  /// 步骤连接线高度
  final double lineHeight;

  const StepNavigation({
    super.key,
    required this.steps,
    required this.currentStep,
    this.onStepTap,
    this.activeColor = Colors.blue,
    this.completedColor = Colors.green,
    this.inactiveColor = Colors.grey,
    this.indicatorSize = 32.0,
    this.lineHeight = 2.0,
  });

  @override
  Widget build(BuildContext context) {
    return Container(
      padding: const EdgeInsets.symmetric(horizontal: 16, vertical: 24),
      child: Column(
        children: _buildSteps(),
      ),
    );
  }

  /// 构建步骤列表
  List<Widget> _buildSteps() {
    final List<Widget> stepWidgets = [];

    for (int i = 0; i < steps.length; i++) {
      final bool isCompleted = i < currentStep;
      final bool isActive = i == currentStep;
      final bool isInactive = i > currentStep;

      // 添加步骤项
      stepWidgets.add(
        GestureDetector(
          onTap: () {
            if (onStepTap != null) {
              onStepTap!(i);
            }
          },
          child: Container(
            margin: const EdgeInsets.only(bottom: 24),
            child: Row(
              crossAxisAlignment: CrossAxisAlignment.start,
              children: [
                // 步骤指示器
                Container(
                  width: indicatorSize,
                  height: indicatorSize,
                  decoration: BoxDecoration(
                    shape: BoxShape.circle,
                    color: isCompleted
                        ? completedColor
                        : isActive
                            ? activeColor
                            : inactiveColor,
                  ),
                  child: Center(
                    child: isCompleted
                        ? const Icon(
                            Icons.check,
                            color: Colors.white,
                            size: 16,
                          )
                        : Text(
                            '${i + 1}',
                            style: TextStyle(
                              color: Colors.white,
                              fontSize: 14,
                              fontWeight: FontWeight.bold,
                            ),
                          ),
                  ),
                ),

                // 步骤内容
                Expanded(
                  child: Container(
                    margin: const EdgeInsets.only(left: 16),
                    child: Column(
                      crossAxisAlignment: CrossAxisAlignment.start,
                      children: [
                        Text(
                          steps[i].title,
                          style: TextStyle(
                            fontSize: 16,
                            fontWeight: isActive ? FontWeight.bold : FontWeight.normal,
                            color: isActive ? activeColor : Colors.black,
                          ),
                        ),
                        if (steps[i].description != null)
                          Padding(
                            padding: const EdgeInsets.only(top: 4),
                            child: Text(
                              steps[i].description!,
                              style: const TextStyle(
                                fontSize: 14,
                                color: Colors.grey,
                              ),
                            ),
                          ),
                      ],
                    ),
                  ),
                ),
              ],
            ),
          ),
        ),
      );

      // 添加连接线（最后一步除外）
      if (i < steps.length - 1) {
        stepWidgets.add(
          Container(
            margin: EdgeInsets.only(left: indicatorSize / 2 - lineHeight / 2, bottom: 24),
            width: lineHeight,
            height: 24,
            color: i < currentStep ? completedColor : inactiveColor,
          ),
        );
      }
    }

    return stepWidgets;
  }
}

组件特点

高度可定制化：支持自定义激活状态颜色、完成状态颜色、未激活状态颜色、步骤指示器大小和连接线高度
交互性：通过 onStepTap 回调函数支持步骤点击事件
视觉反馈：根据步骤状态（完成、激活、未激活）显示不同的视觉效果
灵活布局：自适应步骤数量，自动处理步骤间的连接线

核心实现逻辑

状态判断：通过 currentStep 索引判断每个步骤的状态（完成、激活、未激活）
步骤渲染：使用 GestureDetector 包裹每个步骤项，实现点击交互
指示器渲染：根据步骤状态显示不同颜色的圆形指示器，完成状态显示对勾图标
连接线渲染：在步骤之间添加连接线，根据前一步的状态显示不同颜色

步骤导航示例组件

为了方便开发者理解和使用步骤导航组件，我们创建了 StepNavigationDemo 示例组件：

/// 步骤导航示例组件
class StepNavigationDemo extends StatefulWidget {
  const StepNavigationDemo({super.key});

  @override
  State<StepNavigationDemo> createState() => _StepNavigationDemoState();
}

class _StepNavigationDemoState extends State<StepNavigationDemo> {
  /// 当前步骤索引
  int _currentStep = 1;

  /// 步骤列表
  final List<StepItem> _steps = [
    StepItem(
      title: '填写基本信息',
      description: '输入姓名、邮箱和联系电话',
    ),
    StepItem(
      title: '选择服务类型',
      description: '根据您的需求选择合适的服务',
    ),
    StepItem(
      title: '确认订单信息',
      description: '检查订单详情并提交',
    ),
    StepItem(
      title: '完成支付',
      description: '选择支付方式并完成付款',
    ),
  ];

  /// 处理步骤点击
  void _handleStepTap(int index) {
    setState(() {
      _currentStep = index;
    });
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text('步骤导航示例'),
      ),
      body: Column(
        children: [
          // 步骤导航
          StepNavigation(
            steps: _steps,
            currentStep: _currentStep,
            onStepTap: _handleStepTap,
          ),
          
          // 内容区域
          Expanded(
            child: Center(
              child: Column(
                mainAxisAlignment: MainAxisAlignment.center,
                children: [
                  Text(
                    '当前步骤: ${_currentStep + 1}',
                    style: const TextStyle(
                      fontSize: 18,
                      fontWeight: FontWeight.bold,
                    ),
                  ),
                  const SizedBox(height: 20),
                  Text(
                    '步骤名称: ${_steps[_currentStep].title}',
                    style: const TextStyle(
                      fontSize: 16,
                      color: Colors.blue,
                    ),
                  ),
                  const SizedBox(height: 40),
                  const Text(
                    '点击步骤可切换当前进度',
                    style: TextStyle(
                      fontSize: 14,
                      color: Colors.grey,
                    ),
                  ),
                ],
              ),
            ),
          ),
        ],
      ),
    );
  }
}

示例组件功能

完整的步骤流程：展示了一个包含4个步骤的完整流程
交互演示：实现了点击步骤切换当前进度的功能
状态反馈：在内容区域显示当前步骤的信息，提供清晰的状态反馈
布局展示：展示了如何在实际应用中集成和使用步骤导航组件

应用入口配置

在 main.dart 文件中，我们导入并使用了步骤导航组件：

import 'package:flutter/material.dart';
import 'components/step_navigation.dart';

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

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

  // This widget is the root of your application.
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Flutter for openHarmony',
      theme: ThemeData(
        // This is the theme of your application.
        //
        // TRY THIS: Try running your application with "flutter run". You'll see
        // the application has a purple toolbar. Then, without quitting the app,
        // try changing the seedColor in the colorScheme below to Colors.green
        // and then invoke "hot reload" (save your changes or press the "hot
        // reload" button in a Flutter-supported IDE, or press "r" if you used
        // the command line to start the app).
        //
        // Notice that the counter didn't reset back to zero; the application
        // state is not lost during the reload. To reset the state, use hot
        // restart instead.
        //
        // This works for code too, not just values: Most code changes can be
        // tested with just a hot reload.
        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});

  // This class is the configuration for the state. It holds the values (in this
  // case the title) provided by the parent (in this case the App widget) and
  // used by the build method of the State. Fields in a Widget subclass are
  // always marked "final".

  final String title;

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

class _MyHomePageState extends State<MyHomePage> {
  @override
  Widget build(BuildContext context) {
    return const Scaffold(
      body: StepNavigationDemo(),
    );
  }
}

配置说明

导入组件：通过 import 'components/step_navigation.dart'; 导入步骤导航组件
使用示例组件：在 _MyHomePageState 的 build 方法中，直接使用 StepNavigationDemo 作为应用的主内容
简化布局：移除了默认的计数器和浮动按钮，专注于展示步骤导航功能