画面とルート

@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     # キーとしてのパスは角括弧で囲んで書く

関連項目