# curb-ui

**Repository Path**: curb-ui/curb-ui

## Basic Information

- **Project Name**: curb-ui
- **Description**: 一个精致的 Flutter 设计系统
开箱即用、极致语义化的 Flutter UI 框架
- **Primary Language**: Dart
- **License**: MIT
- **Default Branch**: master
- **Homepage**: https://v0-curb-ui.vercel.app/
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-14
- **Last Updated**: 2026-05-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# CurbUI

一个精致的 Flutter 设计系统，提供全面的 UI 组件和工具，用于构建美观、一致且响应式的应用程序。

> 📖 [English Version](README.md)

## 🎨 特性

### 核心组件

- **UI 组件**：按钮、卡片、输入框、列表、对话框、提示、加载等多种组件
- **布局组件**：应用栏、标签栏、标签页、页面、下拉刷新等
- **表单组件**：复选框、单选框、开关、滑块、评分等
- **媒体组件**：图片、头像、轮播图、Lottie 动画等
- **反馈组件**：提示、加载、对话框、确认框等

### 设计系统

- **主题管理**：可定制的主题系统，包含多个预设主题
- **色彩系统**：全面的色彩 palette，包含语义化和功能性颜色
- **排版系统**：一致的排版系统，包含不同的文本级别
- **间距系统**：一致的间距尺度，用于布局
- **圆角系统**：一致的边框圆角尺度
- **图标系统**：自定义图标字体支持

### 国际化

- **多语言支持**：内置多语言支持
- **简单本地化**：添加新语言的简单方法
- **动态语言切换**：运行时更改语言

### 路由管理

- **声明式路由**：使用 GoRouter 实现清晰的声明式路由
- **路由守卫**：使用身份验证和授权保护路由
- **深度链接**：支持深度链接

### API 服务

- **Retrofit 集成**：轻松生成 API 客户端
- **模拟服务**：内置开发用的模拟数据
- **错误处理**：跨 API 调用的一致错误处理

### 工具类

- **存储**：本地存储工具
- **日志**：全面的日志系统
- **屏幕工具**：屏幕尺寸和方向工具
- **颜色工具**：颜色操作工具

## 🚀 快速开始

### 前置条件

- Flutter 3.10.4 或更高版本
- Dart 3.10.4 或更高版本

### 快速上手

1. **拉取代码到本地**：
   ```bash
   git clone https://gitee.com/curb-ui/curb-ui.git
   ```
   或
   ```bash
   git clone https://github.com/curb-ui/curb-ui.git
   ```
   进入项目目录：
   ```bash
   cd curb-ui
   ```

1. **环境配置初始化**：
   进入项目根目录，根据 `config_example.json` 模板新建各环境配置文件：
   - 复制并命名为 `config_dev.json` (开发环境)
   - 复制并命名为 `config_prod.json` (生产环境)
  ```json
    {
      "APP_NAME": "Curb UI",
      "APP_VERSION": "1.0.0",
      "API_URL": "https://show.cool-admin.com",
      "BASE_URL": "/api",
      "SHOW_LOGS": false,
      "PRIVACY_URL": "https://gitee.com/curb-ui/curb-ui-docs/blob/master/content/about/privacy.md",
      "AGREEMENTS_URL": "https://gitee.com/curb-ui/curb-ui-docs/blob/master/content/about/agreement.md",
    }
  ```
2. **安装依赖**
   ```bash
   flutter pub get
   ```
3. **生成本地化文件**
   ```bash
   flutter gen-l10n
   ```
4. **生成 API 客户端**
   ```bash
   flutter pub run build_runner build --delete-conflicting-outputs
   ```
5. **运行应用**
   ```bash
   flutter run
   ```

## 📁 项目结构

```
lib/
├── api/           # API 服务和模型
├── components/    # UI 组件
├── config/        # 应用配置
├── locale/        # 国际化文件
├── pages/         # 应用页面
├── provider/      # 状态管理
├── routes/        # 路由配置
├── theme/         # 主题系统
├── utils/         # 工具函数
├── app.dart       # 应用入口点
├── bootstrap.dart # 应用引导
├── curb_ui.dart   # CurbUI 导出
└── main.dart      # 主入口点
```

### 关键目录

- **components/**：所有 UI 组件，按类型组织
- **pages/**：应用页面，包括组件演示页面
- **theme/**：主题系统，包含预设主题和配置
- **locale/**：国际化文件和工具
- **api/**：API 服务和数据模型
- **routes/**：路由配置和路由定义

## 🎯 核心组件

### 按钮

一个多功能按钮组件，支持多种样式和尺寸。

### 卡片

一个灵活的卡片组件，用于显示内容。

### 输入框

一个全面的输入组件，支持验证和错误处理。

### 列表

一个强大的列表组件，支持不同的项目类型和布局。

### 对话框

一个可定制的对话框组件，用于用户交互。

### 提示

一个轻量级的提示组件，用于快速反馈。

### 加载

一个加载指示器组件，用于异步操作。

### 应用栏

一个可定制的应用栏组件。

### 标签栏

一个标签栏组件，用于在视图之间导航。

### 下拉刷新

一个下拉刷新组件，用于数据刷新。

## 🎨 主题系统

CurbUI 提供全面的主题系统，包括：

- **预设主题**：多个现成可用的主题
- **可定制**：轻松创建和定制主题
- **主题切换**：运行时更改主题
- **语义化颜色**：基于语义角色的颜色系统

### 可用主题

- 默认
- 樱桃红
- 珊瑚橙
- 翡翠绿
- 金色
- 灰色
- 薄荷绿
- 紫色

## 🌐 国际化

CurbUI 开箱即支持多种语言：

- **英文**
- **中文**

添加新语言很简单：

1. 在 `lib/locale/l10n/` 中创建新的 `.arb` 文件
2. 运行 `flutter gen-l10n` 生成本地化文件
3. 更新设置页面中的语言选择器

## 🛣️ 路由管理

CurbUI 使用 GoRouter 实现声明式路由，包括：

- **命名路由**：轻松导航路由
- **路由守卫**：保护路由
- **深度链接**：支持深度链接
- **嵌套路由**：层次化组织路由

## 🔌 API 服务

CurbUI 提供结构化的 API 服务方法：

- **Retrofit 集成**：通过注解生成 API 客户端
- **模拟服务**：内置开发用的模拟数据
- **错误处理**：一致的错误处理
- **响应模型**：类型化的响应模型

## 📖 文档

### 组件文档

每个组件的详细文档可在 `docs/components/` 目录中找到。

### API 文档

API 文档可在 `docs/api/` 目录中找到。

### 国际化文档

国际化文档可在 `docs/locale/` 目录中找到。

### 路由文档

路由文档可在 `docs/route/` 目录中找到。

### 主题文档

主题文档可在 `docs/theme/` 目录中找到。

## 🤝 贡献

欢迎贡献！请随时提交 Pull Request。

### 开发指南

- 遵循现有的代码风格
- 为新功能添加测试
- 为更改更新文档
- 使用语义化的提交消息

## 📄 许可证

本项目采用 MIT 许可证 - 详见 [LICENSE](LICENSE) 文件。

## 📞 联系我们

如有任何问题、反馈或合作意向，欢迎通过以下方式联系我们：

- 📧 邮箱：**curbui@yeah.net**

***

由 CurbUI 团队用心制作 ❤️