《构建高质量 Flutter 应用：从模块化基础模板到可扩展架构实践》- 适配开源鸿蒙版

在这里插入图片描述

• 个人首页： VON
• 鸿蒙系列专栏： 鸿蒙开发小型案例总结
• 综合案例 ：鸿蒙综合案例开发
• 鸿蒙6.0：从0开始的开源鸿蒙6.0.0
• 鸿蒙5.0：鸿蒙5.0零基础入门到项目实战
• Electron适配开源鸿蒙专栏：Electron for OpenHarmony
• 本文章所属专栏：Flutter for OpenHarmony
• 文章AtomGit地址：Template_V1.0

🧱 一、整体架构设计理念

该模板遵循 “清晰分层 + 预留扩展” 的原则，目标是：

• ✅ 快速启动一个符合 Flutter 最佳实践的项目；
• ✅ 模块职责分明，便于团队协作；
• ✅ 不引入冗余依赖，保持轻量；
• ✅ 为状态管理、国际化、深色模式、多页面等常见需求预留接口。

这种“骨架先行”的方式非常适合用于企业级项目或长期维护的 MVP（最小可行产品）开发。

📁 二、目录结构详解

lib/
├── main.dart               # 应用入口
├── app.dart                # 根组件：主题、路由、全局配置
├── constants/              # 全局常量（颜色、尺寸、字符串等）
│   └── app_colors.dart
├── screens/                # 页面级组件（每个屏幕一个文件）
│   └── home_screen.dart
├── widgets/                # 可复用 UI 组件
│   └── app_bar_title.dart
└── utils/                  # 工具类（日志、格式化、设备判断等）
    └── logger.dart         # 预留

💡 为什么这样分？

• screens/ 与 widgets/ 分离：页面负责业务逻辑，组件专注 UI 复用。
• constants/ 集中管理设计系统变量，便于后期接入 Design Token。
• utils/ 为通用逻辑（如时间格式、网络工具）提供存放地。

🚪 三、入口文件：main.dart

import 'package:flutter/material.dart';
import 'app.dart';

void main() {
  runApp(const MyApp());
}

• 使用 runApp() 启动应用；
• 传入根组件 MyApp（无状态，性能更优）；
• 未包裹任何状态管理器（如 ProviderScope），为后续按需引入留白。

🔜 扩展提示：未来若使用 Riverpod，只需在此处改为：

runApp(ProviderScope(child: MyApp()));

🎨 四、根组件：app.dart

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

  static bool get isDarkMode => false; // ← 预留开关

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'My App',
      debugShowCheckedModeBanner: false,
      theme: ThemeData(...),
      darkTheme: ThemeData(...),
      themeMode: isDarkMode ? ThemeMode.dark : ThemeMode.light,
      home: const HomeScreen(),
    );
  }
}

关键设计点：

1. 双主题支持：
   • theme：浅色主题；
   • darkTheme：深色主题；
   • themeMode：动态切换依据（当前硬编码为 false，但结构已支持动态切换）。
2. Material 3 支持：
   • useMaterial3: true 确保使用最新 Material Design 规范。
3. 路由预留：
   • 注释中提示可添加 routes 或未来改用 GoRouter。

🔜 扩展路径：

• 将 isDarkMode 改为从 SharedPreferences 读取；
• 通过状态管理（如 Riverpod）监听用户切换操作，动态更新 themeMode。

🎨 五、常量管理：constants/app_colors.dart

class AppColors {
  static const primary = Color(0xFF1976D2);
  static const secondary = Color(0xFF424242);
}

• 虽然当前未在主题中使用，但为将来自定义 ThemeData 提供统一颜色源；
• 避免“魔法值”散落在代码各处，提升可维护性。

✅ 最佳实践：后续可结合 Figma 设计系统，生成完整的 AppColors、AppSpacing、AppTextStyles。

🧩 六、可复用组件：widgets/app_bar_title.dart

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

  @override
  Widget build(BuildContext context) {
    return Text(
      title,
      style: Theme.of(context).textTheme.titleLarge?.copyWith(
            fontWeight: FontWeight.bold,
          ),
    );
  }
}

• 抽离 AppBar 标题为独立组件，避免重复写样式；
• 自动适配当前主题（亮/暗）下的文字风格；
• 使用 required 参数确保调用时不会遗漏标题内容。

💡 这种“小而专”的组件是构建大型应用 UI 的基石。

🏠 七、主页实现：screens/home_screen.dart

这是一个典型的 StatefulWidget 示例，包含：

• 计数器状态 _counter；
• setState 触发 UI 更新；
• 响应式布局（Center + Column 适配手机/平板）；
• 同时提供 ElevatedButton 和 FloatingActionButton 两种交互方式。

亮点细节：

主题感知文本：

style: Theme.of(context).textTheme.headlineMedium

确保字体大小、颜色随主题自动变化。

语义化结构：

• 使用 SizedBox 控制间距，而非硬编码 padding；
• 按钮使用 ElevatedButton.icon，符合 Material 指南。

⚠️ 当前局限：状态仅限本地。一旦页面重建或跳转，计数会重置。 ✅ 解决方案：引入状态管理（见下文）。

🛠️ 八、pubspec.yaml 配置说明

environment:
  sdk: '>=3.0.0 <4.0.0'  # 使用 Dart 3，支持 records、patterns 等新特性

dependencies:
  flutter:
    sdk: flutter
  cupertino_icons: ^1.0.6  # iOS 风格图标（虽未用，但保留兼容性）

dev_dependencies:
  flutter_lints: ^3.0.0   # 官方推荐代码规范检查

• 不预装 Dio、SharedPrefs 等：避免“过度工程”，按需添加；
• 启用 uses-material-design: true：确保 Material 图标可用。

测试

在这里插入图片描述

🚀 九、未来扩展路线图（2.0+ 升级建议）

✅ 总结

这个 Flutter 1.0 基础模板虽小，却“五脏俱全”：

• 结构清晰：分层合理，职责单一；
• 主题友好：原生支持亮/暗模式；
• 扩展性强：每一处都为未来升级埋下伏笔；
• 零冗余：没有为了“可能用到”而提前引入复杂库。

它不是功能最全的脚手架，而是最干净、最克制、最面向未来的起点。无论是个人项目、创业 MVP，还是企业级应用，都可以以此为基础，稳步演进。

🌟 建议：将此模板保存为公司/团队的 Flutter Starter Kit，统一开发规范，提升交付效率。