一个基于 Flutter 与 shadcn_ui 组件库的管理后台示例项目。
项目采用 feature-friendly 分层，并在 lib/app 下进行归档：
lib/
app/
common/ // 通用能力与配置
langs/ // 国际化资源与服务
en_US.dart
zh_Hans.dart
translation_service.dart
auth_service.dart
my_config.dart
my_constants.dart
index.dart // Barrel 导出
core/ // 全局能力与主题
theme/
index.dart
global.dart
index.dart // Barrel 导出
data/ // 数据模型
user_info.dart
modules/ // 模块（页面/逻辑/绑定）
dashboard/
binding.dart
logic.dart
page.dart
view.dart
login/
binding.dart
logic.dart
page.dart
view.dart
res/ // 资源（主题数据等）
shadcn_theme_data.dart
routes/ // 路由定义与集中出口
app_pages.dart
app_routes.dart
index.dart
shared/ // 共享 UI（布局/组件/页面片段）
layout/
components/
admin_header.dart
admin_sidebar.dart
theme_toggle_button.dart
controllers/
customize_controller.dart
layout_controller.dart
shell/
admin_layout.dart
user/
sidebar_user_info.dart
components.dart
controllers.dart
index.dart
pages/
errors/
unauthorized_view.dart
forbidden_view.dart
not_found_view.dart
internal_server_error_view.dart
service_unavailable_view.dart
index.dart
widgets/
dashboard/
recent_sales.dart
stat_card.dart
index.dart
error/
custom_error_logic.dart
custom_error_state.dart
custom_error_view.dart
index.dart
index.dart // Barrel 导出
main.dart
- common：跨模块通用能力与配置，含国际化服务与常量
- core：全局初始化、主题与全局状态
- data：纯数据模型定义
- modules：按照功能模块组织的页面/逻辑/绑定
- res：静态资源与主题数据
- routes：集中管理路由表与路径常量
- shared：共享 UI（布局、通用组件、错误页等）
- 文件命名：lower_case_with_underscores
- 类命名：UpperCamelCase
- 常量命名：lowerCamelCase（例如 storageUserProfileKey）
- 国际化：TranslationService 使用 'en_US' 与 'zh_Hans' 作为语言键
- 导出：每个一级目录提供 index.dart 作为 Barrel 出口，减少长路径导入
- 代码静态检查：
flutter analyze - 运行：
flutter run -d chrome或选择本地平台设备
- 安装依赖：
- Flutter SDK（3.10 及以上）
- 执行
flutter pub get
- 启动项目：
- Web：
flutter run -d chrome - 桌面/移动：选择对应设备后运行
- Web：
- 主题切换：
- 登录页或主界面右上角的图标按钮打开主题菜单
- 选择 Light/Dark/System 即可全局生效
- 自定义外观：
- 点击右上角调色板按钮，打开右侧「自定义」抽屉
- 可选择颜色（Color Scheme）与圆角（Radius），并设置颜色模式
- 主题实现：
- 全局主题状态由
Global.themeMode与Global.themeData管理（见lib/app/core/global.dart） - 根组件在
main.dart中通过ShadApp.custom将主题注入到 shadcn_ui - 所有页面与组件通过
ShadTheme.of(context)读取颜色与排版信息
- 全局主题状态由
- 模式切换：
- 顶部的
ThemeToggleButton提供 Light/Dark/System 三种模式切换 - Light 模式使用当前选择的调色板（如 Blue/Zinc）
- Dark 模式统一使用 shadcn_ui 官方暗色方案，背景与前景为暗色系
- System 模式根据操作系统的亮暗模式自动选择 Light 或 Dark
- 顶部的
- 自定义外观：
- 右侧「自定义」抽屉中可以调整：
- 主题颜色（Color Scheme）
- 圆角大小（Radius）
- 颜色模式（Light/Dark/System）
- 这些设置会持久化存储，在下次启动时自动恢复
- 右侧「自定义」抽屉中可以调整：
- 开发约定：
- 新增组件时，应优先使用
ShadTheme.of(context).colorScheme与textTheme - 避免直接使用
Colors.*或Theme.of(context)的颜色，以保证主题切换时全局外观一致
- 新增组件时，应优先使用
- 切到 Dark 但页面仍是亮色：
- 检查页面/组件是否使用了
Colors.*或Theme.of(context)的颜色，改为ShadTheme.of(context).colorScheme与textTheme - 确认当前模式是否为 System，且操作系统本身处于亮色；System 模式会跟随系统
- 确认根组件仍然通过
ShadApp.custom构建（见main.dart），且Global.setThemeMode被调用
- 检查页面/组件是否使用了
- 菜单颜色与页面不一致：
- 弹出菜单应从
ShadTheme.of(context)取色；若使用了固定色值请替换 - 关闭菜单后重新打开以应用最新主题
- 弹出菜单应从
- UI 组件：shadcn_ui
- 路由与依赖注入：GetX
本项目遵循 LICENSE 中的开源许可。 本项目基于 Apache License 2.0 开源协议发布，详见 LICENSE。
- 本项目的部分代码与文档由 AI 辅助生成与优化，所有改动均经过人工审阅与测试验证
- 欢迎以 Issue/PR 的形式提供建议或改进