《深度链接与路由进阶：从内部导航到跨端唤起》

// 命令式：状态藏在 Navigator 内部
Navigator.push(context, MaterialPageRoute(builder: (_) => DetailPage()));

// 声明式：路由由页面列表推导，状态可导出/恢复
Navigator(
  pages: [
    const MaterialPage(child: HomePage()),
    if (_selectedId != null) MaterialPage(child: DetailPage(id: _selectedId!)),
  ],
  onPopPage: (route, result) { ... },
)

class MyRouterDelegate extends RouterDelegate<AppState>
    with ChangeNotifier {
  // 监听平台 URL 变化
  @override
  Future<void> setNewRoutePath(AppState state) async {
    _state = state;
    notifyListeners();
  }
}

final router = GoRouter(
  initialLocation: '/',
  routes: [
    ShellRoute(
      builder: (context, state, child) => AppScaffold(child: child),
      routes: [
        GoRoute(path: '/', builder: (_, __) => HomePage()),
        GoRoute(path: '/orders', builder: (_, __) => OrdersPage()),
      ],
    ),
    GoRoute(
      path: '/product/:id',
      builder: (context, state) =>
          ProductDetail(id: state.pathParameters['id']!),
    ),
  ],
);

final router = GoRouter(
  refreshListenable: authProvider,
  redirect: (context, state) {
    final loggedIn = authProvider.isLoggedIn;
    final needAuth = state.matchedLocation.startsWith('/account');
    if (needAuth && !loggedIn) return '/login';
    return null;
  },
);

// 用 go_router_builder 生成类型安全的深链参数
@TypedGoRoute<ProductDetailRoute>(path: '/product/:id')
class ProductDetailRoute extends GoRouteData {
  final String id;
  const ProductDetailRoute({required this.id});

  @override
  Widget build(BuildContext context, GoRouterState state) =>
      ProductDetail(id: id);
}

// 深链到达后可以类型安全地拿参数
final route = ProductDetailRoute.fromState(state);
print(route.id);

// 全局配置：hash 策略（对静态托管更友好）
final router = GoRouter(
  urlPathStrategy: UrlPathStrategy.hash,
  routes: [...],
);

// 刷新深链后页面必须能重建状态
GoRoute(
  path: '/product/:id',
  builder: (context, state) =>
      ProductDetail(id: state.pathParameters['id']!),
);

// 兜底未知路由
final router = GoRouter(
  errorBuilder: (context, state) => NotFoundPage(path: state.uri.toString()),
);

# Nginx：所有请求回退到 index.html
location / {
  try_files $uri $uri/ /index.html;
}

<!-- AndroidManifest.xml -->
<activity
  android:name=".MainActivity"
  android:launchMode="singleTop"
  android:exported="true">

  <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="https" android:host="example.com" />
  </intent-filter>
</activity>

<!-- ios/Runner/Runner.entitlements -->
<key>com.apple.developer.associated-domains</key>
<array>
  <string>applinks:example.com</string>
</array>

// 冷启动：应用完全未运行，深链随初始化事件进入
// 热启动：应用已在后台，深链走 onLink 回调
final sub = appLinks.linkStream.listen((Uri uri) {
  router.go(uri.path); // 统一交给 GoRouter 处理
});

// app_links 包会自动区分冷/热启动并合并进同一流

// 路径参数 + 查询参数 + 任意扩展对象
GoRoute(
  path: '/search/:query',
  builder: (context, state) {
    final query = state.pathParameters['query']!;
    final page = int.tryParse(state.uri.queryParameters['page'] ?? '1') ?? 1;
    final filter = state.extra as SearchFilter?; // 复杂对象走 extra
    return SearchPage(query: query, page: page, filter: filter);
  },
);

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp.router(
      routerConfig: router,
      restorationScopeId: 'app', // 让系统记录导航栈
    );
  }
}

// 页面内用 RestorableInt 等保存可恢复状态
class ProductDetail extends StatefulWidget { ... }
class _ProductDetailState extends State<ProductDetail> with RestorationMixin {
  final RestorableInt _scrollOffset = RestorableInt(0);
  @override
  String? get restorationId => 'product_detail';
  ...
}

// 深链进入后控制返回行为
context.push('/product/123');       // 允许返回
context.go('/product/123');         // 替换当前页，深链落地常用
context.go('/checkout', extra: cart); // 清栈进入新流程

// 只接受来自可信域名的深链
bool isValidDeepLink(Uri uri) {
  const allowedHosts = {'example.com', 'm.example.com'};
  return allowedHosts.contains(uri.host) && uri.scheme == 'https';
}

// 收口处统一过滤
final safeUri = uri.linkStream
    .where(isValidDeepLink)
    .first;

final router = GoRouter(
  redirect: (context, state) {
    final loggedIn = context.read<SessionCubit>().state.isLoggedIn;
    // 深链目标需要登录 → 重定向到登录页并记录原路径
    if (!loggedIn && state.matchedLocation.startsWith('/private')) {
      return '/login?redirect=${Uri.encodeComponent(state.matchedLocation)}';
    }
    return null;
  },
);

// 深链携带的数据先进状态管理，再驱动 UI
class ProductDetail extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    final productId = GoRouterState.of(context).pathParameters['id']!;
    // 交给 Bloc/Provider 加载并缓存商品数据
    return BlocProvider(
      create: (_) => ProductBloc(productId)..add(LoadProduct(productId)),
      child: const ProductView(),
    );
  }
}