# Flutter 电子书阅读器项目 - 01：项目结构与环境配置

## 一、项目创建与验证
### 1. 执行命令
```bash
flutter create readful    # 创建项目
cd readful               # 进入项目目录
flutter run              # 运行项目
```

### 2. 成功标志
- 终端显示「Connected device」或检测到模拟器/真机
- 能看到Flutter默认的计数器界面
- `flutter doctor` 中所有检查项都是绿色对勾

---

## 二、Flutter项目核心结构解析
| 目录/文件 | 作用说明 | 是否经常修改 |
|-----------|---------|-------------|
| `lib/main.dart` | 应用入口文件，所有Flutter程序的起点 | ✅ 经常修改 |
| `pubspec.yaml` | 项目配置文件，管理依赖、资源、版本号 | ✅ 经常修改 |
| `lib/` | 存放所有Dart源代码的核心目录 | ✅ 经常修改 |
| `assets/` | 静态资源目录（图片、字体、电子书文件） | ✅ 经常修改 |
| `android/` | Android平台原生代码 | ⚠️ 偶尔修改 |
| `ios/` | iOS平台原生代码 | ⚠️ 偶尔修改 |
| `test/` | 单元测试文件 | ⚠️ 开发后期使用 |

> 💡 **小白提示**：作为Flutter初学者，你主要关注 `lib/` 目录、`pubspec.yaml` 文件和 `assets/` 目录即可。

---

## 三、pubspec.yaml 配置文件详解
### 1. 基础配置说明
```yaml
name: readful                    # 项目名称（小写+下划线）
description: 电子书阅读器        # 项目描述
version: 1.0.0+1                # 版本号（1.0.0是版本，+1是构建号）

environment:                     # Flutter和Dart版本要求
  sdk: '>=3.0.0 <4.0.0'         # Dart SDK版本范围

dependencies:                    # 生产环境依赖（用户安装的包）
  flutter:
    sdk: flutter                # Flutter框架核心（必须）
  cupertino_icons: ^1.0.2       # iOS风格图标库

dev_dependencies:                # 开发环境依赖（开发工具）
  flutter_test:
    sdk: flutter                # 测试框架
  flutter_lints: ^2.0.0         # 代码规范检查工具

flutter:                         # Flutter特定配置
  uses-material-design: true     # 启用Material Design图标库
  # assets:                      # 资源配置（后续添加）
  #   - assets/images/
  #   - assets/books/
```

### 2. 依赖管理常用命令
```bash
flutter pub get                  # 下载pubspec.yaml中的依赖
flutter pub add <package_name>   # 添加新依赖包
flutter pub upgrade              # 升级所有依赖包
```

---

## 四、main.dart 入口代码详细解析
### 1. 核心概念
**Flutter的一切都是Widget（组件）**：
- **StatelessWidget（无状态组件）**：UI不随数据变化，如静态文本、图标
- **StatefulWidget（有状态组件）**：UI随数据变化，如计数器、电子书阅读进度

### 2. 关键代码逐行解释
```dart
import 'package:flutter/material.dart';  // 引入Material Design组件库

void main() {                           // Dart程序入口点（固定写法）
  runApp(const MyApp());                // 启动Flutter应用，传入根组件
}

class MyApp extends StatelessWidget {   // 定义根组件（无状态）
  const MyApp({super.key});             // 构造函数

  @override                              // 重写父类方法
  Widget build(BuildContext context) {   // 构建UI的核心方法（自动调用）
    return MaterialApp(                  // Material Design应用容器
      title: 'Readful',                // 应用标题（在任务管理器显示）
      theme: ThemeData(                 // 应用主题配置
        primarySwatch: Colors.blue,    // 主题颜色
      ),
      home: const MyHomePage(title: 'Readful 电子书阅读器'),  // 首页组件
    );
  }
}

class MyHomePage extends StatefulWidget {  // 首页组件（有状态）
  const MyHomePage({super.key, required this.title});  // 构造函数

  final String title;                     // 组件属性（从外部传入）

  @override
  State<MyHomePage> createState() => _MyHomePageState();  // 创建状态管理对象
}

class _MyHomePageState extends State<MyHomePage> {  // 状态管理类
  int _counter = 0;                      // 状态变量（存储组件数据）

  void _incrementCounter() {             // 状态更新方法
    setState(() {                        // 关键！调用setState更新状态
      _counter++;                        // 修改状态变量
    });                                  // 会自动触发build()重新构建UI
  }

  @override
  Widget build(BuildContext context) {   // 构建UI方法
    return Scaffold(                     // 页面基础布局组件
      appBar: AppBar(                    // 顶部导航栏
        title: Text(widget.title),       // 使用父组件传入的title属性
      ),
      body: Center(                      // 页面主体内容
        child: Column(                   // 垂直排列组件
          mainAxisAlignment: MainAxisAlignment.center,  // 垂直居中
          children: <Widget>[            // 子组件列表
            const Text(
              '点击次数：',              // 静态文本
            ),
            Text(
              '$_counter',               // 显示状态变量（动态变化）
              style: Theme.of(context).textTheme.headlineMedium,  // 使用主题字体
            ),
          ],
        ),
      ),
      floatingActionButton: FloatingActionButton(  // 悬浮操作按钮
        onPressed: _incrementCounter,    // 点击事件绑定
        tooltip: '增加',                 // 长按提示文本
        child: const Icon(Icons.add),    // 按钮图标
      ),
    );
  }
}
```

### 3. 关键API和组件说明
| 组件/API | 作用 | 使用场景 |
|---------|------|---------|
| `MaterialApp` | Material Design应用容器 | 几乎所有Flutter应用的根组件 |
| `Scaffold` | 页面基础布局 | 提供导航栏、主体、浮动按钮等页面结构 |
| `AppBar` | 顶部导航栏 | 显示页面标题和操作按钮 |
| `Center` | 居中布局 | 让子组件在父组件中居中显示 |
| `Column` | 垂直布局 | 子组件从上到下排列 |
| `Text` | 文本显示 | 显示各种文字内容 |
| `FloatingActionButton` | 悬浮按钮 | 页面右下角的圆形操作按钮 |
| `setState()` | 状态更新 | 更新StatefulWidget的状态数据 |
| `Theme.of(context)` | 获取主题 | 访问应用的颜色、字体等主题配置 |

---

## 五、学习要点总结
### 1. Flutter开发特点
- **声明式UI**：描述UI应该长什么样，而不是如何操作DOM
- **Widget组合**：复杂界面由简单Widget组合而成
- **热重载**：修改代码后可立即看到效果，无需重新编译

### 2. 常用开发命令
```bash
flutter run                          # 运行应用
flutter devices                       # 查看可用设备
flutter clean                        # 清理构建缓存
flutter pub get                      # 获取依赖
```

### 3. 调试技巧
- 使用 `print()` 输出调试信息
- 利用热重载（按R键）快速测试UI修改
- 通过 `debugPrint()` 输出性能相关的调试信息

---

## 下一步学习重点
1. **数据模型设计**：如何表示电子书、章节、阅读进度等
2. **本地存储**：使用Hive或SharedPreferences存储数据
3. **UI组件**：学习更多Flutter内置组件构建电子书界面
4. **状态管理**：学习更复杂的状态管理方案

---

## 常见问题解答
**Q：为什么要区分StatelessWidget和StatefulWidget？**
A：StatelessWidget性能更好，适用于静态内容；StatefulWidget适用于需要根据用户交互或数据变化更新UI的场景。

**Q：setState()的作用是什么？**
A：通知Flutter框架"这个组件的状态发生了变化，需要重新构建UI"。如果不调用setState()，即使修改了状态变量，UI也不会更新。

**Q：MaterialApp和Scaffold有什么区别？**
A：MaterialApp是整个应用的容器，提供路由、主题等全局功能；Scaffold是单个页面的基础布局，提供导航栏、主体区域等页面结构。