Flutter Example

2. 先选骨架

• 按复杂度选择模板：
  • 默认情况：XxxDemoPage -> XxxDemoView
  • 带本地状态类：XxxDemoPage -> Stateful XxxDemoView
  • 复杂场景：xxx_example.dart 作为入口，再拆 pages/ 等子目录
• 同一个示例内保持一种清晰模式，不要混入多套入口风格。

3. 对外入口规则

• 叶子 demo 页面文件统一使用 xxx_example.dart。
• 对外入口组件默认命名为 XxxDemoPage，优先使用 StatelessWidget。
• 默认只负责返回对应的 XxxDemoView。
• 允许承担轻量组装职责，例如：
  • provider / bloc / controller 注入
  • ScreenUtilInit 之类的外层包裹
  • observer 注册与恢复
  • 必要的生命周期桥接
• 不要把具体业务 UI、复杂布局、列表渲染和页面交互细节塞进 XxxDemoPage。
• 如果外层需要管理注入层生命周期、恢复全局设置或注册/注销 observer，允许 XxxDemoPage 使用 StatefulWidget。

class ToastDemoPage extends StatelessWidget {
  const ToastDemoPage({super.key, required this.title});

  final String title;

  @override
  Widget build(BuildContext context) {
    return ToastDemoView(title: title);
  }
}

4. 内层页面规则

• XxxDemoView：单文件内承载 Scaffold 的真实页面组件。
• 复杂场景下可拆到 pages/ 目录中的真实页面组件，但 xxx_example.dart 仍然是统一入口。
• 默认优先生成 XxxDemoView；只有在页面明显变复杂时，才继续拆目录。
• 无本地状态时用 StatelessWidget；需要 initState、setState、控制器生命周期时改用 StatefulWidget。
• 有 await 后再更新 UI、弹 SnackBar、setState 或访问上下文时：
  • 在 State 里优先使用 if (!mounted) return;
  • 只有依赖 BuildContext 时使用 if (!context.mounted) return;
• 常规页面优先保持这个骨架：

class XxxDemoView extends StatelessWidget {
  const XxxDemoView({super.key, required this.title});

  final String title;

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: Text(title)),
      body: getBody(),
      floatingActionButton: getFAB(),
    );
  }

  Widget getBody() {
    return const Center();
  }

  Widget getFAB() {
    return FloatingActionButton(
      onPressed: null,
      child: const Icon(Icons.add),
    );
  }
}

• 如果页面不需要 FAB，可以删除 floatingActionButton 和 getFAB()，不要为了统一而保留空实现。
• 如果页面明显变复杂，就继续拆小组件或拆目录，但保持入口模式一致。

5. 复杂示例及时拆目录

• 当示例包含状态管理、controller、notifier、observer、binding、可复用页面组件时，不要把所有内容塞进一个 xxx_example.dart。
• 应按现有项目风格拆分，例如：
  • pages/
  • controllers/
  • notifiers/
  • cubits/
  • providers/
  • observers/
  • bindings/
• xxx_example.dart 优先只保留对外入口、注入层、包裹层和必要的轻量生命周期逻辑。
• 只有在 demo 本身确实有多文件支撑内容时，才保留额外目录；不要为了单页 demo 再嵌套一层同名目录。
• 可参考：
  • lib/demos/state_management/provider/
  • lib/demos/state_management/bloc/
  • lib/demos/state_management/riverpod/
  • lib/demos/basics/getx_app/

6. 命名与 helper 约定

• 类名、文件名、路由标题保持一致语义，例如：
  • ToastDemoPage / ToastDemoView / packages/toast_example.dart
  • ProviderCounterDemoPage / CounterProviderPage / state_management/provider/provider_example.dart
• title 默认与 demo 名称语义一致，例如 Toast、SharedPreferences、Counter Example。
• subtitle 默认与当前分组现有风格保持一致；若无额外说明，可与 title 主语义一致。
• 同一个文件内保持一种 helper 命名风格，不要混用 getBody() 和 _buildBody()。
• 默认骨架优先使用：
  • getBody()
  • getFAB()
• 如果 FAB 逻辑依赖上下文，优先写成 Widget getFAB(BuildContext context)。
• 只有在页面明显更复杂、且整个文件已经采用私有 build helper 风格时，才使用 _buildBody()、_buildFab()。

7. Catalog 接入规则

• 普通 demo 不手写额外 app 路由，统一通过 catalog.dart 接入。
• 路由项统一使用 CatalogEntry。
• 叶子页面使用 CatalogEntry.page(...)。
• 子分组使用 CatalogEntry.catalog(...)。
• path 统一写相对路径：
  • 顶层分组相对根目录，例如 basics、layout、network
  • 子分组和页面相对父分组目录，例如 containers、dio、shared-preferences
• 多单词 path 优先使用 kebab-case，例如：
  • shared-preferences
  • screen-util
  • secure-storage
• pageBuilder 应直接返回 const XxxDemoPage(...)。
• 需要包示例说明时，可在文件顶部保留这种注释风格：

/// Toast
/// https://pub.dev/packages/fluttertoast

8. 项目约定

• 只用 package import。
• 优先使用 const、final、强类型、显式返回类型。
• 不使用 print；如需日志，使用 lib/core/utils/logger/。
• 尽量延续周边文件已有的中英文风格。
• 异步逻辑里遵守 use_build_context_synchronously 规则，不要在缺少 mounted 检查时直接使用上下文。
• 写 package 示例前，先检查 lib/core/utils/ 是否已有封装；若已有，优先复用项目统一封装，而不是重复直接调用第三方包 API。
• 常见复用位置包括：
  • lib/core/utils/ui/toast.dart
  • lib/core/utils/ui/notification.dart
  • lib/core/utils/storage/shared_preferences.dart
  • lib/core/utils/logger/logger.dart
• 默认禁止在普通 demo page 外再包一层 MaterialApp、GetMaterialApp。
• 只有像 lib/demos/basics/getx_app/ 这种独立实验应用，才允许自带 GetMaterialApp。

9. 保持现有导航层级

• 这个项目的导航链路是固定三层：
  • AppHome 展示首页顶层分组
  • CatalogPage 展示分组列表
  • CatalogPage 内通过 AppNavigator.pushPath(item.path) 进入最终示例页
  • 最终示例页由当前启用的路由器提供
• 新增示例时不要随意改掉这三层结构，也不要把首页分组入口和最终示例页混成同一级。

10. 新增页面时同步文件

• 如果只是向现有分组新增页面，通常只需要更新对应分组下的 lib/demos/*/catalog.dart。
• 如果新增的是首页一级分组，还要同步更新：
  • lib/catalog/registry/catalog_registry.dart
  • 必要时检查 lib/app/router/app_router_config.dart

11. 完成后验证

• 优先运行：
  • fvm flutter analyze
  • fvm flutter test
• 如果改动了路由，至少验证：
  • 首页分组入口正常
  • CatalogPage 分组列表入口正常
  • 最终页面跳转正常

Constraints

• 默认优先生成 XxxDemoPage -> XxxDemoView。
• 只有在复杂场景下，才扩展为 xxx_example.dart + pages/ 等子目录。
• XxxDemoPage 不承载复杂页面 UI 和业务细节，但允许承载轻量注入、包裹层和必要生命周期逻辑。
• 只有在确实需要本地状态时，才让内层 XxxDemoView 或拆分后的页面组件使用 StatefulWidget。
• 只有在确实需要注入层生命周期管理、observer 恢复、全局包装恢复时，才让外层 XxxDemoPage 使用 StatefulWidget。
• 保持和现有 lib/demos/packages/toast_example.dart、lib/demos/packages/notification_example.dart、lib/demos/state_management/provider/provider_example.dart 一致的组织方式。