spring_boot_starter_flutter_navigation
spring_boot_starter_flutter_navigation は、Flutter アプリの画面をルートに置きます。ウィジェットに @ScreenRoute('/catalog/books/{isbn}') を付けると、スターターはそのアドレスで、SDK 自身の Router の上にそれを開きます。ブラウザーのアドレスバー、ディープリンク、Android の戻るボタンがすべて、go_router なしで動きます。パスは Spring のパターン、つまり Web スターターの @GetMapping のものを使います。
使う理由
Flutter のナビゲーションは、命令的 (Navigator.push、アドレスなし、ディープリンクなし) か、画面の隣で手で保守するテーブルを持つルーティングパッケージのどちらかです。ここでは画面が自分のアドレスを宣言し、ジェネレーターがすべてのルートをチェックして型付きの定数を書き出し、残りは設定です。
- ルート上の画面: ウィジェットの
@ScreenRoute、または Dart の設定のScreenRoutesBean (Spring WebFlux のRouterFunctionsのようなもの)。起動時にマージされてチェックされ、二度宣言されたパスは両方の場所を示します。 - 型付きのナビゲーション:
BookPageRoute.to(isbn: ..., page: 2)と値ごとの型付きのキー。そのため、パスやパラメーターの名前を変えるとアプリではなくビルドが壊れます。 - シェル:
@RouteShell(branches: [...])は、ブランチの画面が変わってもタブを保ちます。各ブランチは独自のスタックを持ちます。 - フィルターとガード:
RouteFilterBean はナビゲーションを別の場所に送ります。セキュリティスターターがあれば、画面の@PreAuthorizeは、ログインしていない人をログインに送り、また戻します。 - スコープ: 画面やブランチと同じ期間だけ存在する Bean。
- Markdown の画面: フォルダーの Markdown ファイルごとに一つのアドレス。テーマで表示されます。
- アドレスの中の言語:
/ja/catalogはカタログを日本語で開きます。 - Web とディープリンク:
#のないアドレス、検索エンジンのためのルートごとのページ、iOS、macOS、Android のディープリンクのファイル。すべてプロパティから。
セットアップ
# pubspec.yaml
dependencies:
spring_boot_starter_flutter_navigation: ^0.9.0
dev_dependencies:
build_runner: ^2.17.0
spring_core_dart_generator: ^0.9.0
スターターは spring_boot_starter_flutter を取り込んで再エクスポートします。アプリはこのパッケージだけを加えます (spring_boot_starter_flutter_security もこれを取り込みます)。インポートは一つで足ります。
import 'package:spring_boot_starter_flutter_navigation/spring_boot_starter_flutter_navigation.dart';
ルーターは Material も Cupertino もインポートしないため、spring.flutter.app.type: widgets (デザインのスターターがないときの種類) のアプリのビルドにはデザインライブラリーが含まれません。下の例のように Material のウィジェットを表示するアプリは、spring_boot_starter_flutter_material と material_ui も加え、ウィジェットのために package:material_ui/material_ui.dart をインポートします。
# pubspec.yaml
dependencies:
material_ui: ^1.11.0
spring_boot_starter_flutter_material: ^0.9.0
spring_boot_starter_flutter_navigation: ^0.9.0
Cupertino のアプリは、代わりに spring_boot_starter_flutter_cupertino と cupertino_ui を加えます。スターターには Flutter 3.50 以降 (Dart 3.14) が必要です。デザインライブラリー を参照してください。
例
二つのタブ、パス変数、パラメーター、追加のオブジェクトを持つ本の画面、そして見つからない場合の画面を持つアプリです。
// lib/main.dart
import 'package:material_ui/material_ui.dart';
import 'package:spring_boot_starter_flutter_navigation/spring_boot_starter_flutter_navigation.dart';
import 'spring_gen/main.spring.dart';
// home なし: アプリのウィジェットはルーターの上に組み立てられる。
@SpringBootApplication()
void main() => runApp(
SpringApplicationWidget(application: () => springApplication),
);
class BookSummary {
const BookSummary(this.title);
final String title;
}
// タブ。各ブランチは独自の画面のスタックを持つ。
@RouteShell(branches: ['/catalog', '/profile'])
class MainTabs extends StatelessWidget {
const MainTabs(this.shell, {super.key});
final ShellState shell;
@override
Widget build(BuildContext context) => Scaffold(
body: shell.child,
bottomNavigationBar: NavigationBar(
selectedIndex: shell.index,
onDestinationSelected: shell.select,
destinations: const [
NavigationDestination(icon: Icon(Icons.book), label: 'Catalog'),
NavigationDestination(icon: Icon(Icons.person), label: 'Profile'),
],
),
);
}
@ScreenRoute('/catalog', title: 'Catalog')
class CatalogPage extends StatelessWidget {
const CatalogPage({super.key});
@override
Widget build(BuildContext context) => ListView(
children: [
ListTile(
title: const Text('Dune'),
// 生成された型付きのアドレス: パラメーターの名前を変えるとコンパイルできない。
onTap: () => context.route.go(
BookPageRoute.to(isbn: '978-0441013593', page: 1, extra: const BookSummary('Dune')),
),
),
],
);
}
@ScreenRoute('/catalog/books/{isbn}', title: 'Book', params: {'page': int}, extra: BookSummary)
class BookPage extends StatelessWidget {
const BookPage({super.key});
@override
Widget build(BuildContext context) {
final route = context.route;
final isbn = route.get(BookPageRoute.isbn); // String
final page = route.get(BookPageRoute.page) ?? 1; // int?
final summary = route.get(BookPageRoute.extra); // BookSummary?
return Text('${summary?.title ?? isbn}, page $page');
}
}
@ScreenRoute('/profile', title: 'Profile')
class ProfilePage extends StatelessWidget {
const ProfilePage({super.key});
@override
Widget build(BuildContext context) => const Text('Profile');
}
@ScreenRoute.notFound()
class NotFoundPage extends StatelessWidget {
const NotFoundPage({super.key});
@override
Widget build(BuildContext context) => Text('Nothing at ${context.route.uri}');
}
# lib/resources/application.yml
spring:
flutter:
# MaterialApp: 唯一のデザインのスターター spring_boot_starter_flutter_material が
# アプリの種類を決める (spring.flutter.app.type は不要)
navigation:
initial: /catalog
実行する
dart run build_runner build # 画面を登録し、BookPageRoute などを書き出す
flutter run -d chrome
homeのないSpringApplicationWidgetは、ルーターの上にMaterialApp.router(またはspring.flutter.app.typeに応じてCupertinoApp.router、WidgetsApp.router) を組み立てます。種類が設定されていなければ唯一のデザインのスターターの種類、なければwidgetsです。二つのデザインのスターターがあれば設定が必要です。materialには Material のスターターが、cupertinoには Cupertino のスターターが必要です。ないと起動は失敗し、加えるべきスターターを示します。- ルートは起動時にチェックされます。二度宣言されたパス、どのシェルも持たないブランチ、セキュリティスターターのないガード付きの画面は、レポートとともに起動を止めます。
- ブラウザーではアドレスバーに
/catalog/books/978-0441013593?page=1が表示され、再読み込みすると同じ画面が開きます (追加のオブジェクトは失われるため、常に省略可能です)。
内容
- 画面とルート:
@ScreenRoute、パスパターン、context.route、生成される定数、画面を開く。 - トランジション: テーマのトランジション、または画面やナビゲーションごとのもの。
- シェルとタブ:
@RouteShell、独自のスタックを持つブランチ。 - Dart の設定でのルート:
ScreenRoutesBean。 - フィルター、ガード、エラー:
RouteFilter、@PreAuthorize、見つからない場合とエラーの画面。 - 画面やブランチごとの Bean:
routeとbranchのスコープ。 - Markdown の画面:
content:とRouteContentView。 - 言語: 言語ごとのアドレス。
- Web とディープリンク: アドレスバー、検索エンジンのためのページ、ディープリンク。
- テスト: ウィジェットテストでのナビゲーション。
- すべてのプロパティ: スターターのすべてのキー。
- Spring との違い
Spring (Java) との対応
Spring にはアプリのナビゲーションはありません。名前は、従うべきものがある箇所では Spring に従います。パスパターン (@GetMapping のもの)、RouterFunctions (Spring WebFlux)、API の *Template、Bean のスコープ、ガードの @PreAuthorize です。