Flutter路由构建辅助插件 go_router_builder 的使用

go_router_builder 是一个用于简化和增强 go_router 插件的代码生成工具。它允许你定义强类型的路由，从而在编译时捕获错误，而不是在运行时。下面将详细介绍如何使用这个插件，并提供完整的示例。

依赖项

首先，在你的 pubspec.yaml 文件中添加以下依赖：

dependencies:
  # 其他依赖...
  go_router: ^9.0.3

dev_dependencies:
  # 其他开发依赖...
  build_runner: ^2.0.0
  go_router_builder: ^2.3.0

源码结构

为了使用 go_router_builder，你需要导入 go_router.dart 库，并包含一个指向生成的 Dart 文件的 part 指令。生成的文件名总是 [source_file].g.dart。

import 'package:go_router/go_router.dart';

part 'main.g.dart';

运行 build_runner

执行一次性的构建命令：

dart run build_runner build

更多信息可以参考 build_runner 的官方文档。

路由定义

每个路由都需要定义为继承自 GoRouteData 的类，并覆盖 build 方法。

class HomeRoute extends GoRouteData {
  const HomeRoute();

  @override
  Widget build(BuildContext context, GoRouterState state) => const HomeScreen();
}

路由树

路由树可以通过在顶级路由上定义属性来创建：

@TypedGoRoute<HomeRoute>(
  path: '/',
  routes: <TypedGoRoute<GoRouteData>>[
    TypedGoRoute<FamilyRoute>(
      path: 'family/:fid',
    ),
  ],
)
class HomeRoute extends GoRouteData {
  const HomeRoute();

  @override
  Widget build(BuildContext context, GoRouterState state) => const HomeScreen();
}

@TypedGoRoute<LoginRoute>(path: '/login')
class LoginRoute extends GoRouteData {
  LoginRoute({this.from});
  final String? from;

  @override
  Widget build(BuildContext context, GoRouterState state) {
    return LoginScreen(from: from);
  }
}

初始化 GoRouter

代码生成器会将所有顶级路由聚合到一个名为 $appRoutes 的列表中，以便初始化 GoRouter 实例：

final GoRouter router = GoRouter(routes: $appRoutes);

错误处理

你可以使用强类型路由来提供错误处理器：

class ErrorRoute extends GoRouteData {
  ErrorRoute({required this.error});
  final Exception error;

  @override
  Widget build(BuildContext context, GoRouterState state) {
    return ErrorScreen(error: error);
  }
}

final GoRouter routerWithErrorBuilder = GoRouter(
  routes: $appRoutes,
  errorBuilder: (BuildContext context, GoRouterState state) {
    return ErrorRoute(error: state.error!).build(context, state);
  },
);

导航

使用代码生成器提供的 go 或 push 方法进行导航：

void onTap() => const FamilyRoute(fid: 'f2').go(context);

返回值

从 go_router 6.5.0 开始，推送一个路由并在随后弹出它可以产生返回值。生成的路由也支持这一功能：

final bool? result = await const FamilyRoute(fid: 'John').push<bool>(context);

查询参数

未在路径中列出的参数表示查询参数：

@TypedGoRoute<LoginRoute>(path: '/login')
class LoginRoute extends GoRouteData {
  LoginRoute({this.from});
  final String? from;

  @override
  Widget build(BuildContext context, GoRouterState state) {
    return LoginScreen(from: from);
  }
}

默认值

对于非空类型的查询参数，可以定义默认值：

@TypedGoRoute<MyRoute>(path: '/my-route')
class MyRoute extends GoRouteData {
  MyRoute({this.queryParameter = 'defaultValue'});
  final String queryParameter;

  @override
  Widget build(BuildContext context, GoRouterState state) {
    return MyScreen(queryParameter: queryParameter);
  }
}

示例应用

下面是一个完整的示例应用，展示了如何使用 go_router_builder 和 go_router：

import 'package:flutter/material.dart';
import 'package:go_router/go_router.dart';
import 'package:provider/provider.dart';

import 'shared/data.dart';

part 'main.g.dart';

void main() => runApp(App());

class App extends StatelessWidget {
  App({super.key});

  final LoginInfo loginInfo = LoginInfo();
  static const String title = 'GoRouter Example: Named Routes';

  @override
  Widget build(BuildContext context) => ChangeNotifierProvider<LoginInfo>.value(
        value: loginInfo,
        child: MaterialApp.router(
          routerConfig: _router,
          title: title,
          debugShowCheckedModeBanner: false,
        ),
      );

  late final GoRouter _router = GoRouter(
    debugLogDiagnostics: true,
    routes: $appRoutes,

    // 根据登录状态重定向
    redirect: (BuildContext context, GoRouterState state) {
      final bool loggedIn = loginInfo.loggedIn;
      final String loginLoc = const LoginRoute().location;
      final bool goingToLogin = state.matchedLocation == loginLoc;

      if (!loggedIn && !goingToLogin) {
        return LoginRoute(fromPage: state.matchedLocation).location;
      }

      if (loggedIn && goingToLogin) {
        return const HomeRoute().location;
      }

      return null;
    },

    refreshListenable: loginInfo,
  );
}

// 定义路由
@TypedGoRoute<HomeRoute>(
  path: '/',
  routes: <TypedGoRoute<GoRouteData>>[
    TypedGoRoute<FamilyRoute>(
      path: 'family/:fid',
      routes: <TypedGoRoute<GoRouteData>>[
        TypedGoRoute<PersonRoute>(
          path: 'person/:pid',
          routes: <TypedGoRoute<GoRouteData>>[
            TypedGoRoute<PersonDetailsRoute>(path: 'details/:details'),
          ],
        ),
      ],
    ),
    TypedGoRoute<FamilyCountRoute>(path: 'family-count/:count'),
  ],
)
class HomeRoute extends GoRouteData {
  const HomeRoute();

  @override
  Widget build(BuildContext context, GoRouterState state) => const HomeScreen();
}

@TypedGoRoute<LoginRoute>(
  path: '/login',
)
class LoginRoute extends GoRouteData {
  const LoginRoute({this.fromPage});

  final String? fromPage;

  @override
  Widget build(BuildContext context, GoRouterState state) =>
      LoginScreen(from: fromPage);
}

class FamilyRoute extends GoRouteData {
  const FamilyRoute(this.fid);

  final String fid;

  @override
  Widget build(BuildContext context, GoRouterState state) =>
      FamilyScreen(family: familyById(fid));
}

class PersonRoute extends GoRouteData {
  const PersonRoute(this.fid, this.pid);

  final String fid;
  final int pid;

  @override
  Widget build(BuildContext context, GoRouterState state) {
    final Family family = familyById(fid);
    final Person person = family.person(pid);
    return PersonScreen(family: family, person: person);
  }
}

class PersonDetailsRoute extends GoRouteData {
  const PersonDetailsRoute(this.fid, this.pid, this.details, {this.$extra});

  final String fid;
  final int pid;
  final PersonDetails details;
  final int? $extra;

  @override
  Page<void> buildPage(BuildContext context, GoRouterState state) {
    final Family family = familyById(fid);
    final Person person = family.person(pid);

    return MaterialPage<Object>(
      fullscreenDialog: true,
      key: state.pageKey,
      child: PersonDetailsPage(
        family: family,
        person: person,
        detailsKey: details,
        extra: $extra,
      ),
    );
  }
}

class FamilyCountRoute extends GoRouteData {
  const FamilyCountRoute(this.count);

  final int count;

  @override
  Widget build(BuildContext context, GoRouterState state) =>
      FamilyCountScreen(count: count);
}

通过上述步骤，你可以在 Flutter 应用中有效地使用 go_router_builder 来管理复杂的路由系统，并确保类型安全和更清晰的代码结构。