Flutter导航管理插件playx_navigation的使用

Playx Navigation

pub package

Playx Navigation 是一个强大的 Flutter 包，增强了 Flutter 应用程序的导航功能。它基于 go_router 包提供了强大的功能，如带有绑定的路由特定生命周期管理、广泛的路由配置选项和自定义页面过渡。通过 Playx Navigation，您可以为您的应用创建高度模块化和可维护的导航系统。

特性

路由绑定: 将自定义逻辑附加到特定路由，处理进入或退出路由的生命周期事件。
高级路由配置: 使用广泛的配置选项微调您的路由行为，包括自定义过渡、模式行为和状态管理。
路由管理: 轻松导航到路由、替换路由并管理导航堆栈，而无需构建上下文。
自定义页面过渡: 使用预定义的过渡或创建自己的过渡以增强用户体验。

安装

在 pubspec.yaml 中添加 Playx Navigation：

dependencies:
  playx_navigation: ^0.0.1

然后运行：

flutter pub get

设置

步骤 1: 定义你的路由（可选）

你可以选择定义路由名称和路径以便于管理：

abstract class Routes {  
  static const home = 'home';  
  static const products = 'products';  
  static const details = 'productDetails';  
}  
  
abstract class Paths {  
  static const home = '/home';  
  static const products = '/products';  
  static const details = ':id';  
}

步骤 2: 创建你的路由绑定

为每个路由创建绑定，以处理生命周期事件，例如进入或退出路由。这确保了应用程序的逻辑得到妥善管理：

class ProductsBinding extends PlayxBinding {
  [@override](/user/override)
  Future<void> onEnter(BuildContext context, GoRouterState state) async {
    // 初始化产品页面所需的资源。
  }

  [@override](/user/override)
  Future<void> onExit(BuildContext context) async {
    // 清理离开产品页面时的资源。
  }
}

步骤 3: 创建你的 GoRouter 实例

使用 PlayxRoute 定义应用的导航结构：

final router = GoRouter(  
  initialLocation: Paths.home,  
  debugLogDiagnostics: true,  
  routes: [  
    PlayxRoute(  
      path: Paths.home,  
      name: Routes.home,  
      builder: (context, state) => const HomePage(),  
      binding: HomeBinding(),  
    ),  
    PlayxRoute(  
      path: Paths.products,  
      name: Routes.products,  
      builder: (context, state) => ProductsPage(),  
      binding: ProductsBinding(),  
      routes: [  
        PlayxRoute(  
          path: Paths.details,  
          name: Routes.details,  
          builder: (context, state) => ProductDetailsPage(product: state.extra as Product),  
          binding: DetailsBinding(),  
        ),  
      ],  
    ),  
  ],  
);

步骤 4: 初始化 PlayxNavigationBuilder

将 MaterialApp 或 CupertinoApp 包装在 PlayxNavigationBuilder 中，并传递路由器实例以启用 Playx Navigation 并管理路由更改：

class MyApp extends StatelessWidget {  
  const MyApp({super.key});  
  
  [@override](/user/override)  
  Widget build(BuildContext context) {  
    return PlayxNavigationBuilder(  
      router: router,  
      builder: (context) {  
        return MaterialApp.router(  
          title: 'Playx',  
          theme: ThemeData(  
            colorScheme: ColorScheme.fromSeed(seedColor: Colors.deepPurple),  
          ),  
          routerDelegate: router.routerDelegate,  
          routeInformationParser: router.routeInformationParser,  
          routeInformationProvider: router.routeInformationProvider,  
          backButtonDispatcher: router.backButtonDispatcher,  
        );  
      });  
  }  
}

PlayxNavigationBuilder 简化了设置过程，提供了一种集中式的方式来配置和管理路由、绑定和其他与导航相关的设置。

PlayxNavigation 方法和工具

PlayxNavigation 类提供了各种静态方法来使用 GoRouter 包管理 Flutter 应用程序中的导航。在使用这些方法之前，请确保已通过调用 PlayxNavigation.boot() 或通过包含 PlayxNavigationBuilder 小部件来初始化 PlayxNavigation。

初始化

在使用任何导航方法之前，初始化 PlayxNavigation：

PlayxNavigation.boot(router: yourGoRouterInstance);

或者使用 PlayxNavigationBuilder 来自动初始化导航系统：

return PlayxNavigationBuilder(
  router: router,
  builder: (context) {
    return MaterialApp.router(
      routerDelegate: router.routerDelegate,
      routeInformationParser: router.routeInformationParser,
    );
  });

方法概述

导航到路由

无需构建上下文即可调用导航方法。

to: 将新路由推入导航堆栈。

await PlayxNavigation.to('/details', extra: {'id': 1});

offAll: 替换堆栈中所有先前的路由。

await PlayxNavigation.offAll('/home', extra: {'clearHistory': true});

offAndTo: 替换当前路由。

await PlayxNavigation.offAndTo('/profile', extra: {'userId': 123});

命名路由导航

toNamed: 将命名路由推入导航堆栈。

await PlayxNavigation.toNamed('details', pathParameters: {'id': '1'});

offAllNamed: 替换堆栈中所有先前的路由。
```
await PlayxNavigation.offAllNamed('home');
```

offAndToNamed: 替换当前路由。

await PlayxNavigation.offAndToNamed('profile', pathParameters: {'userId': '123'});

导航控制

goToBranch: 导航到指定索引的 StatefulShellRoute 分支位置。
pop([T? result]): 弹出最顶层的路由。
```
PlayxNavigation.pop();
```
canPop(): 如果导航堆栈中有可以弹出的路由，则返回 true。
```
if (PlayxNavigation.canPop()) {
  PlayxNavigation.pop();
}
```

访问当前路由信息和管理路由更改

currentRoute: 获取表示当前路由的 RouteMatch 对象。
currentRouteName: 获取当前路由的名称（如果可用）。
addRouteChangeListener(VoidCallback listener): 添加路由更改监听器。
removeRouteChangeListener(VoidCallback listener): 移除已添加的路由更改监听器。

路由绑定

管理路由生命周期与 PlayxBinding

PlayxBinding 是 PlayxNavigation 包中的抽象类，用于管理路由生命周期中的操作。这包括当路由首次进入时初始化资源，当其被重新访问时处理任务，当其被隐藏时暂停动作，以及当其从导航堆栈中永久移除时清理资源。

主要功能：

全面的生命周期管理: 处理路由生命周期事件，如进入、重新进入、隐藏和退出。
子路由意识: 当主路由及其所有子路由都被移除时，主路由的 onExit 方法才会被调用，确保有效的资源管理。

生命周期方法

onEnter: 当路由首次进入时触发。使用此方法初始化资源或获取数据。
onReEnter: 当重新访问仍然在堆栈中的路由但暂时隐藏时调用。
onHidden: 当路由被隐藏但未移除时触发。适用于暂停任务或释放临时资源。
onExit: 当路由从堆栈中永久移除时触发。使用此方法清理资源或保存状态。

示例：

class MyRouteBinding extends PlayxBinding {
  [@override](/user/override)
  Future<void> onEnter(BuildContext context, GoRouterState state) async {
    // 初始化资源或获取路由所需的数据。
  }

  [@override](/user/override)
  Future<void> onReEnter(
    BuildContext context,
    GoRouterState? state,
    bool wasPoppedAndReentered,
  ) async {
    // 处理路由重新访问时的特殊情况。
  }

  [@override](/user/override)
  Future<void> onHidden(BuildContext context) async {
    // 暂停任务或释放临时资源。
  }

  [@override](/user/override)
  Future<void> onExit(BuildContext context) async {
    // 清理资源或保存状态。
  }
}

示例用例

数据获取: 当路由首次进入时获取所需数据。
资源清理: 在路由完全退出时释放资源。
临时暂停: 当路由被隐藏时暂停动画或后台任务。
重新访问处理: 在路由重新进入后刷新界面或状态。

通过扩展 PlayxBinding，您可以有效地管理应用路由的生命周期，并确保资源被最优地利用。

配置路由

高级路由和自定义过渡与 PlayxRoute

PlayxRoute 类扩展了 GoRoute 类的功能，提供了高级功能，使开发者能够更好地控制 Flutter 应用程序中的路由。通过 PlayxRoute，您可以实现自定义页面过渡、绑定特定于路由的生命周期事件，并轻松配置页面设置。

PlayxRoute 概述

PlayxRoute 旨在通过以下功能增强导航：

生命周期管理: 附加在路由进入或退出时运行的自定义逻辑，从而更好地控制应用的状态和行为。
页面配置: 自定义各种设置，如页面标题、过渡持续时间和模态行为。
自定义过渡: 应用预定义或自定义动画以在页面之间过渡。

生命周期管理与 PlayxBinding

onEnter 和 onExit: 附加自定义逻辑以处理路由进入或退出时发生的情况。这对于管理资源、获取数据或其他设置/拆卸任务非常有用。
重定向处理: 实现自定义重定向逻辑，根据应用状态动态改变导航流程。

示例：

PlayxRoute(
  path: '/dashboard',
  name: 'dashboard',
  builder: (context, state) => DashboardPage(),
  binding: DashboardBinding(), 
);

2. 自定义页面配置与 PlayxPageConfiguration

PlayxPageConfiguration 类允许您精细调整应用中路由的行为、过渡和外观。无论您需要定制过渡持续时间、管理路由的模态行为，还是配置状态管理，PlayxPageConfiguration 都能满足您的需求。

主要配置选项：

灵活设置: 调整属性，如过渡持续时间、模态行为和是否应保持路由在内存中 (maintainState)。
全面配置: 使用 PlayxPageConfiguration 设置页面标题、键和其他重要设置。这允许您详细定制每个路由。

示例：

final config = PlayxPageConfiguration.customTransition(
  transitionsBuilder: (context, animation, secondaryAnimation, child) {
    return FadeTransition(opacity: animation, child: child);
  },
  transitionDuration: Duration(milliseconds: 500),
  opaque: true,
  fullscreenDialog: true,
);

通过 PlayxPageConfiguration，您可以调整几乎每个方面，如何显示和管理路由，确保导航体验符合应用的需求。

3. 创建自定义过渡

PlayxRoute 的一个突出特性是其定义自定义页面过渡的能力，或利用现有的过渡类型，如 Material、Cupertino 和淡入淡出过渡。

预定义过渡类型：

Material: 标准 Android 风格过渡。
Cupertino: iOS 风格过渡。
Fade: 简单的淡入淡出过渡。
Native: 根据平台自动选择适当的过渡。
None: 禁用任何过渡效果。

创建自定义过渡：

要创建自定义过渡，请使用 PlayxPageConfiguration.customTransition 构造函数。这允许您定义当路由被推送或弹出时应该如何进行动画。

示例：

PlayxRoute(
  path: '/custom',
  name: 'customRoute',
  builder: (context, state) => CustomPage(),
  binding: CustomBinding(),
  pageConfiguration: PlayxPageConfiguration.customTransition(
    transitionsBuilder: (context, animation, secondaryAnimation, child) {
      return ScaleTransition(scale: animation, child: child);
    },
    transitionDuration: Duration(milliseconds: 400),
  ),
)

在这个例子中，路由使用 ScaleTransition 动画，具有自定义缩放效果。过渡持续时间为 400 毫秒，提供平滑且定制化的动画。

支持和贡献

如有问题、意见或功能请求，请访问 GitHub 仓库。欢迎贡献！

参见

Playx: 一套冗余功能，减少代码，提高生产力，更好的组织。
Playx_core: Playx 生态系统的核心，帮助应用主题和本地化。
Playx_localization: 从 Playx 生态系统为 Flutter 应用程序提供本地化和国际化。

许可证

该项目采用 MIT 许可证 - 详情请参阅许可证文件。

示例代码

import 'package:flutter/material.dart';
import 'package:playx_navigation/playx_navigation.dart';
import 'package:playx_navigation_example/navigation/pages.dart';

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

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

  [@override](/user/override)
  State<MyApp> createState() => _MyAppState();
}

class _MyAppState extends State<MyApp> {
  final router = AppPages.router;

  [@override](/user/override)
  Widget build(BuildContext context) {
    return PlayxNavigationBuilder(
        router: router,
        builder: (context) {
          return MaterialApp.router(
            title: 'Playx',
            theme: ThemeData(
              colorScheme: ColorScheme.fromSeed(seedColor: Colors.deepPurple),
              useMaterial3: true,
            ),
            routerDelegate: router.routerDelegate,
            routeInformationParser: router.routeInformationParser,
            routeInformationProvider: router.routeInformationProvider,
            backButtonDispatcher: router.backButtonDispatcher,
          );
        });
  }
}

更多关于Flutter导航管理插件playx_navigation的使用的实战系列教程也可以访问 https://www.itying.com/category-92-b0.html

songsunli 1楼•20 小时前

更多关于Flutter导航管理插件playx_navigation的使用的实战系列教程也可以访问 https://www.itying.com/category-92-b0.html

当然，以下是如何在Flutter项目中使用playx_navigation插件进行导航管理的一个简单示例。假设你已经将playx_navigation添加到你的pubspec.yaml文件中并运行了flutter pub get。

首先，确保你的pubspec.yaml包含以下依赖项：

dependencies:
  flutter:
    sdk: flutter
  playx_navigation: ^最新版本号  # 替换为实际的最新版本号

然后，你可以按照以下步骤配置和使用playx_navigation。

1. 配置导航图

首先，你需要定义一个导航图，通常在一个单独的文件中，例如routes.dart。

// routes.dart
import 'package:flutter/material.dart';
import 'package:playx_navigation/playx_navigation.dart';
import 'screens/home_screen.dart';
import 'screens/detail_screen.dart';

class AppRoutes {
  static final List<RouteDef> routes = [
    RouteDef(path: '/', builder: () => HomeScreen()),
    RouteDef(path: '/detail/:id', builder: (context, args) => DetailScreen(id: args['id'] as int)),
  ];
}

2. 创建屏幕

创建两个简单的屏幕，HomeScreen和DetailScreen。

// screens/home_screen.dart
import 'package:flutter/material.dart';

class HomeScreen extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: Text('Home Screen')),
      body: Center(
        child: ElevatedButton(
          onPressed: () {
            // 导航到详情屏幕，传递一个参数
            Navigator.of(context).pushNamed('/detail/1');
          },
          child: Text('Go to Detail Screen'),
        ),
      ),
    );
  }
}

// screens/detail_screen.dart
import 'package:flutter/material.dart';

class DetailScreen extends StatelessWidget {
  final int id;

  DetailScreen({required this.id});

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

3. 配置MaterialApp

在你的主文件中（通常是main.dart），使用PlayxNavigation包装你的MaterialApp，并设置路由。

// main.dart
import 'package:flutter/material.dart';
import 'package:playx_navigation/playx_navigation.dart';
import 'routes.dart';

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

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return PlayxNavigation(
      routes: AppRoutes.routes,
      onGenerateRoute: (settings) {
        // 这里可以处理未定义的路由（可选）
        return MaterialPageRoute<void>(
          builder: (context) {
            return Scaffold(
              appBar: AppBar(title: Text('Not Found')),
              body: Center(child: Text('Route Not Found')),
            );
          },
        );
      },
      child: MaterialApp(
        title: 'Flutter Demo',
        theme: ThemeData(
          primarySwatch: Colors.blue,
        ),
        home: Navigator(
          onGenerateRoute: (settings) {
            return PlayxNavigation.of(context).generator(settings);
          },
        ),
      ),
    );
  }
}

4. 运行应用

现在，当你运行应用时，应该会看到HomeScreen。点击按钮将导航到DetailScreen，并显示传递的参数。

这个示例展示了如何使用playx_navigation插件进行基本的路由管理。根据你的需求，你可以进一步自定义和扩展这个基础示例。