ルーティングとディープリンクの実装

目次

• コアコンセプト
• ワークフロー: アプリケーションとルーターの初期化
• ワークフロー: プラットフォームのディープリンク設定
• ワークフロー: ネストされたナビゲーションの実装
• 例

コアコンセプト

Flutter でのデクララティブルーティングには go_router パッケージを使用します。複雑なルーティングシナリオ、ディープリンク、ネストされたナビゲーションに対応した堅牢な API を提供します。

• GoRouter: アプリケーションのルートツリーを定義する中央設定オブジェクト。
• GoRoute: URL パスを Flutter スクリーンにマッピングする標準ルート。
• ShellRoute / StatefulShellRoute: 子ルートを永続的な UI シェル（例: BottomNavigationBar）でラップします。StatefulShellRoute は並列ナビゲーションブランチの状態を維持します。
• Path URL Strategy: Web URL からデフォルトの # フラグメントを削除し、プラットフォーム全体でのクリーンなディープリンクを実現します。

ワークフロー: アプリケーションとルーターの初期化

このワークフローに従い、go_router を使用した新しい Flutter アプリケーションを起動し、ルートルーティングメカニズムを設定します。

タスク進捗

• Flutter アプリケーションを作成する。
• go_router 依存関係を追加する。
• Web/ディープリンク用の URL strategy を設定する。
• GoRouter 設定を実装する。
• ルーターを MaterialApp.router にバインドする。

1. アプリケーションのスキャフォルド

次のコマンドを実行してアプリを作成し、必要なルーティングパッケージを追加します:

flutter create <app-name>
cd <app-name>
flutter pub add go_router

2. ルーターを設定

トップレベルの GoRouter インスタンスを定義します。redirect パラメータを使用して認証またはステート ベースのルーティングを処理します。

import 'package:flutter/material.dart';
import 'package:go_router/go_router.dart';
import 'package:flutter_web_plugins/url_strategy.dart';

void main() {
  // Web URL から '#' を削除するため path URL strategy を使用
  usePathUrlStrategy();
  runApp(const MyApp());
}

final GoRouter _router = GoRouter(
  initialLocation: '/',
  routes: [
    GoRoute(
      path: '/',
      builder: (context, state) => const HomeScreen(),
      routes: [
        GoRoute(
          path: 'details/:id',
          builder: (context, state) => DetailsScreen(id: state.pathParameters['id']!),
        ),
      ],
    ),
  ],
  errorBuilder: (context, state) => ErrorScreen(error: state.error),
);

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp.router(
      routerConfig: _router,
      title: 'Routing App',
    );
  }
}

ワークフロー: プラットフォームのディープリンク設定

ネイティブプラットフォームを設定して特定の URL をインターセプトし、Flutter アプリケーションにルーティングします。

タスク進捗

• ターゲットプラットフォーム（iOS、Android、またはその両方）を決定する。
• Android の条件付き設定を適用する（Manifest + Asset Links）。
• iOS の条件付き設定を適用する（Plist + Entitlements + AASA）。
• バリデータを実行 → エラーを確認 → 修正する。

Android 用に設定する場合:

1. AndroidManifest.xml を変更: .MainActivity の <activity> タグ内に intent filter を追加します。

<intent-filter android:autoVerify="true">
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />
    <data android:scheme="http" android:host="yourdomain.com" />
    <data android:scheme="https" />
</intent-filter>

2. assetlinks.json をホスト: 次の JSON を https://yourdomain.com/.well-known/assetlinks.json で提供します。

[{
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "com.yourcompany.yourapp",
    "sha256_cert_fingerprints": ["YOUR_SHA256_FINGERPRINT"]
  }
}]

iOS 用に設定する場合:

1. Info.plist を変更: Flutter のデフォルトディープリンクハンドラーをオプトインします。 注: サードパーティのディープリンキングプラグイン（例: app_links）を使用している場合は、競合を防ぐためこれを NO に設定してください。

<key>FlutterDeepLinkingEnabled</key>
<true/>

2. Runner.entitlements を変更: associated domain を追加します。

<key>com.apple.developer.associated-domains</key>
<array>
  <string>applinks:yourdomain.com</string>
</array>

3. apple-app-site-association をホスト: 次の JSON を（.json 拡張子なしで）https://yourdomain.com/.well-known/apple-app-site-association で提供します。

{
  "applinks": {
    "apps": [],
    "details": [{
      "appIDs": ["TEAM_ID.com.yourcompany.yourapp"],
      "paths": ["*"],
      "components": [{"/": "/*"}]
    }]
  }
}

バリデーションループ

バリデータを実行 → エラーを確認 → 修正する。

• Android: ADB を使用してテストします。

  adb shell 'am start -a android.intent.action.VIEW -c android.intent.category.BROWSABLE -d "https://yourdomain.com/details/123"' com.yourcompany.yourapp
  

• iOS: 起動されたシミュレータで xcrun を使用してテストします。

  xcrun simctl openurl booted https://yourdomain.com/details/123
  

ワークフロー: ネストされたナビゲーションの実装

StatefulShellRoute を使用して、永続的な UI シェル（ボトムナビゲーションバーなど）を実装し、子ルートの状態を維持します。

タスク進捗

• GoRouter 設定で StatefulShellRoute.indexedStack を定義する。
• 各ナビゲーションタブに対して StatefulShellBranch インスタンスを作成する。
• StatefulNavigationShell を使用してシェルウィジェットを実装する。

final GoRouter _router = GoRouter(
  initialLocation: '/home',
  routes: [
    StatefulShellRoute.indexedStack(
      builder: (context, state, navigationShell) {
        return ScaffoldWithNavBar(navigationShell: navigationShell);
      },
      branches: [
        StatefulShellBranch(
          routes: [
            GoRoute(
              path: '/home',
              builder: (context, state) => const HomeScreen(),
            ),
          ],
        ),
        StatefulShellBranch(
          routes: [
            GoRoute(
              path: '/settings',
              builder: (context, state) => const SettingsScreen(),
            ),
          ],
        ),
      ],
    ),
  ],
);

例

高忠実度シェルウィジェットの実装

StatefulNavigationShell を使用して、ブランチ切り替えを処理する UI シェルを実装します。

class ScaffoldWithNavBar extends StatelessWidget {
  const ScaffoldWithNavBar({
    required this.navigationShell,
    super.key,
  });

  final StatefulNavigationShell navigationShell;

  void _goBranch(int index) {
    navigationShell.goBranch(
      index,
      // アクティブなタブをタップする際、初期ロケーションへのナビゲーションをサポート
      initialLocation: index == navigationShell.currentIndex,
    );
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: navigationShell,
      bottomNavigationBar: NavigationBar(
        selectedIndex: navigationShell.currentIndex,
        onDestinationSelected: _goBranch,
        destinations: const [
          NavigationDestination(icon: Icon(Icons.home), label: 'Home'),
          NavigationDestination(icon: Icon(Icons.settings), label: 'Settings'),
        ],
      ),
    );
  }
}

プログラマティックナビゲーション

go_router によって提供される context.go() および context.push() 拡張メソッドを使用します。

// 現在のルートスタックをターゲットルートで置き換える（デクララティブ）
context.go('/details/123');

// ターゲットルートを既存スタックにプッシュする（イムペラティブ）
context.push('/details/123');

// 名前付きルートとパスパラメータを使用してナビゲート
context.goNamed('details', pathParameters: {'id': '123'});

// 現在のルートをポップ
context.pop();