94 lines
4.4 KiB
Markdown
94 lines
4.4 KiB
Markdown
[](README.en.md)
|
|
|
|
# Flutter Template
|
|
|
|
一个从实际项目中提炼的 Flutter 通用快速开发模板，开箱即用，避免重复搭建工程基础设施。
|
|
|
|
## 目标
|
|
|
|
- 支持 Android 和 iOS
|
|
- 不包含原业务页面、接口、Model、资源、文案和私有配置
|
|
- 保留通用工程化能力：路由、主题、网络、缓存、日志、权限、工具类、状态管理和常用 UI 组件
|
|
- 默认首页为 demo 页面，可直接替换为新业务首页
|
|
|
|
## 技术栈
|
|
|
|
| 类别 | 依赖 | 用途 |
|
|
| -------- | -------------------- | -------------------------- |
|
|
| 状态管理 | flutter_riverpod | 编译安全、可测试的状态管理 |
|
|
| 网络请求 | dio | HTTP 客户端，支持拦截器链 |
|
|
| 本地缓存 | shared_preferences | KV 持久化存储 |
|
|
| 网络监听 | connectivity_plus | 实时网络状态监测 |
|
|
| 权限申请 | permission_handler | 运行时权限请求 |
|
|
| 屏幕适配 | flutter_screenutil | 设计稿尺寸适配 |
|
|
| 图片加载 | cached_network_image | 网络图片缓存 |
|
|
| SVG | flutter_svg | SVG 渲染 |
|
|
| 下拉刷新 | pull_to_refresh | 下拉刷新 / 上拉加载 |
|
|
| 加载提示 | flutter_easyloading | Toast 和 loading |
|
|
| 设备信息 | device_info_plus | 设备元数据 |
|
|
| 应用信息 | package_info_plus | 版本号等应用信息 |
|
|
| 链接跳转 | url_launcher | 外部 URL 打开 |
|
|
| 代码规范 | flutter_lints | Dart 推荐 lint 规则 |
|
|
|
|
## 目录结构
|
|
|
|
```
|
|
lib/
|
|
├── app/ # 应用壳
|
|
│ ├── app.dart # MaterialApp、主题、国际化、全局配置
|
|
│ ├── bootstrap.dart # 启动初始化
|
|
│ ├── config/ # 多环境配置 (dev/staging/prod)
|
|
│ ├── router/ # Navigator 工具和路由栈跟踪
|
|
│ └── theme/ # 亮色/暗色主题、颜色、间距
|
|
├── core/ # 框架层基础设施
|
|
│ ├── cache/ # SharedPreferences 封装和通用 key
|
|
│ ├── extensions/ # BuildContext 扩展
|
|
│ ├── logging/ # 日志工具
|
|
│ ├── mixins/ # 通用 mixin
|
|
│ ├── network/ # Dio 封装、响应包装、异常处理
|
|
│ │ └── offline_queue/ # 拦截器、网络监听、离线请求队列
|
|
│ ├── permission/ # 权限请求封装
|
|
│ └── utils/ # 日期、表单校验、防抖节流、设备、URL 工具
|
|
├── shared/
|
|
│ └── widgets/ # 通用 UI 组件库
|
|
├── features/
|
|
│ └── demo/ # 模板能力演示页，可删除
|
|
└── main.dart # 入口
|
|
```
|
|
|
|
## 内置能力
|
|
|
|
- **网络层** — ApiClient (Dio) + ApiResponse + ApiException + 请求头拦截器
|
|
- **网络监听** — 基于 connectivity_plus 的实时状态追踪
|
|
- **离线队列** — 请求入队、持久化、网络恢复自动重放
|
|
- **本地缓存** — AppStorage 封装 SharedPreferences
|
|
- **状态管理** — Riverpod Provider 体系
|
|
- **主题系统** — Material 3 亮/暗双主题 + 屏幕适配
|
|
- **UI 组件** — AppButton、AppTextField、AppCard、AppDialog、AppToast、AppEmptyView、AppErrorView、AppLoadingView、AppStatusView、AppAvatar、AppTag、AppSearchBar、AppRefreshList、AppNetworkImage、SafeAreaWrapper
|
|
- **工具类** — 日期格式化、表单校验、防抖节流、设备信息、URL 工具
|
|
- **工程配置** — flutter_lints、Android/iOS 平台工程
|
|
|
|
## 快速开始
|
|
|
|
```bash
|
|
cd record-tool
|
|
flutter pub get
|
|
flutter analyze
|
|
flutter test
|
|
flutter run
|
|
```
|
|
|
|
```bash
|
|
flutter run -d <device-id>
|
|
flutter build apk --debug
|
|
flutter build ios --debug --no-codesign
|
|
```
|
|
|
|
## 新业务接入指引
|
|
|
|
1. 修改 `lib/app/config/app_config.dart` 中的环境地址
|
|
2. 在 `lib/features/` 下新增业务模块
|
|
3. 通过 `core/network/providers/dio_providers.dart` 获取 ApiClient
|
|
4. 业务缓存 key 放在业务模块内，`core/cache/storage_keys.dart` 只放真正通用的 key
|
|
5. 删除 `features/demo/` 或替换为业务首页
|