Flutter Fluro 路由框架在 OpenHarmony 中的深度应用

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

一、引言

路由管理是 Flutter 应用开发中的核心模块。fluro 是一个功能强大的路由管理库，提供了灵活的路由配置和导航能力。本文将详细介绍如何在 Flutter-OH 项目中使用 fluro 进行路由管理，并探讨鸿蒙化适配的关键要点。

二、Fluro 概述

Fluro 是一个轻量级的 Flutter 路由管理库，具有以下特性：

• 灵活的路由配置：支持静态路由和动态路由
• 参数传递：支持复杂参数的传递
• 路由拦截：支持路由守卫功能
• 过渡动画：支持自定义页面过渡动画

三、项目集成

3.1 添加依赖

dependencies:
  flutter:
    sdk: flutter
  fluro: ^2.0.5

3.2 初始化路由

import 'package:fluro/fluro.dart';

class AppRouter {
  static final FluroRouter router = FluroRouter();

  static void configureRoutes() {
    router.define(
      '/',
      handler: Handler(
        handlerFunc: (context, params) => const HomePage(),
      ),
    );

    router.define(
      '/detail/:id',
      handler: Handler(
        handlerFunc: (context, params) {
          final id = params['id']?.first;
          return DetailPage(id: id ?? '');
        },
      ),
    );

    router.define(
      '/login',
      handler: Handler(
        handlerFunc: (context, params) => const LoginPage(),
      ),
      transitionType: TransitionType.fadeIn,
    );
  }
}

3.3 配置应用

void main() {
  AppRouter.configureRoutes();
  runApp(const MyApp());
}

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

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Fluro Demo',
      onGenerateRoute: AppRouter.router.generator,
      home: const HomePage(),
    );
  }
}

四、核心用法

4.1 基础导航

// 导航到首页
AppRouter.router.navigateTo(context, '/');

// 导航到详情页并传递参数
AppRouter.router.navigateTo(context, '/detail/123');

// 导航到登录页
AppRouter.router.navigateTo(
  context, 
  '/login',
  transition: TransitionType.cupertino,
);

4.2 接收参数

class DetailPage extends StatelessWidget {
  final String id;

  const DetailPage({super.key, required this.id});

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Detail')),
      body: Center(
        child: Text('Item ID: $id'),
      ),
    );
  }
}

4.3 路由拦截

class AuthMiddleware extends Middleware {
  @override
  Future<MiddlewareResult> handleRequest(
    RequestContext request,
    MiddlewareHandler handler,
  ) async {
    // 检查用户是否登录
    bool isLoggedIn = await checkLoginStatus();
    
    if (isLoggedIn) {
      return handler.next(request);
    } else {
      // 未登录则跳转到登录页
      request.redirect('/login', replace: true);
      return MiddlewareResult.redirect;
    }
  }

  Future<bool> checkLoginStatus() async {
    // 检查登录状态逻辑
    return false;
  }
}

// 在路由配置中使用中间件
router.define(
  '/profile',
  handler: Handler(
    handlerFunc: (context, params) => const ProfilePage(),
  ),
  middleware: [AuthMiddleware()],
);

五、高级功能

5.1 复杂参数传递

// 传递复杂参数
final params = {
  'user': jsonEncode(User(id: '1', name: 'John').toJson()),
};
AppRouter.router.navigateTo(
  context,
  '/profile?${Uri(queryParameters: params).query}',
);

// 接收复杂参数
class ProfilePage extends StatelessWidget {
  const ProfilePage({super.key});

  @override
  Widget build(BuildContext context) {
    final params = ModalRoute.of(context)?.settings.arguments as Map?;
    final userJson = params?['user'];
    final user = User.fromJson(jsonDecode(userJson));
    
    return Scaffold(
      appBar: AppBar(title: const Text('Profile')),
      body: Center(
        child: Text('User: ${user.name}'),
      ),
    );
  }
}

5.2 自定义过渡动画

router.define(
  '/custom',
  handler: Handler(
    handlerFunc: (context, params) => const CustomPage(),
  ),
  transitionType: TransitionType.custom,
  transitionBuilder: (context, animation, secondaryAnimation, child) {
    return ScaleTransition(
      scale: animation,
      child: child,
    );
  },
);

六、鸿蒙化适配要点

6.1 平台特定路由

router.define(
  '/harmony-only',
  handler: Handler(
    handlerFunc: (context, params) {
      if (Platform.isHarmony) {
        return const HarmonySpecificPage();
      }
      return const FallbackPage();
    },
  ),
);

6.2 生命周期集成

class RouterObserver extends NavigatorObserver {
  @override
  void didPush(Route<dynamic> route, Route<dynamic>? previousRoute) {
    super.didPush(route, previousRoute);
    // 页面进入统计
    print('Page entered: ${route.settings.name}');
  }

  @override
  void didPop(Route<dynamic> route, Route<dynamic>? previousRoute) {
    super.didPop(route, previousRoute);
    // 页面退出统计
    print('Page exited: ${route.settings.name}');
  }
}

// 在 MaterialApp 中配置
MaterialApp(
  navigatorObservers: [RouterObserver()],
);

七、实战案例：完整的路由管理系统

class RouteManager {
  static void goHome(BuildContext context) => 
      AppRouter.router.navigateTo(context, '/');

  static void goDetail(BuildContext context, String id) => 
      AppRouter.router.navigateTo(context, '/detail/$id');

  static void goLogin(BuildContext context) => 
      AppRouter.router.navigateTo(context, '/login');

  static void goProfile(BuildContext context) => 
      AppRouter.router.navigateTo(context, '/profile');

  static void goBack(BuildContext context) => 
      AppRouter.router.pop(context);
}

八、性能优化建议

1. 路由预加载：提前初始化常用页面
2. 避免深层嵌套路由：保持路由层级简洁
3. 使用常量路由名称：避免硬编码字符串
4. 路由缓存：对于复杂页面使用 keepAlive

九、常见问题与解决方案

9.1 参数获取失败

问题：无法获取路由参数。

解决方案：确保参数在路由路径中正确定义，并使用 params['key']?.first 获取。

9.2 页面栈管理问题

问题：页面栈混乱，返回时出现异常。

解决方案：使用 replace: true 替换当前页面，或使用 clearStack: true 清空页面栈。

十、总结

Fluro 以其灵活的配置和强大的功能，成为 Flutter 路由管理的首选方案。在 OpenHarmony 平台上，Fluro 的跨平台特性使其能够无缝运行，为开发者提供高效的路由管理体验。

---

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