oneapp_docs/basic_uis

Basic UIs 基础UI组件模块群

模块群概述

Basic UIs 模块群是 OneApp 的用户界面基础设施，提供了完整的UI组件生态系统。该模块群包含了基础UI组件、业务UI组件和通用UI组件，为整个应用提供统一的设计语言和用户体验。

子模块列表

核心UI组件

1. ui_basic - 基础UI组件库

   • 按钮、输入框、卡片等基础组件
   • 布局容器和交互组件
   • 主题系统和响应式设计

2. ui_business - 业务UI组件库

   • 车辆状态展示组件
   • 消息中心组件
   • 地理位置组件
   • 用户同意组件

3. basic_uis - 通用UI组件集合

   • 组件库整合和统一导出
   • 跨模块UI组件管理
   • 全局UI配置和工具

4. general_ui_component - 通用UI组件

   • 可复用的通用组件
   • 跨业务场景组件
   • 第三方组件封装

模块架构

分层设计

应用层 UI 组件
    ↓
业务层 UI 组件 (ui_business)
    ↓
基础层 UI 组件 (ui_basic)
    ↓
Flutter Framework

组件分类

1. 基础组件层 (ui_basic)

• 原子组件: Button, TextField, Icon, Text
• 分子组件: Card, ListTile, AppBar, Dialog
• 布局组件: Container, Row, Column, Stack
• 交互组件: GestureDetector, InkWell, RefreshIndicator

2. 业务组件层 (ui_business)

• 车辆组件: VehicleStatusCard, VehicleControlPanel
• 消息组件: MessageListView, MessageTile
• 位置组件: LocationPicker, MapView
• 表单组件: BusinessForm, ConsentDialog

3. 通用组件层 (basic_uis & general_ui_component)

• 复合组件: SearchBar, NavigationDrawer
• 特效组件: AnimatedWidget, TransitionWidget
• 工具组件: LoadingOverlay, ErrorBoundary

设计原则

1. 一致性原则

• 视觉一致性: 统一的颜色、字体、间距规范
• 交互一致性: 统一的交互模式和反馈机制
• 行为一致性: 相同功能组件的行为保持一致

2. 可访问性原则

• 语义标签: 为屏幕阅读器提供清晰的语义
• 键盘导航: 支持键盘和辅助设备导航
• 对比度: 满足无障碍对比度要求
• 字体缩放: 支持系统字体缩放设置

3. 响应式原则

• 屏幕适配: 适应不同屏幕尺寸和密度
• 方向适配: 支持横竖屏切换
• 设备适配: 针对手机、平板的优化
• 性能适配: 根据设备性能调整渲染策略

4. 可扩展性原则

• 插件化: 支持组件插件化扩展
• 主题化: 支持多主题和自定义主题
• 国际化: 支持多语言和本地化
• 配置化: 通过配置控制组件行为

主题系统

主题架构

class OneAppTheme {
  // 颜色系统
  static ColorScheme get colorScheme => ColorScheme.fromSeed(
    seedColor: const Color(0xFF1976D2),
  );
  
  // 字体系统
  static TextTheme get textTheme => const TextTheme(
    displayLarge: TextStyle(fontSize: 32, fontWeight: FontWeight.bold),
    titleLarge: TextStyle(fontSize: 20, fontWeight: FontWeight.w600),
    bodyLarge: TextStyle(fontSize: 16, fontWeight: FontWeight.normal),
  );
  
  // 组件主题
  static ThemeData get lightTheme => ThemeData(
    useMaterial3: true,
    colorScheme: colorScheme,
    textTheme: textTheme,
    appBarTheme: const AppBarTheme(/* ... */),
    elevatedButtonTheme: ElevatedButtonThemeData(/* ... */),
  );
}

设计令牌 (Design Tokens)

class DesignTokens {
  // 间距系统
  static const double spacingXs = 4.0;
  static const double spacingSm = 8.0;
  static const double spacingMd = 16.0;
  static const double spacingLg = 24.0;
  static const double spacingXl = 32.0;
  
  // 圆角系统
  static const double radiusXs = 4.0;
  static const double radiusSm = 8.0;
  static const double radiusMd = 12.0;
  static const double radiusLg = 16.0;
  
  // 阴影系统
  static const List<BoxShadow> shadowSm = [
    BoxShadow(
      color: Color(0x0D000000),
      blurRadius: 2,
      offset: Offset(0, 1),
    ),
  ];
}

组件开发规范

1. 组件结构

class ExampleComponent extends StatelessWidget {
  // 1. 必需参数
  final String title;
  
  // 2. 可选参数
  final String? subtitle;
  final VoidCallback? onTap;
  
  // 3. 样式参数
  final TextStyle? titleStyle;
  final EdgeInsets? padding;
  
  // 4. 构造函数
  const ExampleComponent({
    Key? key,
    required this.title,
    this.subtitle,
    this.onTap,
    this.titleStyle,
    this.padding,
  }) : super(key: key);

  @override
  Widget build(BuildContext context) {
    return Container(/* 实现 */);
  }
}

2. 命名规范

• 组件名称: 使用PascalCase，如 VehicleStatusCard
• 参数名称: 使用camelCase，如 onPressed
• 常量名称: 使用camelCase，如 defaultPadding
• 枚举名称: 使用PascalCase，如 ButtonType

3. 文档规范

/// 车辆状态卡片组件
/// 
/// 用于展示车辆的基本状态信息，包括电量、里程、锁定状态等。
/// 支持点击交互和自定义样式。
/// 
/// 示例用法：
/// ```dart
/// VehicleStatusCard(
///   status: vehicleStatus,
///   onTap: () => Navigator.push(...),
/// )
/// ```
class VehicleStatusCard extends StatelessWidget {
  /// 车辆状态数据
  final VehicleStatus status;
  
  /// 点击回调函数
  final VoidCallback? onTap;
}

性能优化策略

1. 渲染优化

• Widget缓存: 缓存不变的Widget实例
• RepaintBoundary: 隔离重绘区域
• Const构造: 使用const构造函数
• Build优化: 避免在build方法中创建对象

2. 内存优化

• 资源释放: 及时释放Controller和Stream
• 图片缓存: 合理使用图片缓存策略
• 对象池: 复用频繁创建的对象
• 弱引用: 避免内存泄漏

3. 加载优化

• 懒加载: 按需加载组件和资源
• 预加载: 预测性加载关键资源
• 分包加载: 大型组件分包异步加载
• 缓存策略: 智能缓存机制

测试策略

1. 单元测试

testWidgets('VehicleStatusCard displays correct information', (tester) async {
  const status = VehicleStatus(
    vehicleName: 'Test Vehicle',
    batteryLevel: 80,
    isLocked: true,
  );

  await tester.pumpWidget(
    MaterialApp(
      home: VehicleStatusCard(status: status),
    ),
  );

  expect(find.text('Test Vehicle'), findsOneWidget);
  expect(find.text('80%'), findsOneWidget);
  expect(find.byIcon(Icons.lock), findsOneWidget);
});

2. Widget测试

• 渲染测试: 验证组件正确渲染
• 交互测试: 测试用户交互响应
• 状态测试: 测试状态变化
• 样式测试: 验证样式正确应用

3. 集成测试

• 页面流程测试: 测试完整用户流程
• 性能测试: 测试组件性能表现
• 兼容性测试: 测试不同设备兼容性
• 可访问性测试: 测试无障碍功能

构建和发布

1. 版本管理

• 语义化版本: 遵循 semver 规范
• 变更日志: 详细的变更记录
• 向后兼容: 保证API向后兼容
• 废弃通知: 提前通知API废弃

2. 发布流程

# 1. 运行测试
flutter test

# 2. 更新版本号
# 编辑 pubspec.yaml

# 3. 更新变更日志
# 编辑 CHANGELOG.md

# 4. 发布包
flutter pub publish

使用指南

1. 快速开始

import 'package:ui_basic/ui_basic.dart';
import 'package:ui_business/ui_business.dart';

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      theme: OneAppTheme.lightTheme,
      home: MyHomePage(),
    );
  }
}

2. 组件使用

// 基础组件使用
BasicButton(
  text: '确定',
  type: ButtonType.primary,
  onPressed: () {},
)

// 业务组件使用
VehicleStatusCard(
  status: vehicleStatus,
  onTap: () {},
)

3. 主题定制

MaterialApp(
  theme: OneAppTheme.lightTheme.copyWith(
    primarySwatch: Colors.green,
    // 其他自定义配置
  ),
)

最佳实践

1. 组件设计

• 单一职责: 每个组件功能单一明确
• 可组合性: 支持组件组合使用
• 可配置性: 提供丰富的配置选项
• 可预测性: 相同输入产生相同输出

2. API设计

• 直观性: API命名直观易理解
• 一致性: 相似功能API保持一致
• 扩展性: 预留扩展空间
• 文档化: 提供完整文档和示例

3. 性能考虑

• 懒加载: 按需加载减少初始化开销
• 缓存策略: 合理使用缓存提升性能
• 异步处理: 避免阻塞UI线程
• 资源管理: 及时释放不需要的资源

总结

Basic UIs 模块群为 OneApp 提供了完整的UI基础设施，通过分层设计、统一规范和完善的工具链，实现了高效的UI开发和一致的用户体验。模块群具有良好的可扩展性和可维护性，能够支撑大型应用的UI需求，并为未来的功能扩展提供了坚实的基础。