
# 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 の設定の `ScreenRoutes` Bean (Spring WebFlux の `RouterFunctions` のようなもの)。起動時にマージされてチェックされ、二度宣言されたパスは両方の場所を示します。
- **型付きのナビゲーション**: `BookPageRoute.to(isbn: ..., page: 2)` と値ごとの型付きのキー。そのため、パスやパラメーターの名前を変えるとアプリではなくビルドが壊れます。
- **シェル**: `@RouteShell(branches: [...])` は、ブランチの画面が変わってもタブを保ちます。各ブランチは独自のスタックを持ちます。
- **フィルターとガード**: `RouteFilter` Bean はナビゲーションを別の場所に送ります。セキュリティスターターがあれば、画面の `@PreAuthorize` は、ログインしていない人をログインに送り、また戻します。
- **スコープ**: 画面やブランチと同じ期間だけ存在する Bean。
- **Markdown の画面**: フォルダーの Markdown ファイルごとに一つのアドレス。テーマで表示されます。
- **アドレスの中の言語**: `/ja/catalog` はカタログを日本語で開きます。
- **Web とディープリンク**: `#` のないアドレス、検索エンジンのためのルートごとのページ、iOS、macOS、Android のディープリンクのファイル。すべてプロパティから。

## セットアップ

```yaml
# 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/index.md) を取り込んで再エクスポートします。アプリはこのパッケージだけを加えます (`spring_boot_starter_flutter_security` もこれを取り込みます)。インポートは一つで足ります。

```dart
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](../spring-boot-starter-flutter-material/index.md) と `material_ui` も加え、ウィジェットのために `package:material_ui/material_ui.dart` をインポートします。

```yaml
# 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) が必要です。[デザインライブラリー](../spring-boot-starter-flutter/design-libraries.md) を参照してください。

## 例

二つのタブ、パス変数、パラメーター、追加のオブジェクトを持つ本の画面、そして見つからない場合の画面を持つアプリです。

```dart
// 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}');
}
```

```yaml
# lib/resources/application.yml
spring:
  flutter:
    # MaterialApp: 唯一のデザインのスターター spring_boot_starter_flutter_material が
    # アプリの種類を決める (spring.flutter.app.type は不要)
    navigation:
      initial: /catalog
```

## 実行する

```bash
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` が表示され、再読み込みすると同じ画面が開きます (追加のオブジェクトは失われるため、常に省略可能です)。

## 内容

- [画面とルート](screens.md): `@ScreenRoute`、パスパターン、`context.route`、生成される定数、画面を開く。
- [トランジション](transitions.md): テーマのトランジション、または画面やナビゲーションごとのもの。
- [シェルとタブ](shells.md): `@RouteShell`、独自のスタックを持つブランチ。
- [Dart の設定でのルート](dart-configuration.md): `ScreenRoutes` Bean。
- [フィルター、ガード、エラー](filters-and-guards.md): `RouteFilter`、`@PreAuthorize`、見つからない場合とエラーの画面。
- [画面やブランチごとの Bean](scopes.md): `route` と `branch` のスコープ。
- [Markdown の画面](markdown-screens.md): `content:` と `RouteContentView`。
- [言語](languages.md): 言語ごとのアドレス。
- [Web とディープリンク](web-and-deep-links.md): アドレスバー、検索エンジンのためのページ、ディープリンク。
- [テスト](testing.md): ウィジェットテストでのナビゲーション。
- [すべてのプロパティ](properties.md): スターターのすべてのキー。
- [Spring との違い](differences.md)

## Spring (Java) との対応

Spring にはアプリのナビゲーションはありません。名前は、従うべきものがある箇所では Spring に従います。パスパターン (`@GetMapping` のもの)、`RouterFunctions` (Spring WebFlux)、API の `*Template`、Bean のスコープ、ガードの `@PreAuthorize` です。

## 関連項目

- [spring_boot_starter_flutter](../spring-boot-starter-flutter/index.md)
- [spring_boot_starter_flutter_security](../spring-boot-starter-flutter-security/index.md)
- [Flutter のためのジェネレーター](../spring-core-dart-generator/flutter/index.md)
- [ビルドに含まれるもの](optimizations.md)
