25b7c5ae35
主要功能： - ✅ 完成Book模型（电子书基本信息管理） - ✅ 完成Highlight模型（文本高亮功能） - ✅ 建立Flutter数据模型设计标准 技术特点： - 采用不可变对象设计模式 - 实现完整的序列化支持（toMap/fromMap） - 提供便利的工厂构造函数 - 正确处理枚举类型序列化 - 完善的空值安全处理 学习文档： - 📚 项目结构与环境配置指南 - 🎯 数据模型设计思路分析 - 💡 Flutter数据模型最佳实践 下一步： - 实现Annotation批注模型 - 设计本地存储方案 - 开始UI组件开发 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
198 lines
8.0 KiB
Markdown
198 lines
8.0 KiB
Markdown
# 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是单个页面的基础布局，提供导航栏、主体区域等页面结构。 |