350 lines
8.9 KiB
Markdown
350 lines
8.9 KiB
Markdown
|
# Basic UIs 基础UI组件模块群
|
|||
|
|
|
|||
|
|
## 模块群概述
|
|||
|
|
|
|||
|
|
Basic UIs 模块群是 OneApp 的用户界面基础设施，提供了完整的UI组件生态系统。该模块群包含了基础UI组件、业务UI组件和通用UI组件，为整个应用提供统一的设计语言和用户体验。
|
|||
|
|
|
|||
|
|
## 子模块列表
|
|||
|
|
|
|||
|
|
### 核心UI组件
|
|||
|
|
1. **[ui_basic](./ui_basic.md)** - 基础UI组件库
|
|||
|
|
- 按钮、输入框、卡片等基础组件
|
|||
|
|
- 布局容器和交互组件
|
|||
|
|
- 主题系统和响应式设计
|
|||
|
|
|
|||
|
|
2. **[ui_business](./ui_business.md)** - 业务UI组件库
|
|||
|
|
- 车辆状态展示组件
|
|||
|
|
- 消息中心组件
|
|||
|
|
- 地理位置组件
|
|||
|
|
- 用户同意组件
|
|||
|
|
|
|||
|
|
3. **[basic_uis](./basic_uis.md)** - 通用UI组件集合
|
|||
|
|
- 组件库整合和统一导出
|
|||
|
|
- 跨模块UI组件管理
|
|||
|
|
- 全局UI配置和工具
|
|||
|
|
|
|||
|
|
4. **[general_ui_component](./general_ui_component.md)** - 通用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. 可扩展性原则
|
|||
|
|
- **插件化**: 支持组件插件化扩展
|
|||
|
|
- **主题化**: 支持多主题和自定义主题
|
|||
|
|
- **国际化**: 支持多语言和本地化
|
|||
|
|
- **配置化**: 通过配置控制组件行为
|
|||
|
|
|
|||
|
|
## 主题系统
|
|||
|
|
|
|||
|
|
### 主题架构
|
|||
|
|
```dart
|
|||
|
|
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)
|
|||
|
|
```dart
|
|||
|
|
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. 组件结构
|
|||
|
|
```dart
|
|||
|
|
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
|
|||
|
|
/// 车辆状态卡片组件
|
|||
|
|
///
|
|||
|
|
/// 用于展示车辆的基本状态信息，包括电量、里程、锁定状态等。
|
|||
|
|
/// 支持点击交互和自定义样式。
|
|||
|
|
///
|
|||
|
|
/// 示例用法：
|
|||
|
|
/// ```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. 单元测试
|
|||
|
|
```dart
|
|||
|
|
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. 发布流程
|
|||
|
|
```bash
|
|||
|
|
# 1. 运行测试
|
|||
|
|
flutter test
|
|||
|
|
|
|||
|
|
# 2. 更新版本号
|
|||
|
|
# 编辑 pubspec.yaml
|
|||
|
|
|
|||
|
|
# 3. 更新变更日志
|
|||
|
|
# 编辑 CHANGELOG.md
|
|||
|
|
|
|||
|
|
# 4. 发布包
|
|||
|
|
flutter pub publish
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 使用指南
|
|||
|
|
|
|||
|
|
### 1. 快速开始
|
|||
|
|
```dart
|
|||
|
|
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. 组件使用
|
|||
|
|
```dart
|
|||
|
|
// 基础组件使用
|
|||
|
|
BasicButton(
|
|||
|
|
text: '确定',
|
|||
|
|
type: ButtonType.primary,
|
|||
|
|
onPressed: () {},
|
|||
|
|
)
|
|||
|
|
|
|||
|
|
// 业务组件使用
|
|||
|
|
VehicleStatusCard(
|
|||
|
|
status: vehicleStatus,
|
|||
|
|
onTap: () {},
|
|||
|
|
)
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 3. 主题定制
|
|||
|
|
```dart
|
|||
|
|
MaterialApp(
|
|||
|
|
theme: OneAppTheme.lightTheme.copyWith(
|
|||
|
|
primarySwatch: Colors.green,
|
|||
|
|
// 其他自定义配置
|
|||
|
|
),
|
|||
|
|
)
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 最佳实践
|
|||
|
|
|
|||
|
|
### 1. 组件设计
|
|||
|
|
- **单一职责**: 每个组件功能单一明确
|
|||
|
|
- **可组合性**: 支持组件组合使用
|
|||
|
|
- **可配置性**: 提供丰富的配置选项
|
|||
|
|
- **可预测性**: 相同输入产生相同输出
|
|||
|
|
|
|||
|
|
### 2. API设计
|
|||
|
|
- **直观性**: API命名直观易理解
|
|||
|
|
- **一致性**: 相似功能API保持一致
|
|||
|
|
- **扩展性**: 预留扩展空间
|
|||
|
|
- **文档化**: 提供完整文档和示例
|
|||
|
|
|
|||
|
|
### 3. 性能考虑
|
|||
|
|
- **懒加载**: 按需加载减少初始化开销
|
|||
|
|
- **缓存策略**: 合理使用缓存提升性能
|
|||
|
|
- **异步处理**: 避免阻塞UI线程
|
|||
|
|
- **资源管理**: 及时释放不需要的资源
|
|||
|
|
|
|||
|
|
## 总结
|
|||
|
|
|
|||
|
|
Basic UIs 模块群为 OneApp 提供了完整的UI基础设施，通过分层设计、统一规范和完善的工具链，实现了高效的UI开发和一致的用户体验。模块群具有良好的可扩展性和可维护性，能够支撑大型应用的UI需求，并为未来的功能扩展提供了坚实的基础。
|