# flutter-roadmap-2025

**Repository Path**: CodingGorit/flutter-roadmap-2025

## Basic Information

- **Project Name**: flutter-roadmap-2025
- **Description**: A repository showcasing my journey to mastering Flutter, including all my projects and code backups.
学习 Flutter 之路，从入门到进阶到精通
- **Primary Language**: Dart
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 2
- **Forks**: 0
- **Created**: 2025-03-21
- **Last Updated**: 2026-04-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: Flutter

## README

# flutter-roadmap-2025

## 项目介绍

**flutter-roadmap-2025** - 展示我的 Flutter 学习之旅，包含所有项目和代码备份。  
从入门到进阶到精通的学习路径。

**当前 SDK 版本：**
- Flutter 3.27.5-ohos-1.0.4
- Dart 3.6.2

---

## 目录

1. [项目结构](#项目结构)
2. [示例项目](#示例项目)
3. [Dart 基础示例](#dart-基础示例)
4. [Flutter 学习资源](#flutter-学习资源)
5. [常用命令整理](#常用命令整理)
6. [OpenHarmony 开发指南](#openharmony-开发指南)
7. [Flutter 踩坑记录](#flutter-踩坑记录)
8. [开发技巧](#开发技巧)
9. [相关资源](#相关资源)
10. [学习建议](#学习建议)

---

## 项目结构

```
flutter-roadmap-2025/
├── dart_samples/              # Dart 语言基础示例
│   └── basic/                 # 基础语法练习
├── flutter_samples/           # Flutter 应用示例
│   ├── flutter_first_application/   # 第一个 Flutter 应用
│   ├── flutter_layout_application/  # 布局练习应用
│   ├── flutter_web_application/     # Web 应用示例
│   └── flutter-oh-app/              # OpenHarmony 示例应用
├── flutter_service/           # Flutter 服务示例
│   └── flutter_test_background_service/  # 后台服务测试
└── assets/                    # 项目截图资源
```

---

## 示例项目

### 1. flutter_first_application

第一个 Flutter 应用，展示基础组件使用。

**运行截图：**
- [首页](./assets/flutter_first_application/home_page.png)
- [收藏页](./assets/flutter_first_application/favorite_page..png)

### 2. flutter_layout_application

布局练习应用，包含多种布局组件的使用示例。

**功能：**
- GridView 卡片布局
- 分类导航抽屉
- 详情预览页面

**运行截图：**
- [主页](./assets/flutter_layout_application/home.png)
- [预览页](./assets/flutter_layout_application/preview.png)

### 3. flutter_web_application

Web 应用示例，包含登录注册和简历展示功能。

**功能：**
- 表单验证（登录/注册）
- 路由导航
- 本地存储（shared_preferences）
- 可选择文本（SelectableText）

**运行截图：**
- [登录页](./assets/flutter_web_application/index.png)

### 4. flutter-oh-app

OpenHarmony 平台示例应用，采用分层架构设计。

**架构特点：**
| 层级 | 说明 |
|------|------|
| UI Layer | 页面和组件 |
| Logic Layer | ViewModel 状态管理 |
| Data Layer | Models、Repositories、Services |

**验证技能：**
| Skill | Status |
|-------|--------|
| flutter-architecting-apps | ✅ Passed |
| flutter-building-layouts | ✅ Passed |
| flutter-managing-state | ✅ Passed |
| flutter-handling-http-and-json | ✅ Passed |

---

## Dart 基础示例

`dart_samples/basic/` 目录包含 Dart 语言基础练习：

| 文件 | 内容 |
|------|------|
| `async_basic.dart` | 异步基础 |
| `async_error.dart` | 异步错误处理 |
| `async_parallel.dart` | 并行异步 |
| `async_stream.dart` | Stream 流处理 |
| `classes.dart` | 类定义 |
| `enums.dart` | 枚举类型 |
| `exception_handling.dart` | 异常处理 |
| `extensions.dart` | 扩展方法 |
| `generics.dart` | 泛型 |
| `getter_setter.dart` | getter/setter |
| `optional_parameters.dart` | 可选参数 |

---

## Flutter 学习资源

### 一、学习路线

一切以官方为主：[Flutter 官网](https://flutter.dev)

#### 1.1 基础学习

1. **[Dart 语言基础](https://dart.cn/language/)**【类的定义、类的继承、异步】
   - [给 JavaScript 开发者的 Dart 编程指南](https://dart.cn/guides/language/coming-from/js-to-dart/)
   
2. **[学习 Flutter](https://docs.flutter.cn/get-started/learn-flutter)**
   - [给 web 开发者的学习指南](https://docs.flutter.cn/get-started/flutter-for/web-devs)
   - Flutter Widget 学习

3. **Flutter 状态管理**
   - [Flutter 自带的状态管理](https://docs.flutter.cn/get-started/fundamentals/state-management#learn-more-about-state-management)
   - [bloc](https://bloclibrary.dev/#/coreconcepts)
   - [Provider](https://pub.dev/packages/provider)

4. **测试、性能优化**
5. **Flutter 编译成鸿蒙 app 及 其他 app**
6. **[Flutter FAQ](https://docs.flutter.cn/resources/faq)**

**补充资料:**
- [Flutter widgets 参考](https://docs.flutter.cn/reference/widgets)

#### 1.2 进阶学习

1. **Flutter Firebase 框架**
2. **Dart 高级语法，后端开发**

### 二、项目实战

1. **[你的第一个 Flutter 应用](https://codelabs.developers.google.cn/codelabs/flutter-codelab-first?hl=zh-cn)**
2. **[Flutter layout 练习](https://docs.flutter.cn/ui/layout/tutorial)**
3. **[Flutter Codelabs](https://docs.flutter.cn/codelabs)**
4. **[Flutter cookbook](https://docs.flutter.cn/cookbook)**
5. **[Flutter 实战 2](https://book.flutterchina.club/)**

### 三、Flutter 社区

1. **[StackOverflow](https://stackoverflow.com/questions/tagged/flutter)**
2. **[Flutter 社区](https://flutter.dev/community)**
3. **[掘金 Flutter](https://juejin.cn/tag/Flutter)**

---

## 常用命令整理

```shell
# 创建 package 项目
flutter create --platforms ohos,android,ios multi_entry_ohos

# 创建 plugin 项目
flutter create --platforms ohos,android,ios multi_entry_ohos --template=plugin

# 添加平台支持（插件）
flutter create -t plugin --platforms <platforms>

# 环境检测
flutter doctor

# 列出已连接设备
flutter devices

# 构建 HAP 包（OpenHarmony）
flutter build hap --debug
flutter build hap --release

# 运行应用
flutter run

# 安装 HAP 包
flutter install -t <deviceId> <hap_path>
```

---

## OpenHarmony 开发指南

### ⚠️ 重要版本约束

| 约束 | 说明 |
|------|------|
| 🚫 **禁止** `flutter upgrade` | 会破坏 OpenHarmony 兼容性 |
| 🚫 **禁止** 直接使用 pub.dev 包 | 必须检查 OpenHarmony 兼容性 |
| ✅ **必须** 验证第三方包兼容性 | 查看 [第三方库兼容列表](https://gitcode.com/OpenHarmony-Flutter/docs/blob/main/ThirdpartyLibrarites.md) |

### 添加 OpenHarmony 适配包

适配了 OpenHarmony 的三方库需通过 Git 仓库引入。除必填的 `url` 外，常用参数：

- `path` : 库在仓库中的实际路径
- `ref`（可选） : 指定版本，可以是 **分支名**、**标签（tag）** 或 **commit id**

**按分支引用（推荐）：**
```yaml
dependencies:
  shared_preferences:
    git:
      url: https://gitcode.com/openharmony-tpc/flutter_packages.git
      path: packages/shared_preferences/shared_preferences
      ref: br_shared_preferences-v2.5.3_ohos  # 分支名
```

**按标签引用：**
```yaml
dependencies:
  shared_preferences:
    git:
      url: https://gitcode.com/openharmony-tpc/flutter_packages.git
      path: packages/shared_preferences/shared_preferences
      ref: gitee/shared_preferences-v2.5.3_ohos  # 发布标签
```

**使用步骤：**
1. 在 `pubspec.yaml` 中添加 git 依赖配置
2. 运行 `flutter pub get`
3. `ohos/entry/oh-package.json5` 会自动添加相关插件 har 依赖

> 完整适配包列表：https://gitcode.com/openharmony-tpc/flutter_packages
> 三方库兼容性列表：https://gitcode.com/OpenHarmony-Flutter/docs/blob/main/ThirdpartyLibrarites.md

### 常用适配包（Flutter 3.27 推荐版本）

| 包名 | 推荐版本 | 分支名 |
|------|----------|--------|
| `shared_preferences` | 2.5.3 | `br_shared_preferences-v2.5.3_ohos` |
| `path_provider` | 2.1.5 | `br_path_provider-v2.1.5_ohos` |
| `url_launcher` | 6.3.1 | `br_url_launcher_v6.3.1_ohos` |
| `image_picker` | 1.1.2 | `br_image_picker-v1.1.2_ohos` |
| `camera` | 0.11.1 | `br_camera-v0.11.1_ohos` |
| `video_player` | 2.10.0 | `br_video_player-v2.10.0_ohos` |
| `webview_flutter` | 4.13.0 | `br_webview_flutter-v4.13.0_ohos` |
| `local_auth` | 2.3.0 | `br_local_auth-v2.3.0_ohos` |
| `pigeon` | 25.3.2 | `br_pigeon-v25.3.2_ohos` |
| `file_selector` | 1.0.3 | `br_file_selector-v1.0.3_ohos` |
| `animations` | 2.0.11 | `br_animations-v2.0.11_ohos` |

---

## Flutter 踩坑记录

### 图片资源配置

Flutter 添加图片资源，需要在项目根路径创建 `assets` 目录，然后在 `assets` 目录下创建 `images` 目录，再把图片放进去。

**步骤：**

1. 创建目录结构：
   ```
   项目根目录/
   └── assets/
       └── images/
           └── your_image.png
   ```

2. 在 `pubspec.yaml` 中配置：
   ```yaml
   flutter:
     assets:
       - assets/images/
   ```

3. 使用图片：
   ```dart
   Image.asset('assets/images/your_image.png')
   ```

### RenderFlex 溢出问题

当 `Column` 或 `Row` 内容超出容器尺寸时，会出现溢出错误。

**解决方案：**
- 使用 `mainAxisSize: MainAxisSize.min` 让组件只占用必要空间
- 使用 `Flexible` 或 `Expanded` 包裹可变内容
- 添加 `maxLines` 和 `TextOverflow.ellipsis` 处理文本溢出
- 减小 padding 和 font size

### Web 端文本无法复制

Flutter Web 中普通 `Text` 组件不支持文本选择。

**解决方案：**
使用 `SelectableText` 替代 `Text`：
```dart
SelectableText('可复制的文本内容')
```

### 本地存储登录信息

使用 `shared_preferences` 保存用户登录状态。

**使用示例：**
```dart
// 保存数据
final prefs = await SharedPreferences.getInstance();
await prefs.setBool('isLoggedIn', true);
await prefs.setString('savedEmail', email);

// 读取数据
final isLoggedIn = prefs.getBool('isLoggedIn') ?? false;
final email = prefs.getString('savedEmail') ?? '';
```

---

## 开发技巧

### 快速重构快捷键
使用 Windows 下，使用快捷键 `Ctrl + Shift + R`（快速触发重构）

![重构快捷键](./assets/refactor-shortcuts.png)

### 其他实用技巧
1. **代码格式化**：使用 `Ctrl + Alt + L`（Windows）或 `Cmd + Option + L`（Mac）
2. **快速修复**：使用 `Alt + Enter`（Windows）或 `Option + Enter`（Mac）
3. **代码补全**：使用 `Ctrl + Space`（Windows）或 `Cmd + Space`（Mac）
4. **查找引用**：使用 `Shift + F12`（Windows）或 `Shift + F12`（Mac）

---

## 相关资源

### 官方资源
- **Flutter 官网**: https://flutter.dev
- **Dart 官网**: https://dart.dev
- **Flutter 中文文档**: https://flutter.cn

### OpenHarmony 相关
- **Flutter-oh SDK**: https://gitcode.com/openharmony-tpc/flutter_flutter.git
- **Flutter-oh Packages**: https://gitcode.com/openharmony-tpc/flutter_packages
- **第三方库兼容列表**: https://gitcode.com/OpenHarmony-Flutter/docs/blob/main/ThirdpartyLibrarites.md
- **OpenHarmony 文档**: https://docs.openharmony.cn

### 学习社区
- **StackOverflow Flutter**: https://stackoverflow.com/questions/tagged/flutter
- **Flutter 官方社区**: https://flutter.dev/community
- **掘金 Flutter 专栏**: https://juejin.cn/tag/Flutter
- **GitHub Flutter 组织**: https://github.com/flutter

### 实用工具
- **Flutter DevTools**: 内置的调试和性能分析工具
- **DartPad**: 在线 Dart 代码编辑器
- **Flutter Gallery**: 官方组件示例应用

---

## 学习建议

### 新手入门路径
1. **第1周**: 学习 Dart 基础语法，完成 `dart_samples/basic/` 中的练习
2. **第2周**: 完成 `flutter_first_application` 项目，理解基础组件
3. **第3周**: 学习布局，完成 `flutter_layout_application` 项目
4. **第4周**: 学习状态管理和路由，完成 `flutter_web_application` 项目
5. **第5周**: 学习 OpenHarmony 开发，完成 `flutter-oh-app` 项目

### 进阶学习
1. **深入状态管理**: 学习 Provider、Bloc、Riverpod 等状态管理方案
2. **性能优化**: 学习 Flutter 性能优化技巧
3. **原生交互**: 学习 Platform Channels 与原生代码交互
4. **测试**: 学习单元测试、Widget 测试和集成测试
5. **架构设计**: 学习 Clean Architecture、MVVM 等架构模式

---

**最后更新**: 2026年4月8日  
**维护者**: Flutter 学习之路