mcpField
N
navigation

navigation

github.com/verygoodopensource開発17677 回インストール今日更新
リポジトリ

navigation について

navigation は、GoRouter を使う Flutter アプリ向けにルーティングの指針を定めるスキルです。型安全な階層ルート、名前付きナビゲーション、ディープリンクに適したパラメーターを重視し、リダイレクトとテストも扱います。

主な機能

  1. 01GoRouter を使うナビゲーション規約
  2. 02生成ヘルパーを用いる型付きルート
  3. 03階層的なルート構成
  4. 04名前付きナビゲーションと URL パラメーター
  5. 05リダイレクトとウィジェットテストの指針

活用シーン

  1. 01型安全な Flutter ルートの追加
  2. 02戻る操作に沿った画面構成
  3. 03ディープリンクの設定とテスト

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/verygoodopensource/vgv-ai-flutter-plugin --skill navigation

インストール後、Claude Code で/navigationを入力して読み込まれたか確認します。

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

agents/
openai.yaml
references/
parameters.md
redirects.md
testing.md
typed-routes.md

詳細

ナビゲーション

Navigator 2.0 API を基盤とする、Flutter チーム推奨のルーティングパッケージ GoRouter を使った Flutter アプリケーションのルーティングとナビゲーションのベストプラクティスです。

基本基準

ナビゲーションに関するすべての作業で、以下の基準を適用します。

  • すべてのナビゲーションに package:go_router を使います — Navigator 2.0 や Navigator 1.0 の push／pop を直接使わないでください
  • 型安全なルートには @TypedGoRoute アノテーションを使います — ルート定義で文字列パスを直接使わないでください
  • push() より go() を優先します — 遷移先からの戻り値が必要な場合に限り push() を使います
  • extra パラメーターは使わないでください — ディープリンクが機能しなくなり、ウェブでも動作しません
  • 適切な戻るナビゲーションのために階層化されたサブルートを使います — ルートをフラットなリストではなく、親子ツリーとして構成します
  • URL の単語の区切りにはハイフンを使います — URL パスにアンダースコアやキャメルケースを使わないでください
  • 生のパス文字列ではなく、ルート名でナビゲートします — 名前付きルートナビゲーションを使い、パスの変更から切り離します
  • ナビゲーションには BuildContext の拡張メソッドを使います — GoRouter.of(context).goNamed() より context.goNamed() を優先します

ルートの構成

論理的な親子関係を持つ階層構造でルートを構成します。サブルートを使うと、アプリバーの戻るボタンが正しく表示され、URL もすっきりと保てます。

階層構造（推奨）
/flutter
  /flutter/news
  /flutter/chat
  /flutter/articles
    /flutter/articles?category=all
    /flutter/article/:id
/android
  /android/news
  /android/chat
フラットな構造（非推奨）
/flutter-news
/flutter-chat
/android-news
/android-chat

階層化されたサブルートを使うと、戻るナビゲーションが自動的に適切に設定されます。たとえば、ユーザーが /flutter/news にいる場合、戻るボタンで /flutter に移動します。

型安全なルート

すべてのルートは GoRouteData クラスで表し、@TypedGoRoute アノテーションを付与します。文字列パスを直接使わないでください。サブルートは親の routes: リスト内にネストすることで、上記の階層構造が型システムで表現され、package:go_router_builder がナビゲーションヘルパーを生成します。

基本的なルート、ネストされたサブルート、シェルルートについては、references/typed-routes.md を参照してください。

ナビゲーションメソッド

go() と push() の比較
メソッドURL の更新戻るボタン用途
go()はいアプリバー画面間の標準的なナビゲーション
push()いいえシステムポップされたルートからの戻り値が必要な場合
go() の使用（デフォルト）
const CategoriesPageRoute(size: 'small', color: 'blue').go(context);

go() を使うと、現在のルートに戻るための親ルートがある場合、アプリの AppBar に戻るボタンが表示されます。

push() の使用（戻り値が必要な場合のみ）
final result = await DialogPageRoute().push<String>(context);

ルートから戻り値を取得する必要がある場合（例：ユーザー入力を収集するダイアログ）に限り、push() を使います。ウェブでは、push() を使ってもアドレスバーは更新されません。

BuildContext の拡張メソッド

より簡潔な構文にするため、常に拡張メソッドを使います。

// Preferred
context.goNamed('flutterNews');

// Avoid
GoRouter.of(context).goNamed('flutterNews');

パラメーターの方針

リソースの識別にはパスパラメーター（:id）を使い、任意のフィルタリングにはクエリパラメーター（?category=all）を使います。extra は使わないでください。ディープリンクが機能しなくなり、ウェブでも動作しません。

パスパラメーター、クエリパラメーター、および extra が禁止されている理由の詳しい例については、references/parameters.md を参照してください。

リダイレクト

リダイレクトはルートルーターのレベル（例：認証ガード）と個々のルートのレベル（例：認可ガード）で適用できます。親のリダイレクトは子のリダイレクトより先に実行されます。

ルートレベルおよび個別ルートレベルのリダイレクト例については、references/redirects.md を参照してください。

テスト

package:mocktail で GoRouter をモックし、ウィジェットテストではウィジェットを InheritedGoRouter でラップします。リダイレクトをテストするには、対象のリダイレクトロジックを持つ GoRouter を構築し、結果のページを検証します。

GoRouter のモック方法とリダイレクトのテスト例については、references/testing.md を参照してください。

よく使われるパターン

新しいルートの追加
  1. ページウィジェットを作成します（Bloc を使用する場合は、Page/View パターンに従います）。
  2. @TypedGoRoute アノテーションを付けた GoRouteData クラスを定義します。
  3. 適切な親ルートのサブルートとして追加します。
  4. dart run build_runner build --delete-conflicting-outputs を実行して、ルートヘルパーを再生成します。
  5. 生成された型安全なルートクラスを使って移動します。
ディープリンクの設定
  1. 意味のある URL パスを使って、ルートを階層的に構成します。
  2. リソースの識別にはパスパラメーターを使用します。
  3. フィルタリングにはクエリパラメーターを使用します。extra は決して使用しないでください。
  4. ルート名で移動し、パスの再構成によってリンクが壊れないようにします。
  5. 対象の URL を使ってアプリを起動し、ディープリンクをテストします。

追加リソース

コメント

Markdown 対応