readful/learning_docs/01_项目结构与环境配置.md

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

一、项目创建与验证

1. 执行命令

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. 基础配置说明

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. 依赖管理常用命令

flutter pub get                  # 下载pubspec.yaml中的依赖
flutter pub add <package_name>   # 添加新依赖包
flutter pub upgrade              # 升级所有依赖包

---

四、main.dart 入口代码详细解析

1. 核心概念

Flutter的一切都是Widget（组件）：

• StatelessWidget（无状态组件）：UI不随数据变化，如静态文本、图标
• StatefulWidget（有状态组件）：UI随数据变化，如计数器、电子书阅读进度

2. 关键代码逐行解释

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. 常用开发命令

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是单个页面的基础布局，提供导航栏、主体区域等页面结构。