Flutter for OpenHarmony 实战：页面路由切换动画 - 使用 PageRouteBuilder自定义转场动画。

在移动开发领域，我们总是面临着选择与适配。今天，你的Flutter应用在Android和iOS上跑得正欢，明天可能就需要考虑一个新的平台：HarmonyOS（鸿蒙）。这不是一道选答题，而是很多团队正在面对的现实。Flutter的优势很明确——写一套代码，就能在两个主要平台上运行，开发体验流畅。而鸿蒙代表的是下一个时代的互联生态，它不仅仅是手机系统，更着眼于未来全场景的体验。

水果风暴欧派

408人浏览 · 2026-02-08 21:49:52

水果风暴欧派 · 2026-02-08 21:49:52 发布

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

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

功能代码实现

页面路由切换动画组件

组件结构设计

页面路由切换动画组件采用了模块化的设计思路，主要包含以下核心部分：

自定义路由：使用 CustomPageRoute 类继承自 PageRouteBuilder，实现自定义转场动画
动画类型：定义 RouteAnimationType 枚举，包含淡入淡出、滑动、缩放和旋转四种动画效果
页面组件：实现 FirstPage 和 SecondPage 两个页面组件，用于展示动画效果
示例集成：使用 RouteAnimationExample 组件整合所有功能

核心代码实现

自定义路由动画

class CustomPageRoute extends PageRouteBuilder {
  final Widget child;
  final RouteAnimationType type;

  CustomPageRoute({
    required this.child,
    required this.type,
  }) : super(
          transitionDuration: Duration(milliseconds: 500),
          reverseTransitionDuration: Duration(milliseconds: 500),
          pageBuilder: (context, animation, secondaryAnimation) => child,
          transitionsBuilder: (context, animation, secondaryAnimation, child) {
            switch (type) {
              case RouteAnimationType.fade:
                return FadeTransition(
                  opacity: animation,
                  child: child,
                );
              case RouteAnimationType.slide:
                return SlideTransition(
                  position: Tween<Offset>(
                    begin: Offset(1.0, 0.0),
                    end: Offset.zero,
                  ).animate(animation),
                  child: child,
                );
              case RouteAnimationType.scale:
                return ScaleTransition(
                  scale: Tween<double>(
                    begin: 0.0,
                    end: 1.0,
                  ).animate(animation),
                  child: child,
                );
              case RouteAnimationType.rotate:
                return RotationTransition(
                  turns: Tween<double>(
                    begin: 1.0,
                    end: 0.0,
                  ).animate(animation),
                  child: ScaleTransition(
                    scale: animation,
                    child: child,
                  ),
                );
              default:
                return FadeTransition(
                  opacity: animation,
                  child: child,
                );
            }
          },
        );
}

enum RouteAnimationType {
  fade,
  slide,
  scale,
  rotate,
}

第一页组件

class FirstPage extends StatelessWidget {
  const FirstPage({Key? key}) : super(key: key);

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      backgroundColor: Colors.blue,
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: [
            Text(
              '第一页',
              style: TextStyle(fontSize: 32, color: Colors.white, fontWeight: FontWeight.bold),
            ),
            SizedBox(height: 40),
            _buildAnimationButton(context, '淡入淡出', RouteAnimationType.fade),
            SizedBox(height: 20),
            _buildAnimationButton(context, '滑动', RouteAnimationType.slide),
            SizedBox(height: 20),
            _buildAnimationButton(context, '缩放', RouteAnimationType.scale),
            SizedBox(height: 20),
            _buildAnimationButton(context, '旋转', RouteAnimationType.rotate),
          ],
        ),
      ),
    );
  }

  Widget _buildAnimationButton(BuildContext context, String title, RouteAnimationType type) {
    return ElevatedButton(
      onPressed: () {
        Navigator.push(
          context,
          CustomPageRoute(
            child: SecondPage(animationType: type),
            type: type,
          ),
        );
      },
      style: ElevatedButton.styleFrom(
        backgroundColor: Colors.white,
        foregroundColor: Colors.blue,
        padding: EdgeInsets.symmetric(horizontal: 32, vertical: 16),
        textStyle: TextStyle(fontSize: 18),
      ),
      child: Text(title),
    );
  }
}

第二页组件

class SecondPage extends StatelessWidget {
  final RouteAnimationType animationType;

  const SecondPage({Key? key, required this.animationType}) : super(key: key);

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      backgroundColor: Colors.green,
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: [
            Text(
              '第二页',
              style: TextStyle(fontSize: 32, color: Colors.white, fontWeight: FontWeight.bold),
            ),
            SizedBox(height: 20),
            Text(
              '动画类型: ${_getAnimationTypeName()}',
              style: TextStyle(fontSize: 18, color: Colors.white),
            ),
            SizedBox(height: 40),
            ElevatedButton(
              onPressed: () {
                Navigator.pop(context);
              },
              style: ElevatedButton.styleFrom(
                backgroundColor: Colors.white,
                foregroundColor: Colors.green,
                padding: EdgeInsets.symmetric(horizontal: 32, vertical: 16),
                textStyle: TextStyle(fontSize: 18),
              ),
              child: Text('返回第一页'),
            ),
          ],
        ),
      ),
    );
  }

  String _getAnimationTypeName() {
    switch (animationType) {
      case RouteAnimationType.fade:
        return '淡入淡出';
      case RouteAnimationType.slide:
        return '滑动';
      case RouteAnimationType.scale:
        return '缩放';
      case RouteAnimationType.rotate:
        return '旋转';
      default:
        return '未知';
    }
  }
}

示例集成

class RouteAnimationExample extends StatelessWidget {
  const RouteAnimationExample({Key? key}) : super(key: key);

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text('页面路由切换动画'),
        centerTitle: true,
        backgroundColor: Colors.blue,
      ),
      body: FirstPage(),
    );
  }
}