Flutter 教学项目 🚀

一个专业级的 Flutter 入门教学项目，采用业界最佳实践的项目架构，展示 Flutter 开发的核心概念。不仅仅是 Demo，而是一个可用于生产环境的项目模板！

📚 教学文档（必读）

🎯 根据你的水平选择：

完全小白？从这里开始 👇

📘 Flutter 零基础入门教程 ⭐⭐⭐⭐⭐
从目录结构开始，逐行讲解 main.dart、GetX、Widget 等核心概念
适合：完全没接触过 Flutter 的新手

有 Web 开发经验？看这个 👇

📗 从 Web 到 Flutter 指南 ⭐⭐⭐⭐⭐
React/Vue/uniapp → Flutter 的完整对比教程
适合：有 React、Vue、uniapp 基础的全栈开发者

想快速上手？看这个 👇

📦 项目结构说明 ⭐⭐⭐⭐⭐
详解专业项目架构、数据流向、目录设计
适合：想了解项目整体架构的开发者

想直接用代码？看这个 👇

🎯 使用示例手册 ⭐⭐⭐⭐⭐
各模块的实际使用代码、完整示例、最佳实践
适合：边看边写的实战派

✨ 项目特色

🏗️ 专业级项目架构

📂 清晰的目录结构：models/、services/、constants/、utils/ 完整分层
🎯 类型安全：完整的数据模型定义，告别 Map<String, dynamic>
🌐 模拟 API 层：无需后端即可学习前后端交互
🔧 工具函数库：15+ 验证器、20+ 格式化器，开箱即用
📝 常量管理：统一的颜色和文本管理，易于维护
🔐 完整认证系统：Apple 登录 + 邮箱登录 + LocalStorage 持久化
📊 专业日志：使用 logger 框架，彩色输出，生产级别

🎨 现代化 UI 设计

💎 Material Design 3：最新设计规范
🎯 三大 Icon 库：Iconsax、FontAwesome、Lucide Icons
💫 精美动画：flutter_animate + animated_text_kit + shimmer
📱 响应式适配：flutter_screenutil 多屏幕适配
🎨 shadcn/ui 风格：现代化表单设计（渐变、阴影、圆角）

🚀 学习友好

📦 4 大学习模块：基础组件、动画、表单、列表
🎓 7 个详情页面：完整的路由跳转演示
📘 7 份教学文档：从入门到精通（新增认证和日志文档）
🔗 GetX 全家桶：状态管理 + 路由 + 依赖注入
💡 代码注释丰富：每个文件都有详细说明
🍎 真实登录体验：Apple Sign In + SharedPreferences

📚 学习模块

应用采用底部 TabBar 导航，点击即可快速切换到不同的学习模块：

1️⃣ 基础组件 (蓝紫色 Tab)

学习 Flutter 的基本 Widget，包括：

🔘 各种按钮样式（Elevated、Filled、Outlined、Text Button）
📝 文本样式和排版
🎨 Icon 图标的使用（Iconsax + FontAwesome）
🎛️ 交互组件（计数器、开关、滑块）
📦 容器和布局（渐变、阴影等）

2️⃣ 动画效果 (粉红色 Tab)

探索 Flutter 的动画系统：

⚡ Flutter Animate 动画库（淡入、滑动、缩放）
💬 文字动画效果（打字机、淡入淡出、波浪）
✨ Shimmer 加载动画
🔄 交互式动画（可展开容器）
🎯 旋转和过渡效果

3️⃣ 表单与输入 (绿色 Tab)

掌握用户输入处理：

⌨️ 文本输入和实时验证
🔘 单选按钮和复选框
📊 滑块和评分组件
📋 下拉菜单选择器
📅 日期和时间选择器
✅ 完整的表单验证和提交流程

4️⃣ 列表与网格 (橙色 Tab)

学习数据展示（包含内部 Tab 导航）：

📜 基础 ListView 和可展开列表
🎴 卡片式列表（带操作按钮）
🔲 网格布局（GridView）
🎯 多样化的数据展示方式

🛠️ 技术栈

🎯 核心框架

GetX (^4.6.6) - 状态管理 + 路由 + 依赖注入三合一
flutter_screenutil (^5.9.0) - 响应式屏幕适配

🎨 UI 组件

Iconsax (^0.0.8) - 现代化、美观的图标库
FontAwesome (^10.7.0) - 流行的 FontAwesome 图标
Lucide Icons (^1.0.0) - 你熟悉的 Lucide 图标（Web 同款）
google_fonts (^6.2.1) - Google 字体库

🌈 动画库

flutter_animate (^4.5.0) - 强大的动画库
animated_text_kit (^4.2.2) - 文字动画效果
shimmer (^3.0.0) - 加载动画效果

🔧 工具库

gap (^3.0.1) - 简化间距的 widget
intl (^0.19.0) - 国际化和日期格式化
shared_preferences (^2.2.2) - 本地存储（相当于 localStorage）
sign_in_with_apple (^5.0.0) - Apple 登录
logger (^2.0.2) - 专业日志框架（美观、强大）

🚀 运行项目

快速开始：

# 使用 Makefile（推荐）
make install      # 安装依赖
make run          # 运行项目

# 或使用原生命令
flutter pub get   # 安装依赖
flutter run       # 运行项目

详细步骤：

确保已安装 Flutter SDK
克隆或下载本项目
安装依赖：
```
make install
# 或
flutter pub get
```
启动模拟器或连接真机
运行项目：
```
make run
# 或
flutter run
```

📖 更多命令请查看：开发命令速查手册

📱 支持的平台

✅ iOS
✅ Android
✅ Web
✅ macOS
✅ Windows
✅ Linux

💡 学习建议

📚 对于有 Web 开发经验的你：

强烈建议先阅读：📖 Flutter 入门指南

这份指南详细讲解了：

✅ Flutter vs HTML/CSS/JS 的核心区别
✅ Widget 树 vs Virtual DOM
✅ GetX vs React Hooks/Vue Composition API
✅ 链式编程详解
✅ 动画系统对比（flutter_animate vs Framer Motion）
✅ 完整的代码对比示例

使用技巧：

📱 底部导航：点击底部的任意 Tab 即可切换模块
🎯 状态保持：切换 Tab 不会丢失当前页面的状态（IndexedStack）
💾 独立学习：每个模块都可以独立学习，互不影响
🎨 颜色识别：每个 Tab 都有独特的主题色，方便识别
🔗 路由跳转：在"基础组件"和"列表与网格"中体验页面跳转

📖 完整文档体系

📚 核心教程（7份）

文档	说明	适合人群
📘 Flutter 零基础入门	从零开始学 Flutter	完全小白
📗 从 Web 到 Flutter	React/Vue → Flutter	有前端基础
📦 项目结构说明	专业架构详解	所有开发者 ⭐
🎯 使用示例手册	实战代码示例	动手实践派 ⭐
📖 Widget 速查手册	Widget vs Web 对照	快速查阅
🔧 命令速查手册	开发命令大全	终端操作
📊 日志框架指南	Logger 使用教程	日志记录 ⭐ 新增

官方文档：

图标库：

🎯 你将学会什么？

📱 Flutter 基础

✅ Widget 的使用和组合（一切皆 Widget）
✅ 底部导航栏的实现（TabBar + IndexedStack）
✅ 动画和过渡效果（flutter_animate 链式编程）
✅ 表单处理和验证（现代化 shadcn/ui 风格）
✅ 列表和网格布局（ListView + GridView）
✅ 响应式屏幕适配（flutter_screenutil）
✅ Material Design 3 设计规范

🚀 GetX 全家桶

✅ 状态管理：简单状态（.obs）、复杂状态（列表）、全局状态
✅ 路由管理：页面跳转、参数传递、命名路由、返回导航
✅ 依赖注入：Get.put()、Get.find()、控制器管理

🔐 认证系统（完整实现）

✅ Apple 登录：真实的 Apple Sign In（iOS/macOS）
✅ 邮箱登录：用于测试（所有平台）
✅ 自动登录：启动时检查 SharedPreferences
✅ 用户信息持久化：Token、角色、头像、深色模式偏好
✅ 退出登录：清除本地数据，跳转登录页

🏗️ 专业项目架构（重点）

✅ 分层架构：Model → Service → Controller → View
✅ 数据模型：类型安全的数据定义（告别 dynamic）
✅ API 服务层：前后端分离架构（虽然是模拟 API）
✅ 常量管理：统一的颜色和文本管理
✅ 工具函数：表单验证、数据格式化（可复用）

🎨 对比 Web 开发

✅ Flutter vs HTML/CSS/JS 的核心区别
✅ Widget vs React Component / Vue Component
✅ GetX vs React Hooks / Vuex / Pinia
✅ 链式编程 vs 函数式编程
✅ 响应式状态 vs React useState / Vue ref()

🏗️ 项目结构（专业级架构）

lib/
├── main.dart                         ← 应用入口（认证检查 + GetX 初始化）
│
├── screens/                          ← 页面级组件（相当于 Web 的 pages/）
│   ├── auth/                         ← 认证页面 ⭐ 新增
│   │   └── login_screen.dart         ← 登录页（Apple + 邮箱登录）
│   ├── home_screen.dart              ← 主页（底部导航 + 购物车 + 抽屉）
│   ├── basic_widgets_screen.dart     ← Tab 1: 基础组件
│   ├── animations_screen.dart        ← Tab 2: 动画效果
│   ├── forms_screen.dart             ← Tab 3: 表单输入
│   ├── lists_screen.dart             ← Tab 4: 列表网格
│   └── details/                      ← 详情页面（7个演示页）
│       ├── product_detail_screen.dart
│       ├── user_profile_screen.dart
│       ├── settings_screen.dart
│       ├── about_screen.dart
│       ├── counter_demo_screen.dart
│       └── cart_demo_screen.dart
│
├── widgets/                          ← 可复用组件（相当于 components/）
│   └── app_drawer.dart               ← 全局抽屉（用户信息 + 菜单）
│
├── controllers/                      ← 状态管理（相当于 store/）
│   ├── auth_controller.dart          ← 认证状态（登录/用户/深色模式） ⭐ 核心
│   ├── cart_controller.dart          ← 购物车状态
│   └── counter_controller.dart       ← 计数器状态
│
├── models/                           ← 数据模型（相当于 types/）
│   ├── cart_item.dart                ← 购物车商品模型
│   ├── product.dart                  ← 商品模型
│   └── user.dart                     ← 用户模型
│
├── services/                         ← API 服务（相当于 api/）
│   ├── api_service.dart              ← 基础 API 服务
│   ├── auth_service.dart             ← 认证服务（Apple + 邮箱 + LocalStorage） ⭐ 新增
│   ├── product_service.dart          ← 商品 API（8个模拟数据）
│   └── user_service.dart             ← 用户 API（登录/注册）
│
├── routes/                           ← 路由配置（相当于 router/）
│   ├── app_routes.dart               ← 路由常量
│   └── app_pages.dart                ← 路由映射
│
├── constants/                        ← 常量配置
│   ├── colors.dart                   ← 颜色常量（30+ 个，已应用）
│   └── strings.dart                  ← 文本常量（128 行，已应用）
│
└── utils/                            ← 工具函数
    ├── validators.dart               ← 表单验证（15+ 验证器）
    ├── formatters.dart               ← 数据格式化（20+ 格式化器）
    └── logger.dart                   ← 日志工具（logger 框架封装） ⭐ 新增

📘 详细说明：项目结构文档

🎨 设计特点

底部导航栏：现代化的 Tab 设计，每个 Tab 有独特的颜色标识
彩色背景高亮：选中的 Tab 会显示半透明的彩色背景
流畅动画：Tab 切换时有轻微的缩放动画效果
状态保持：使用 IndexedStack 保持每个页面的状态
GetX 路由：页面跳转动画流畅，支持参数传递
响应式适配：自动适配不同屏幕尺寸
Material Design 3：遵循最新的 Material 设计规范

🚀 核心功能演示

🔐 认证系统（完整流程）

登录页面 - Apple 登录 + 邮箱登录
- 📁 文件：screens/auth/login_screen.dart
- 🎯 特性：表单验证、加载状态、错误处理
- 🍎 Apple 登录仅 iOS/macOS 可用
认证服务 - SharedPreferences 持久化
- 📁 文件：services/auth_service.dart
- 💾 存储：Token、用户信息、深色模式偏好
- 🔄 自动登录：启动时检查登录状态
认证控制器 - 全局状态管理
- 📁 文件：controllers/auth_controller.dart
- 🎯 对应：React Context + LocalStorage, Pinia + Persist

📦 状态管理示例

购物车演示 - 复杂的列表状态管理
- 📁 文件：controllers/cart_controller.dart
- 🎯 对应：Zustand store, Pinia store
计数器演示 - 简单的响应式状态（.obs）
- 📁 文件：controllers/counter_controller.dart
- 🎯 对应 React: useState, Vue: ref()

路由跳转示例：

基础跳转 - Get.toNamed('/page')
- 📁 使用：basic_widgets_screen.dart 第 281 行
- 🎯 对应：navigate('/page'), router.push('/page')
参数传递 - Get.toNamed('/detail', arguments: data)
- 📁 使用：lists_screen.dart 第 246 行
- 🎯 对应：navigate('/detail', { state: data })
返回跳转 - Get.back()
- 🎯 对应：navigate(-1), router.back()
页面过渡 - 多种过渡动画效果
- 📁 配置：routes/app_pages.dart
- 🎯 对应：Framer Motion 页面过渡

在哪里体验？

📱 基础组件 Tab：底部有"GetX 路由跳转"演示区（3 个跳转按钮）
📱 列表与网格 Tab：点击任意产品卡片查看详情（参数传递）
📱 详情页面有完整的购物车、用户资料等功能

🎨 代码风格：现代化设计

shadcn/ui 风格的 Flutter 实现

本项目的表单页面（forms_screen.dart）参考了 shadcn/ui 的设计理念：

✅ 微妙阴影 - BoxShadow 增加深度感
✅ 渐变背景 - LinearGradient 增加视觉吸引力
✅ 聚焦状态 - focusedBorder 明确交互反馈
✅ 圆角统一 - 14-16px 统一圆角设计
✅ 渐入动画 - .animate().fadeIn() 流畅过渡
✅ 响应式交互 - InkWell 水波纹效果

链式编程示例

// 链式动画（forms_screen.dart）
_buildModernTextField(...)
  .animate()
  .fadeIn(delay: 100.ms)      // 100ms 后淡入
  .slideX(begin: -0.1)         // 从左滑入

// 链式时间（Duration 扩展）
Duration(milliseconds: 500)  →  500.ms
Duration(seconds: 2)         →  2.seconds

🎓 Web 开发者的 Flutter 速查表

React → Flutter 映射表

// React
const [count, setCount] = useState(0);
setCount(count + 1);
{count}

// Flutter GetX
var count = 0.obs;
count++;
Obx(() => Text('${count}'))

// React Router
navigate('/detail', { state: { id: 1 } })

// Flutter GetX
Get.toNamed('/detail', arguments: { 'id': 1 })

// React + Framer Motion
<motion.div animate={{ opacity: 1 }}>

// Flutter + flutter_animate
Container(...).animate().fadeIn()

Vue → Flutter 映射表

// Vue Composition API
const count = ref(0);
count.value++;

// Flutter GetX
var count = 0.obs;
count++;  // 完全一样！

// Vue Router
router.push({ name: 'detail', params: { id: 1 } })

// Flutter GetX
Get.toNamed('/detail', arguments: { 'id': 1 })

🌟 核心亮点

1️⃣ 完整的认证系统

// Apple 登录（真实）
final user = await authService.signInWithApple();
// ↑ 调起真实的 Apple ID 登录界面

// 邮箱登录（测试）
final user = await authService.signInWithEmail(email, password);

// 自动保存到 SharedPreferences
{
  'is_logged_in': true,
  'token': 'token_xxx',
  'user_name': 'Apple 用户',
  'user_email': 'user@example.com',
  'user_avatar': '🍎',
  'is_dark_mode': false,
}

// 启动时自动检查
await authController.checkLoginStatus();
// 已登录 → 直接进入主页
// 未登录 → 显示登录页

2️⃣ 类型安全的数据模型

// ❌ 之前：使用 Map（不安全）
final product = {'name': 'iPhone', 'price': 8999};
final name = product['name'];  // dynamic 类型

// ✅ 现在：使用 Model（类型安全）
final product = Product(name: 'iPhone', price: 8999);
final name = product.name;  // String 类型 ✅

3️⃣ 模拟 API 服务层

// 无需真实后端，模拟网络请求
final products = await ProductService().getProducts();
// ↑ 自动延迟 800ms，返回 8 个测试商品

// 模拟用户登录
final user = await UserService().login(email, password);

4️⃣ 统一的常量管理

// 所有颜色统一管理
Container(color: AppColors.primary)  // 蓝紫色
Container(color: AppColors.tab1)     // Tab 1 专属色

// 所有文本统一管理
Text(AppStrings.buttonConfirm)  // "确认"
Text(AppStrings.errorRequired)  // "此字段不能为空"

5️⃣ 实用工具函数

// 表单验证（15+ 验证器）
TextFormField(validator: Validators.email)
TextFormField(validator: Validators.phone)
TextFormField(validator: Validators.password)

// 数据格式化（20+ 格式化器）
Formatters.currency(8999.00)        // ¥8,999.00
Formatters.relativeTime(date)       // 2小时前
Formatters.phoneWithMask('138...')  // 138****5678

// 日志记录（logger 框架）
Log.d('调试信息');     // 💙 Debug
Log.i('流程信息');     // 💚 Info
Log.w('警告信息');     // 💛 Warning
Log.e('错误信息', e);  // ❤️ Error

6️⃣ 专业日志框架

// ❌ 之前：使用 print()
print('检查登录状态失败: $e');
// 输出：检查登录状态失败: Exception: Network error

// ✅ 现在：使用 logger
Log.e('检查登录状态失败', e);
// 输出：
// [00:01:23.456] ❤️ ERROR │ 检查登录状态失败
//                        ├─ Exception: Network error
//                        └─ at AuthController.checkLoginStatus

🚀 快速开始

1. 安装依赖

make install
# 或
flutter pub get

2. 运行项目

make run
# 或
flutter run

3. 开始学习

🔐 启动应用，体验登录功能（邮箱：test@example.com，密码：123456）
📖 阅读项目结构说明了解整体架构
🎯 查看使用示例手册学习如何使用
💻 打开 lib/services/auth_service.dart 查看认证流程
🎨 打开 lib/constants/colors.dart 自定义主题色
✅ 打开 lib/utils/validators.dart 学习表单验证
📊 打开 lib/utils/logger.dart 学习日志记录

💡 推荐学习路径

1. 🔐 体验登录功能
   ↓ 理解认证流程和 SharedPreferences
   
2. 📦 项目结构说明 (PROJECT_STRUCTURE.md)
   ↓ 了解整体架构和数据流向
   
3. 🎯 使用示例手册 (USAGE_EXAMPLES.md)
   ↓ 学习各模块的实际使用
   
4. 📗 从 Web 到 Flutter (FLUTTER_GUIDE.md)
   ↓ 理解 Flutter vs Web 的差异
   
5. 📖 Widget 速查手册 (WIDGET_REFERENCE.md)
   ↓ 快速查找 Widget 用法
   
6. 🔧 命令速查手册 (COMMANDS.md)
   ↓ 掌握开发命令
   
7. 📊 日志框架指南 (LOGGING.md)
   ↓ 学习专业的日志记录

🔐 认证功能测试

方法 1：邮箱登录（推荐，所有平台可用）

邮箱：test@example.com（或任意邮箱格式）
密码：123456（至少 6 位）

方法 2：Apple 登录（仅 iOS/macOS）

在 Xcode 中配置 Sign in with Apple
点击"使用 Apple 账号登录"
使用真实 Apple ID 登录
授权后自动跳转主页

配置 Apple 登录：

Xcode → Runner target → Signing & Capabilities
点击 + Capability → 添加 Sign in with Apple

📞 获取帮助

📚 查看 docs/ 目录下的 7 份完整文档
💬 阅读代码中的详细注释
🔍 使用 grep 搜索相关代码示例
📊 查看日志框架指南学习日志记录

🎁 项目亮点总结

🔐 完整认证系统（Apple + 邮箱 + 自动登录）
💾 数据持久化（SharedPreferences）
🎨 常量管理（30+ 颜色、128 行文本）
📊 专业日志（logger 框架，彩色输出）
🏗️ 8 层目录结构（screens、widgets、controllers、models、services、routes、constants、utils）
📘 7 份教学文档（从入门到精通）
🔧 35+ 工具函数（15 验证器 + 20 格式化器）

祝你学习愉快！💪

🌟 记得先登录体验，然后阅读：项目结构说明

Name		Name	Last commit message	Last commit date
Latest commit History 11 Commits
android		android
docs		docs
ios		ios
lib		lib
linux		linux
macos		macos
test		test
web		web
windows		windows
.gitignore		.gitignore
.metadata		.metadata
Makefile		Makefile
README.md		README.md
analysis_options.yaml		analysis_options.yaml
pubspec.lock		pubspec.lock
pubspec.yaml		pubspec.yaml

Folders and files

Latest commit

History

Repository files navigation