画面とルート
@ScreenRoute はウィジェットのクラスを、そのパスで開かれる画面にします。画面はその値 (パス変数、クエリパラメーター、一緒に渡されたオブジェクト) を context.route から読み、ジェネレーターは画面ごとに定数を書き出します。そのためコードは、文字列ではなく BookPageRoute.to(isbn: ...) で画面を開きます。
使う理由
二十か所に文字列として書かれたアドレスは、パスが変わると黙って壊れます。ここではパスは画面の上で一度だけ宣言されます。ジェネレーターは型付きのキーと型付きの to(...) を書き出し、クエリパラメーターは build ではなく画面が開く前に変換 (そしてチェック) されます。
例
@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 |
画面自身のパスがその下にない場合に、画面が開くブランチをパスで指定する (シェル を参照) |
transition |
画面の入り方と出方。デフォルトはテーマのもの (トランジション を参照) |
content |
Markdown のリソース。{*name} で終わるパスではそのフォルダー (Markdown の画面 を参照) |
@ScreenRoute.notFound() は未知のアドレスの画面を示します (フィルター、ガード、エラー を参照)。
パスパターン
パターンは Web スターターのものです。
| パターン | 一致するもの | 値 |
|---|---|---|
/catalog/books/{isbn} |
一つのセグメント | isbn |
/orders/{id:\d+} |
正規表現に一致する一つのセグメント | id |
/docs/{*path} |
アドレスの残り (末尾でのみ) | path。先頭の / を含む (/core/beans) |
末尾に / のあるアドレス (/docs/beans/) は、それがないアドレスと同じです。静的ホストはフォルダーのアドレスをそのように送るためです。
@RouteInfo
@RouteInfo は、ナビゲーション以外の画面の情報を記述します。検索結果とリンクのプレビュー、外部からのリンクで開くかどうかです。springdoc の @Operation が @GetMapping の隣にあるように、@ScreenRoute の隣に置きます。
@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') |
現在の言語と切り替え (言語 を参照) |
ウィジェットの外では、RouteTemplate Bean を注入します。それは一番上の画面を読みます。
画面を開く
ジェネレーターは画面ごとに、その定数を持つ拡張を書き出します: BookPageRoute.pattern、BookPageRoute.routeName、値ごとのキー (isbn、page、extra)、そして値をパラメーターとする to(...) (パス変数は必須、それ以外は省略可能) です。
// アプリの状態がこの画面になり、そのパスの画面がその下に置かれる。
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 がアドレスを別の場所に送ります。
spring:
flutter:
navigation:
initial: /catalog
redirects:
"[/home]": /catalog # キーとしてのパスは角括弧で囲んで書く