# flutter_base **Repository Path**: 705348563/flutter_base ## Basic Information - **Project Name**: flutter_base - **Description**: No description available - **Primary Language**: Dart - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2025-07-25 - **Last Updated**: 2026-01-16 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # Flutter Base 项目 一个功能完整的 Flutter 基础项目，集成了现代移动应用开发的核心功能和最佳实践。 ## 项目介绍 本项目是一个 Flutter 基础框架，旨在为开发者提供一个快速启动的项目模板。项目采用了清晰的架构设计，集成了常用的第三方库，并实现了多语言支持、网络请求、路由管理、状态管理等核心功能。 ### 主要特性 - 🌍 **多语言支持** - 支持中文和英文，可轻松扩展其他语言 - 🚀 **现代路由管理** - 基于 go_router 的声明式路由 - 🔄 **状态管理** - 使用 Provider 进行状态管理 - 🌐 **网络请求** - 基于 Dio 的 HTTP 客户端，支持拦截器和错误处理 - 📱 **响应式设计** - 适配多种屏幕尺寸 - 🎨 **自定义组件** - 丰富的自定义 UI 组件库 - 💾 **本地存储** - SharedPreferences 数据持久化 - 🖼️ **图片处理** - 网络图片缓存和图片查看器 - 📅 **选择器组件** - 日期选择器、底部选择器、联动选择器等 - 📜 **列表刷新加载** - 支持下拉刷新、上拉加载更多、错误重试的通用列表组件 ## 详细目录结构 ``` flutter_base/ ├── .gitignore # Git 忽略文件配置 ├── .metadata # Flutter 元数据 ├── .trae/ # Trae AI 配置 │ └── rules/ │ └── project_rules.md # 项目规则文档 ├── .vscode/ # VS Code 配置 │ └── launch.json # 调试配置 ├── README.md # 项目说明文档 ├── analysis_options.yaml # Dart 代码分析配置 ├── pubspec.yaml # 项目依赖配置 ├── pubspec.lock # 依赖锁定文件 ├── devtools_options.yaml # 开发工具配置 │ ├── android/ # Android 平台配置 │ ├── app/ │ │ ├── build.gradle.kts # Android 应用构建配置 │ │ └── src/ # Android 源码 │ ├── build.gradle.kts # Android 项目构建配置 │ ├── gradle/ # Gradle 配置 │ ├── gradle.properties # Gradle 属性 │ └── settings.gradle.kts # Gradle 设置 │ ├── ios/ # iOS 平台配置 │ ├── Flutter/ # Flutter iOS 配置 │ ├── Podfile # CocoaPods 依赖 │ ├── Runner/ # iOS 应用源码 │ └── Runner.xcodeproj/ # Xcode 项目文件 │ ├── linux/ # Linux 平台配置 ├── macos/ # macOS 平台配置 ├── web/ # Web 平台配置 ├── windows/ # Windows 平台配置 │ ├── lib/ # Dart 源码目录 │ ├── main.dart # 应用入口文件 │ ├── generated/ # 自动生成的文件 │ │ ├── intl/ # 国际化生成文件 │ │ └── l10n.dart # 多语言支持类 │ ├── l10n/ # 多语言资源文件 │ │ ├── intl_en.arb # 英文语言包 │ │ └── intl_zh.arb # 中文语言包 │ └── src/ # 源码主目录 │ ├── common/ # 公共组件和工具 │ │ ├── mixin/ # Mixin 类 │ │ └── widgets/ # 自定义组件 │ │ ├── custom_bottom_picker.dart # 底部选择器 │ │ ├── custom_date_picker.dart # 日期选择器 │ │ ├── custom_linked_picker.dart # 二级联动选择器 │ │ ├── custom_triple_linked_picker.dart # 三级联动选择器 │ │ ├── image_viewer.dart # 图片查看器 │ │ ├── web_view.dart # WebView 组件 │ │ └── refresh/ # 刷新加载组件 │ │ ├── common_list_view.dart # 通用列表视图 │ │ ├── custom_refresh_widget.dart # 自定义刷新组件 │ │ └── common_error_widget.dart # 通用错误组件 │ ├── model/ # 数据模型 │ │ ├── base_model.dart # 基础数据模型 │ │ └── base_model.g.dart # 生成的模型文件 │ ├── network/ # 网络请求模块 │ │ ├── http.dart # HTTP 客户端 │ │ └── http_interceptors.dart # HTTP 拦截器 │ ├── pages/ # 页面目录 │ │ ├── home/ # 首页模块 │ │ │ └── home_page.dart # 首页 │ │ ├── login/ # 登录模块 │ │ │ └── login_page.dart # 登录页 │ │ ├── list/ # 列表页模块 │ │ │ └── list_page.dart # 列表示例页 │ │ └── profile/ # 个人中心模块 │ ├── provider/ # 状态管理 │ │ └── locale_provider.dart # 语言状态管理 │ ├── routes/ # 路由配置 │ │ ├── app_routes.dart # 应用路由配置 │ │ ├── common_routes.dart # 通用路由 │ │ └── home_routes.dart # 首页路由 │ └── utils/ # 工具类 │ ├── color_util.dart # 颜色工具 │ ├── loading_utils.dart # 加载工具 │ ├── navigation_service.dart # 导航服务 │ ├── storage_util.dart # 存储工具 │ ├── toast_util.dart # 提示工具 │ └── tool.dart # 通用工具 │ └── test/ # 测试文件 └── widget_test.dart # 组件测试 ``` ## 项目功能 ### 1. 核心架构功能 #### 多语言国际化 - 支持中文（zh_CN）和英文（en_US） - 基于 `flutter_localizations` 和 `intl` 包 - 动态语言切换，无需重启应用 - 语言状态通过 Provider 管理 #### 路由管理 - 使用 `go_router` 实现声明式路由 - 支持路由观察者和导航拦截 - 404 错误页面处理 - 自动键盘收起功能 #### 状态管理 - 基于 `Provider` 的状态管理方案 - 支持多 Provider 组合 - 响应式状态更新 ### 2. 网络请求功能 #### HTTP 客户端 - 基于 `Dio` 的网络请求封装 - 支持 GET、POST、PUT、DELETE 方法 - 统一的错误处理和响应格式 - 请求/响应拦截器支持 - 超时配置和取消请求支持 #### 数据模型 - 基础数据模型 `BaseModel` - JSON 序列化支持 - 代码生成工具集成 ### 3. UI 组件功能 #### 自定义选择器 - **底部选择器** (`CustomBottomPicker`) - 支持单选模式 - 可自定义高度和样式 - 支持复杂数据结构 - **二级联动选择器** (`CustomLinkedPicker`) - 父子级联动选择 - 支持初始值设置 - 动态数据加载 - **三级联动选择器** (`CustomTripleLinkedPicker`) - 省市区三级联动 - 支持地区数据扩展 - 智能联动更新 - **日期选择器** (`CustomDatePicker`) - 自定义日期格式 - 日期范围限制 - 本地化日期显示 #### 图片处理 - **网络图片缓存** (`cached_network_image`) - 自动缓存管理 - 加载状态显示 - 错误处理 - **图片查看器** (`ImageViewer`) - 支持多图浏览 - 缩放和平移功能 - 基于 `photo_view` 实现 #### WebView 组件 - 内置 WebView 页面 - URL 参数传递 - 完整的 Web 内容支持 #### 列表刷新加载组件 - **通用列表视图** (`CommonListView`) - 封装分页、加载、刷新和错误重试逻辑 - 自动管理加载状态 - 支持泛型数据类型 - 智能错误处理（区分首次加载和加载更多） - **自定义刷新组件** (`CustomRefreshWidget`) - 下拉刷新功能 - 上拉加载更多 - 自定义刷新动画 - 支持自定义 Header 和 Footer - 基于 `custom_refresh_indicator` 实现 - **通用错误组件** (`CommonErrorWidget`) - 统一的错误提示界面 - 可自定义标题、副标题和按钮文本 - 支持重试回调 ### 4. 工具类功能 #### 导航服务 - 全局导航管理 - 无 Context 导航支持 - 路由状态监听 #### 加载工具 - 全局加载状态管理 - 自定义加载样式 - 自动加载状态控制 #### 存储工具 - 基于 `SharedPreferences` - 类型安全的存储接口 - 异步存储操作 #### 提示工具 - Toast 消息提示 - 基于 `fluttertoast` - 多种提示样式 #### 颜色工具 - 统一的颜色管理 - 主题色配置 - 颜色工具方法 ### 5. 开发工具集成 #### 代码生成 - `build_runner` 集成 - JSON 序列化代码生成 - 国际化代码生成 #### 代码规范 - `flutter_lints` 代码检查 - 统一的代码风格 - 自定义分析规则 ## 快速开始 ### 环境要求 - Flutter SDK >= 3.8.1 - Dart SDK >= 3.8.1 - Android Studio / VS Code - iOS 开发需要 Xcode（仅 macOS） ### 安装依赖 ```bash flutter pub get ``` ### 生成代码 ```bash flutter pub run build_runner build --delete-conflicting-outputs ``` ### 生成国际化文件 ```bash flutter pub run flutter_intl:generate ``` ### 运行项目 ```bash # 调试模式 flutter run # 发布模式 flutter run --release # 指定设备 flutter run -d ``` ### 构建项目 ```bash # Android APK flutter build apk # iOS flutter build ios # Web flutter build web ``` ## 开发指南 ### 添加新页面 1. 在 `lib/src/pages/` 下创建新的页面目录 2. 创建页面 Dart 文件 3. 在相应的路由文件中添加路由配置 4. 更新 `app_routes.dart` 引入新路由 ### 添加新的多语言文本 1. 在 `lib/l10n/intl_zh.arb` 中添加中文文本 2. 在 `lib/l10n/intl_en.arb` 中添加英文文本 3. 运行 `flutter pub run flutter_intl:generate` 生成代码 4. 在代码中使用 `AppL10n.of(context).textKey` 调用 ### 添加新的网络接口 1. 在 `lib/src/network/http.dart` 中添加接口方法 2. 创建对应的数据模型 3. 在页面中调用接口方法 ### 自定义主题 1. 修改 `lib/src/utils/color_util.dart` 中的颜色配置 2. 在 `main.dart` 中更新 `ThemeData` 配置 ### 使用列表刷新组件 1. 使用 `CommonListView` 创建带分页的列表： ```dart CommonListView( onFetch: (page) async { // 获取数据的异步方法 return await yourApi.fetchList(page: page); }, itemBuilder: (context, item, index) { return ListTile( title: Text(item.name), ); }, ) ``` 2. 使用 `CustomRefreshWidget` 自定义刷新行为： ```dart CustomRefreshWidget( enablePullDown: true, // 启用下拉刷新 enablePullUp: true, // 启用上拉加载 onRefresh: () async { // 刷新逻辑 }, onLoading: () async { // 加载更多逻辑 }, builder: (controller) => ListView.builder( controller: controller, itemBuilder: (context, index) { // 列表项构建 }, ), ) ``` ## 技术栈 - **框架**: Flutter 3.8.1+ - **语言**: Dart 3.8.1+ - **状态管理**: Provider 6.1.2 - **路由管理**: go_router 16.0.0 - **网络请求**: dio 5.8.0+1 - **本地存储**: shared_preferences 2.5.3 - **国际化**: flutter_localizations + intl 0.20.2 - **图片缓存**: cached_network_image 3.4.1 - **图片查看**: photo_view 0.14.0 - **WebView**: webview_flutter 4.13.0 - **提示组件**: fluttertoast 8.2.10 - **刷新加载**: custom_refresh_indicator 4.0.1 - **代码生成**: build_runner 2.6.0 - **代码规范**: flutter_lints 5.0.0 ## 许可证 本项目仅供学习和开发参考使用。