
# 画面とルート

`@ScreenRoute` はウィジェットのクラスを、そのパスで開かれる画面にします。画面はその値 (パス変数、クエリパラメーター、一緒に渡されたオブジェクト) を `context.route` から読み、ジェネレーターは画面ごとに定数を書き出します。そのためコードは、文字列ではなく `BookPageRoute.to(isbn: ...)` で画面を開きます。

## 使う理由

二十か所に文字列として書かれたアドレスは、パスが変わると黙って壊れます。ここではパスは画面の上で一度だけ宣言されます。ジェネレーターは型付きのキーと型付きの `to(...)` を書き出し、クエリパラメーターは `build` ではなく画面が開く前に変換 (そしてチェック) されます。

## 例

```dart
@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

| 引数 | 意味 |
|---|---|
| `path` | 完全な形で書いた Spring のパスパターン |
| `title` | ブラウザーのタブ、スクリーンリーダー、検索結果。`#{key}` はメッセージキー (`#{book.title}`) |
| `name` | ルートの名前。デフォルトはクラス名のケバブケース (`BookPage` は `book-page`) |
| `params` | 画面が読むクエリパラメーターとその型。画面が開くときに `ConversionService` で変換されるため、`?page=abc` は `build` で失敗する代わりにエラー画面を表示する |
| `extra` | アドレスに含まれず一緒に渡されるオブジェクトの型。再読み込みやディープリンクでは失われるため、常に省略可能 |
| `shell` | 画面のパスがどのブランチの下にもない場合に、画面が開くシェル。通常は省略する |
| `branch` | 画面自身のパスがその下にない場合に、画面が開くブランチをパスで指定する ([シェル](shells.md) を参照) |
| `transition` | 画面の入り方と出方。デフォルトはテーマのもの ([トランジション](transitions.md) を参照) |
| `content` | Markdown のリソース。`{*name}` で終わるパスではそのフォルダー ([Markdown の画面](markdown-screens.md) を参照) |

`@ScreenRoute.notFound()` は未知のアドレスの画面を示します ([フィルター、ガード、エラー](filters-and-guards.md) を参照)。

## パスパターン

パターンは Web スターターのものです。

| パターン | 一致するもの | 値 |
|---|---|---|
| `/catalog/books/{isbn}` | 一つのセグメント | `isbn` |
| `/orders/{id:\d+}` | 正規表現に一致する一つのセグメント | `id` |
| `/docs/{*path}` | アドレスの残り (末尾でのみ) | `path`。先頭の `/` を含む (`/core/beans`) |

末尾に `/` のあるアドレス (`/docs/beans/`) は、それがないアドレスと同じです。静的ホストはフォルダーのアドレスをそのように送るためです。

## @RouteInfo

`@RouteInfo` は、ナビゲーション以外の画面の情報を記述します。検索結果とリンクのプレビュー、外部からのリンクで開くかどうかです。springdoc の `@Operation` が `@GetMapping` の隣にあるように、`@ScreenRoute` の隣に置きます。

```dart
@ScreenRoute('/', title: 'NEON Books')
@RouteInfo(description: 'The bookshop of the NEON district.', image: 'resources:images/og.png')
class HomePage extends StatelessWidget { ... }

@ScreenRoute('/checkout')
@RouteInfo(index: false, link: false)
class CheckoutPage extends StatelessWidget { ... }
```

| 引数 | デフォルト | 意味 |
|---|---|---|
| `description` | なし | 検索結果とリンクのプレビューでタイトルの下に出るテキスト。`#{key}` はメッセージキー |
| `image` | なし | プレビューの画像 (`resources:images/book.png`) |
| `index` | `true` | `false`: 検索エンジンはページを掲載してはならない (`noindex`、サイトマップに含めない) |
| `paths` | なし | ビルドが知りえない、パス変数を持つ画面のアドレス (`['/catalog/books/978-0']`)。検索エンジンのためのページに使う |
| `link` | `true` | アプリ外からのリンク (ディープリンク) で画面を開くかどうか |

## ルートを読む: context.route

ウィジェットはルートを `context.route` から読みます。これはウィジェット自身の画面に結び付いた `RouteTemplate` で (別の画面の下にある画面も自分の値を見ます)、パラメーターが変わると再構築されます。`State.initState` では、再構築しない `RouteTemplate.read(context)` を使ってください。

| `context.route` | |
|---|---|
| `get(BookPageRoute.isbn)` | 型付きの値: パス変数、パラメーター、追加のオブジェクト |
| `pathVariable('isbn')`、`param<int>('page')`、`params<String>('tag')`、`extra<T>()` | 同じものを名前で |
| `uri`、`pattern`、`name`、`matches('/catalog/**')` | アドレスとルート |
| `stack`、`branch`、`canPop`、`changes` | 重なった画面、シェルのブランチ、`pop` で画面が閉じるかどうか、ナビゲーションのストリーム |
| `content` | ルートの Markdown のリソース (あれば) |
| `language`、`switchLanguage('ja')` | 現在の言語と切り替え ([言語](languages.md) を参照) |

ウィジェットの外では、`RouteTemplate` Bean を注入します。それは一番上の画面を読みます。

## 画面を開く

ジェネレーターは画面ごとに、その定数を持つ拡張を書き出します: `BookPageRoute.pattern`、`BookPageRoute.routeName`、値ごとのキー (`isbn`、`page`、`extra`)、そして値をパラメーターとする `to(...)` (パス変数は必須、それ以外は省略可能) です。

```dart
// アプリの状態がこの画面になり、そのパスの画面がその下に置かれる。
context.route.go(BookPageRoute.to(isbn: '978-0441013593', page: 2));

// 一番上に開き、結果を待つ。
final paid = await context.route.push<bool>(CheckoutPageRoute.to());

// 結果とともに戻る。
context.route.pop(true);

// 新しい画面を開かずに、別のパラメーター (?page=3) で同じ画面に。
context.route.replaceParams({'page': 3});
```

| メソッド | 意味 |
|---|---|
| `go(location, {pathVariables, params, extra, transition})` | ロケーションをアプリの状態にする。その画面と、その下にそのパスの画面を、そのシェルのブランチの中に置く (他のブランチは保たれる) |
| `push<T>(location, {...})` | ロケーションを一番上に開き、その画面が pop されたときの値で完了する。それ以外の方法で閉じられたら `null` |
| `pop([result])` | 一番上の画面を結果とともに閉じる。閉じるものがなければ `false` |
| `replaceParams(params)` | 新しい画面を開かずに、画面のクエリパラメーターを置き換える |

`go` と `push` は文字列も受け取ります。アドレス (`'/catalog?page=2'`)、または `pathVariables:` を伴うパターンです。`params:` と `extra:` は値を追加し、`transition:` はこのナビゲーションに限って画面のトランジションを置き換えます。

同じルートの別のアドレス (`/books/1` から `/books/2`) では画面が保たれます。その状態、スクロール、周りのシェルはそのままで、新しいアドレスと変数で再構築されます。

## アプリが始まる場所

アプリは、プラットフォームが与えるアドレス (ブラウザーのバー、ディープリンク) で始まります。何も与えられない場合 (`/`)、`spring.flutter.navigation.initial` が最初の画面を指定し、`spring.flutter.navigation.redirects` がアドレスを別の場所に送ります。

```yaml
spring:
  flutter:
    navigation:
      initial: /catalog
      redirects:
        "[/home]": /catalog     # キーとしてのパスは角括弧で囲んで書く
```

## 関連項目

- [シェルとタブ](shells.md)
- [Dart の設定でのルート](dart-configuration.md)
- [すべてのプロパティ](properties.md)
- [Web スターターのパスパターン](../spring-boot-starter-web/controllers/request-mapping.md)
