oneapp_docs/basic_uis/ui_basic.md

# UI Basic 基础UI组件模块

## 模块概述

`ui_basic` 是 OneApp 基础UI模块群中的核心组件库，提供了应用开发中常用的基础UI组件和交互元素。该模块封装了通用的界面组件、布局容器、表单元素等，为整个应用提供统一的设计语言和用户体验。

### 基本信息
- **模块名称**: ui_basic
- **版本**: 0.2.45
- **仓库**: https://gitlab-rd0.maezia.com/dssomobile/oneapp/dssomobile-oneapp-ui-basic
- **Flutter 版本**: >=1.17.0
- **Dart 版本**: >=2.17.0 <4.0.0
- **发布服务器**: http://175.24.250.68:4000/

## 功能特性

### 核心功能
基于实际项目的UI组件库，包含丰富的组件和第三方集成。

1. **基础组件库**
   - 按钮组件（OneIconButton、CommonButton）
   - 输入组件（BasicTextField、BasicMultiTextField、VehiclePlateField）
   - 展示组件（OneTag、OneCard、ProgressWidget）
   - 导航组件（CommonTitleBar、CommonTabbar）

2. **交互组件**
   - 上拉下拉刷新（pull_to_refresh集成）
   - 轮播图组件（OneSwiper、carousel_slider集成）
   - 对话框和弹窗（OneDialogX、CommonBottomSheet）
   - 加载指示器（LoadingWidget、CommonLoadingWidget）

3. **多媒体组件**
   - 图片组件（GlinettImage、ImageWidget、CachedNetworkImage集成）
   - 扫码组件（QrScannerWidget、flutter_scankit集成）
   - 相机组件（CameraWidget、camera集成）
   - SVG支持（flutter_svg集成）

4. **富文本和图表**
   - HTML富文本渲染（flutter_html集成）
   - 图表组件（OneChart、fl_chart集成）
   - ECharts集成（FlutterEcharts）
   - 评分组件（RatingWidget、flutter_rating_bar集成）

## 技术架构

### 目录结构
```
lib/
├── ui_basic.dart               # 模块入口文件
├── src/                        # 源代码目录
│   ├── components/             # 基础组件
│   ├── containers/             # 布局容器
│   ├── interactions/           # 交互组件
│   ├── themes/                 # 主题配置
│   ├── utils/                  # 工具类
│   └── constants/              # 常量定义
├── widgets/                    # 组件导出
└── themes/                     # 主题文件
```

### 依赖关系

基于实际项目的pubspec.yaml配置，展示真实的依赖架构。

#### 框架依赖
```yaml
# 核心框架依赖
dependencies:
  basic_network: ^0.2.3+4      # 网络通信基础
  basic_modular: ^0.2.3        # 模块化框架
  basic_modular_route: ^0.2.1  # 路由管理
  basic_intl_flutter: ^0.2.2+1 # 国际化支持
  basic_theme_core: ^0.2.5     # 主题核心
  ui_basic_annotation: ^0.2.0  # UI框架注解
```

#### UI和交互依赖
```yaml
# UI组件和交互依赖
dependencies:
  provider: ^6.0.5             # 状态管理
  flutter_html: ^3.0.0-beta.2 # HTML富文本渲染
  badges: ^3.1.1               # 角标组件
  pull_to_refresh: ^2.0.0      # 上拉下拉刷新
  carousel_slider: ^4.2.1      # 轮播图组件
  cached_network_image: ^3.3.0 # 缓存网络图片
  flutter_svg: ^2.0.6          # SVG图片支持
  flutter_smart_dialog: ^4.9.1 # 智能对话框
  visibility_detector: ^0.4.0+2# 可见性检测
  fl_chart: ^0.x.x             # 图表组件
```

#### 多媒体和工具依赖
```yaml
# 多媒体和工具依赖
dependencies:
  camera: ^0.10.5+2            # 相机功能
  image_picker: ^1.1.2         # 图片选择
  image_cropper: ^9.1.0        # 图片裁剪
  flutter_image_compress: ^2.0.3# 图片压缩
  flutter_scankit: 2.0.3+1    # 扫码工具
  url_launcher: ^6.1.11       # URL跳转
  flutter_rating_bar: ^4.0.1   # 评分组件
  sprintf: ^7.0.0              # 字符串格式化
  dartz: ^0.10.1               # 函数式编程
  rxdart: ^0.27.7              # 响应式编程
```

## 核心组件分析

### 1. 模块入口 (`ui_basic.dart`)

基于真实项目的模块导出结构，包含大量第三方库集成和自定义组件。

**功能职责**:
- 统一导出所有UI组件和第三方库
- 集成badge、cached_network_image、flutter_html等核心UI库
- 导出自定义组件如OneColors、OneTextStyle、OneIcons
- 提供car_func_block等车辆相关UI组件

```dart
// 实际的模块导出结构（ui_basic.dart）
library ui_basic;

// 第三方UI库集成
export 'package:badges/badges.dart';
export 'package:cached_network_image/cached_network_image.dart';
export 'package:flutter_html/flutter_html.dart';
export 'package:flutter_svg/flutter_svg.dart';
export 'package:visibility_detector/visibility_detector.dart';
export 'package:bottom_sheet/bottom_sheet.dart';
export 'package:fl_chart/fl_chart.dart';

// 自定义组件导出
export 'src/colors/colors.dart' show OneColors;
export 'src/fonts/fonts.dart' show OneTextStyle, TextFont, OneBasicText;
export 'src/icon/icon.dart' show OneIcons;

// UI组件导出
export 'src/components/appbar/common_title_bar.dart';
export 'src/components/button/buttons.dart';
export 'src/components/dialog/dialog_export.dart';
export 'src/components/loading/loading_widget.dart';
export 'src/components/text_field/basic_text_field.dart';
export 'src/components/cards/cards_export.dart';

// 车辆功能组件
export 'src/car_func_block/car_func_block_class.dart';
export 'src/car_func_block/car_func_block_manager.dart';

// 工具类导出
export 'src/utils/qr_scanner_util/qr_scanner_util.dart';
export 'src/utils/image_util/image_util.dart';
export 'src/utils/launcher/launch_util.dart';
```

### 2. 主题颜色系统 (`src/colors/colors.dart`)

基于主题核心框架的动态颜色系统，支持主题切换和自定义颜色。

```dart
// 实际的颜色系统实现
class OneColors {
  /// 主题色 Primary Color
  static Color get primary =>
      theme.ofStandard().themeData?.appColors?.primary ??
      const Color(0xFFEED484);

  /// 背景色 Bgc
  static Color get bgc =>
      theme.ofStandard().themeData?.appColors?.backgroundColors.bgc ??
      const Color(0xFFFFFFFF);

  /// 背景色 辅助1-5
  static Color get bgcSub1 =>
      theme.ofStandard().themeData?.appColors?.backgroundColors.bgcSub1 ??
      const Color(0xFFFFFFFF);
  // ... 更多背景色变体

  /// 动态主题获取
  static ITheme get theme => uiBasicPlatformInfoDeps.theme != null
      ? uiBasicPlatformInfoDeps.theme!
      : DefaultTheme(
          DefaultStandardResource(),
          DefaultUiKitResource(),
        );
}
```

### 4. 按钮组件 (`src/components/button/buttons.dart`)

基于真实项目的按钮组件实现，支持多种按钮类型和状态管理。

```dart
// 实际的按钮状态枚举
enum BtnLoadingStatus {
  /// 初始化
  idle,
  /// 加载中
  loading,
}

/// 按钮类型枚举
enum BtnType {
  /// TextButton
  text,
  /// ElevatedButton
  elevated,
  /// OutlineButton
  outline,
}

/// 实际的图标按钮组件
class OneIconButton extends StatelessWidget {
  const OneIconButton({
    required this.child,
    this.iconSize,
    this.cubit,
    this.onPress,
    this.style,
    Key? key,
  }) : super(key: key);

  /// 按钮内容
  final Widget child;
  /// 字体大小
  final double? iconSize;
  /// 状态管理
  final OneIconButtonCubit? cubit;
  /// 点击回调
  final VoidCallback? onPress;
  /// 样式配置
  final ButtonStyle? style;

  @override
  Widget build(BuildContext context) {
    // 实际的按钮实现逻辑
    // 支持状态管理和样式定制
  }
}

/// 通用按钮组件
class CommonButton extends StatelessWidget {
  // 支持加载状态、不同按钮类型、自定义样式等
  // 集成BLoC状态管理和主题系统
}
```

### 5. 文本输入组件 (`src/components/text_field/`)

包含多种文本输入组件的真实实现。

```dart
// 基础文本输入字段
export 'src/components/text_field/basic_text_field.dart';
export 'src/components/text_field/basic_multi_text_field.dart';
export 'src/components/text_field/clear_text_field.dart';
export 'src/components/text_field/edit_text/edit_text.dart';

// 特殊用途文本字段
export 'src/components/text_field/vehicle_plate_field/vehicle_plate_field_widget.dart';

// 实际支持的功能：
// - 基础文本输入
// - 多行文本输入
// - 带清除按钮的文本输入
// - 车牌号输入专用组件
// - 集成表单验证和状态管理
```

### 7. 第三方UI库集成

ui_basic模块集成了大量优秀的第三方UI库，提供开箱即用的功能。

```dart
// 图标和标记组件
export 'package:badges/badges.dart';              // 角标组件
export 'package:font_awesome_flutter/font_awesome_flutter.dart'; // FontAwesome图标

// 图片和多媒体
export 'package:cached_network_image/cached_network_image.dart'; // 缓存网络图片
export 'package:flutter_svg/flutter_svg.dart';    // SVG支持
export 'package:dd_js_util/dd_js_util.dart';      // 九宫格图片选择

// 富文本和格式化
export 'package:flutter_html/flutter_html.dart';  // HTML渲染
export 'package:sprintf/sprintf.dart';            // 字符串格式化
export 'package:auto_size_text/auto_size_text.dart'; // 自适应文本

// 交互组件
export 'package:bottom_sheet/bottom_sheet.dart';  // 底部弹出框
export 'package:visibility_detector/visibility_detector.dart'; // 可见性检测
export 'package:extended_tabs/extended_tabs.dart'; // 扩展Tab组件

// 图表组件
export 'package:fl_chart/fl_chart.dart';          // Flutter图表库

// 轮播组件  
export 'package:flutter_swiper_null_safety_flutter3/flutter_swiper_null_safety_flutter3.dart';
```

### 8. 工具类组件 (`src/utils/`)

丰富的工具类支持，涵盖图片处理、扫码、启动器等功能。

```dart
// 图片相关工具
export 'src/utils/image_util/image_util.dart';
export 'src/utils/image_solution/image_solution_tools.dart';
export 'src/utils/image_cropper_util/nativate_image_cropper.dart';

// 扫码相关
export 'src/utils/qr_processor/qr_processor.dart';
export 'src/utils/qr_scanner_util/qr_scanner_util.dart';

// 系统交互
export 'src/utils/launcher/launch_util.dart';     // URL启动器
export 'src/utils/imm/custom_imm.dart';           // 输入法管理

// 订单管理
export 'src/utils/order_category_manager/order_category_factory.dart';
export 'src/utils/order_category_manager/order_category_manager.dart';

// 其他工具
export 'src/utils/keep_alive.dart';               // KeepAlive包装器
export 'src/utils/widget_utils.dart';             // Widget工具类
export 'src/utils/methods.dart' show formatDate;  // 格式化方法
```

### 9. 特色组件

针对OneApp应用特点开发的专用组件。

```dart
// 车牌号相关
export 'src/components/one_license_plate_number/one_license_plate_number.dart';
export 'src/components/text_field/vehicle_plate_field/vehicle_plate_field_widget.dart';

// 车辆HVAC相关
export 'src/components/widgets/car_hvac_other_widget.dart';

// 香氛组件
export 'src/components/fragrance/fragrance_widget.dart';

// 步进器组件
export 'src/components/stepper/stepper_widget.dart';

// 验证码组件
export 'src/components/verification_code/verification_box.dart';
export 'src/components/verification_code/code_widget.dart';

// 时间选择器
export 'src/components/time_picker/common_time_picker.dart';
export 'src/components/time_picker/ym_time_picker.dart';

// 可扩展GridView
export 'src/components/gridview/expandable_gridview.dart';

// 瀑布流ScrollView
export 'src/components/widgets/staggered_scrollview_widget.dart';
export 'src/components/widgets/reorderable_staggered_scroll_view_widget.dart';
```

## 性能优化

### 组件优化策略
- **Widget缓存**: 缓存不变的Widget实例
- **局部更新**: 使用Consumer精确控制更新范围
- **延迟构建**: 使用Builder延迟构建复杂组件
- **内存管理**: 及时释放资源和控制器

### 渲染优化
- **RepaintBoundary**: 隔离重绘区域
- **ListView.builder**: 使用懒加载列表
- **Image优化**: 合理使用缓存和压缩
- **动画优化**: 使用硬件加速动画

## 测试策略

### Widget测试
- **组件渲染测试**: 验证组件正确渲染
- **交互测试**: 测试用户交互响应
- **主题测试**: 验证主题正确应用
- **响应式测试**: 测试不同屏幕尺寸适配

### 单元测试
- **工具类测试**: 测试工具方法功能
- **状态管理测试**: 测试状态变化逻辑
- **数据模型测试**: 测试数据序列化

## 最佳实践

### 组件设计原则
1. **单一职责**: 每个组件功能单一明确
2. **可复用性**: 设计通用的可复用组件
3. **可配置性**: 提供丰富的配置选项
4. **一致性**: 保持设计风格一致

### 使用建议
1. **主题使用**: 优先使用主题颜色和样式
2. **响应式设计**: 考虑不同屏幕尺寸适配
3. **无障碍访问**: 添加语义标签和辅助功能
4. **性能考虑**: 避免不必要的重建和重绘

## 总结

`ui_basic` 模块作为 OneApp 的基础UI组件库，提供了丰富的界面组件和交互元素。通过统一的设计语言、灵活的主题系统和完善的组件生态，为整个应用提供了一致的用户体验。模块具有良好的可扩展性和可维护性，能够满足各种界面开发需求。