447 lines
10 KiB
Markdown
447 lines
10 KiB
Markdown
# UI AvatarX 虚拟形象UI组件
|
||
|
||
## 模块概述
|
||
|
||
`ui_avatarx` 是 OneApp 车联网生态中的虚拟形象UI组件库，负责虚拟形象的界面展示、交互控制、动画效果和用户体验优化等功能。该模块为虚拟助手提供了丰富的UI组件和交互体验。
|
||
|
||
### 基本信息
|
||
- **模块名称**: ui_avatarx
|
||
- **版本**: 0.4.7+3
|
||
- **描述**: 虚拟形象UI组件库
|
||
- **Flutter 版本**: >=2.5.0
|
||
- **Dart 版本**: >=2.16.2 <4.0.0
|
||
|
||
## 功能特性
|
||
|
||
### 核心功能
|
||
1. **虚拟形象展示**
|
||
- 3D虚拟形象渲染
|
||
- 2D头像展示
|
||
- 表情动画播放
|
||
- 状态指示器
|
||
|
||
2. **交互组件**
|
||
- 语音交互界面
|
||
- 手势控制组件
|
||
- 触控反馈效果
|
||
- 情绪表达控件
|
||
|
||
3. **动画效果**
|
||
- 流畅的转场动画
|
||
- 表情切换动画
|
||
- 状态变化动画
|
||
- 自定义动画序列
|
||
|
||
4. **主题定制**
|
||
- 多种形象主题
|
||
- 可定制外观
|
||
- 响应式布局
|
||
- 暗黑模式支持
|
||
|
||
## 技术架构
|
||
|
||
### 目录结构
|
||
```
|
||
lib/
|
||
├── ui_avatarx.dart # 模块入口文件
|
||
├── src/ # 源代码目录
|
||
│ ├── widgets/ # UI组件
|
||
│ ├── animations/ # 动画效果
|
||
│ ├── themes/ # 主题配置
|
||
│ ├── controllers/ # 控制器
|
||
│ ├── models/ # 数据模型
|
||
│ └── utils/ # 工具类
|
||
├── assets/ # 资源文件
|
||
└── examples/ # 示例代码
|
||
```
|
||
|
||
### 依赖关系
|
||
|
||
#### 核心依赖
|
||
- `basic_logger` - 日志系统（本地路径依赖）
|
||
|
||
#### Flutter框架
|
||
- `flutter` - Flutter SDK
|
||
|
||
## 核心模块分析
|
||
|
||
### 1. 模块入口 (`ui_avatarx.dart`)
|
||
|
||
**功能职责**:
|
||
- UI组件对外接口导出
|
||
- 主题配置初始化
|
||
- 组件注册管理
|
||
|
||
### 2. UI组件 (`src/widgets/`)
|
||
|
||
**功能职责**:
|
||
- 虚拟形象展示组件
|
||
- 交互控制组件
|
||
- 状态指示组件
|
||
- 自定义装饰组件
|
||
|
||
**主要组件**:
|
||
- `AvatarXWidget` - 主虚拟形象组件
|
||
- `AvatarXHead` - 头像组件
|
||
- `ExpressionPanel` - 表情控制面板
|
||
- `VoiceIndicator` - 语音指示器
|
||
- `EmotionSelector` - 情绪选择器
|
||
- `AvatarXContainer` - 形象容器
|
||
- `InteractionOverlay` - 交互覆盖层
|
||
|
||
### 3. 动画效果 (`src/animations/`)
|
||
|
||
**功能职责**:
|
||
- 表情动画控制
|
||
- 转场动画实现
|
||
- 自定义动画序列
|
||
- 动画状态管理
|
||
|
||
**主要动画**:
|
||
- `ExpressionAnimation` - 表情动画
|
||
- `TransitionAnimation` - 转场动画
|
||
- `IdleAnimation` - 待机动画
|
||
- `InteractionAnimation` - 交互动画
|
||
- `EmotionAnimation` - 情绪动画
|
||
|
||
### 4. 主题配置 (`src/themes/`)
|
||
|
||
**功能职责**:
|
||
- 主题样式定义
|
||
- 颜色配置管理
|
||
- 尺寸规范设置
|
||
- 响应式配置
|
||
|
||
**主要主题**:
|
||
- `DefaultAvatarTheme` - 默认主题
|
||
- `DarkAvatarTheme` - 暗黑主题
|
||
- `CustomAvatarTheme` - 自定义主题
|
||
- `ResponsiveTheme` - 响应式主题
|
||
|
||
### 5. 控制器 (`src/controllers/`)
|
||
|
||
**功能职责**:
|
||
- 虚拟形象状态控制
|
||
- 动画播放控制
|
||
- 交互事件处理
|
||
- 生命周期管理
|
||
|
||
**主要控制器**:
|
||
- `AvatarXController` - 主控制器
|
||
- `AnimationController` - 动画控制器
|
||
- `InteractionController` - 交互控制器
|
||
- `ThemeController` - 主题控制器
|
||
|
||
### 6. 数据模型 (`src/models/`)
|
||
|
||
**功能职责**:
|
||
- 虚拟形象数据模型
|
||
- 动画配置模型
|
||
- 主题配置模型
|
||
- 状态信息模型
|
||
|
||
**主要模型**:
|
||
- `AvatarXModel` - 虚拟形象模型
|
||
- `ExpressionModel` - 表情模型
|
||
- `AnimationConfig` - 动画配置模型
|
||
- `ThemeConfig` - 主题配置模型
|
||
- `InteractionState` - 交互状态模型
|
||
|
||
### 7. 工具类 (`src/utils/`)
|
||
|
||
**功能职责**:
|
||
- 动画工具方法
|
||
- 主题工具函数
|
||
- 布局计算工具
|
||
- 性能优化工具
|
||
|
||
**主要工具**:
|
||
- `AnimationUtils` - 动画工具
|
||
- `ThemeUtils` - 主题工具
|
||
- `LayoutUtils` - 布局工具
|
||
- `PerformanceUtils` - 性能工具
|
||
|
||
## 组件设计
|
||
|
||
### 核心组件详解
|
||
|
||
#### AvatarXWidget
|
||
```dart
|
||
class AvatarXWidget extends StatefulWidget {
|
||
final AvatarXModel avatar;
|
||
final AvatarXController? controller;
|
||
final AvatarTheme? theme;
|
||
final double? width;
|
||
final double? height;
|
||
final bool enableInteraction;
|
||
final VoidCallback? onTap;
|
||
final Function(String)? onExpressionChanged;
|
||
|
||
const AvatarXWidget({
|
||
Key? key,
|
||
required this.avatar,
|
||
this.controller,
|
||
this.theme,
|
||
this.width,
|
||
this.height,
|
||
this.enableInteraction = true,
|
||
this.onTap,
|
||
this.onExpressionChanged,
|
||
}) : super(key: key);
|
||
|
||
@override
|
||
State<AvatarXWidget> createState() => _AvatarXWidgetState();
|
||
}
|
||
```
|
||
|
||
**主要功能**:
|
||
- 虚拟形象渲染展示
|
||
- 交互事件处理
|
||
- 动画状态管理
|
||
- 主题样式应用
|
||
|
||
#### ExpressionPanel
|
||
```dart
|
||
class ExpressionPanel extends StatelessWidget {
|
||
final List<String> expressions;
|
||
final String? currentExpression;
|
||
final Function(String) onExpressionSelected;
|
||
final bool showLabels;
|
||
final Axis direction;
|
||
|
||
const ExpressionPanel({
|
||
Key? key,
|
||
required this.expressions,
|
||
this.currentExpression,
|
||
required this.onExpressionSelected,
|
||
this.showLabels = true,
|
||
this.direction = Axis.horizontal,
|
||
}) : super(key: key);
|
||
}
|
||
```
|
||
|
||
**主要功能**:
|
||
- 表情选择界面
|
||
- 表情预览功能
|
||
- 选择状态指示
|
||
- 可定制布局方向
|
||
|
||
#### VoiceIndicator
|
||
```dart
|
||
class VoiceIndicator extends StatefulWidget {
|
||
final bool isListening;
|
||
final bool isSpeaking;
|
||
final double amplitude;
|
||
final Color? color;
|
||
final double size;
|
||
final VoiceIndicatorStyle style;
|
||
|
||
const VoiceIndicator({
|
||
Key? key,
|
||
this.isListening = false,
|
||
this.isSpeaking = false,
|
||
this.amplitude = 0.0,
|
||
this.color,
|
||
this.size = 60.0,
|
||
this.style = VoiceIndicatorStyle.wave,
|
||
}) : super(key: key);
|
||
}
|
||
```
|
||
|
||
**主要功能**:
|
||
- 语音状态可视化
|
||
- 音频波形显示
|
||
- 实时振幅反映
|
||
- 多种视觉样式
|
||
|
||
## 动画系统
|
||
|
||
### 动画类型
|
||
1. **表情动画**
|
||
- 面部表情切换
|
||
- 眼部动作
|
||
- 嘴部动作
|
||
- 眉毛表情
|
||
|
||
2. **身体动画**
|
||
- 头部转动
|
||
- 肩膀动作
|
||
- 手势动作
|
||
- 姿态变化
|
||
|
||
3. **交互动画**
|
||
- 点击反馈
|
||
- 悬停效果
|
||
- 拖拽响应
|
||
- 状态转换
|
||
|
||
4. **环境动画**
|
||
- 背景变化
|
||
- 光照效果
|
||
- 粒子效果
|
||
- 氛围营造
|
||
|
||
### 动画控制
|
||
```dart
|
||
class AnimationController {
|
||
Future<void> playExpression(String expression, {
|
||
Duration duration = const Duration(milliseconds: 500),
|
||
Curve curve = Curves.easeInOut,
|
||
});
|
||
|
||
Future<void> playSequence(List<AnimationStep> steps);
|
||
|
||
void pauseAnimation();
|
||
void resumeAnimation();
|
||
void stopAnimation();
|
||
|
||
Stream<AnimationState> get animationState;
|
||
}
|
||
```
|
||
|
||
## 主题系统
|
||
|
||
### 主题配置
|
||
```dart
|
||
class AvatarTheme {
|
||
final Color primaryColor;
|
||
final Color secondaryColor;
|
||
final Color backgroundColor;
|
||
final TextStyle labelStyle;
|
||
final EdgeInsets padding;
|
||
final BorderRadius borderRadius;
|
||
final BoxShadow? shadow;
|
||
final AvatarSize size;
|
||
|
||
const AvatarTheme({
|
||
required this.primaryColor,
|
||
required this.secondaryColor,
|
||
required this.backgroundColor,
|
||
required this.labelStyle,
|
||
this.padding = const EdgeInsets.all(8.0),
|
||
this.borderRadius = const BorderRadius.all(Radius.circular(8.0)),
|
||
this.shadow,
|
||
this.size = AvatarSize.medium,
|
||
});
|
||
}
|
||
```
|
||
|
||
### 响应式设计
|
||
- **屏幕尺寸适配**: 自动调整组件大小
|
||
- **密度适配**: 支持不同像素密度
|
||
- **方向适配**: 横竖屏自适应
|
||
- **平台适配**: iOS/Android样式适配
|
||
|
||
## 性能优化
|
||
|
||
### 渲染优化
|
||
- **组件缓存**: 缓存渲染结果
|
||
- **差分更新**: 仅更新变化部分
|
||
- **懒加载**: 按需加载资源
|
||
- **预加载**: 预测性资源加载
|
||
|
||
### 内存管理
|
||
- **资源释放**: 及时释放不需要的资源
|
||
- **内存池**: 复用对象减少GC
|
||
- **弱引用**: 避免内存泄漏
|
||
- **监控告警**: 内存使用监控
|
||
|
||
### 动画优化
|
||
- **硬件加速**: 利用GPU加速
|
||
- **帧率控制**: 智能帧率调节
|
||
- **插值优化**: 高效插值算法
|
||
- **批量更新**: 批量处理动画更新
|
||
|
||
## 交互设计
|
||
|
||
### 手势支持
|
||
1. **点击手势**
|
||
- 单击激活
|
||
- 双击特殊功能
|
||
- 长按菜单
|
||
- 多点触控
|
||
|
||
2. **滑动手势**
|
||
- 水平滑动切换
|
||
- 垂直滑动控制
|
||
- 旋转手势
|
||
- 缩放手势
|
||
|
||
3. **自定义手势**
|
||
- 手势识别器
|
||
- 手势回调
|
||
- 手势反馈
|
||
- 手势组合
|
||
|
||
### 反馈机制
|
||
- **视觉反馈**: 动画和颜色变化
|
||
- **触觉反馈**: 震动反馈
|
||
- **听觉反馈**: 音效提示
|
||
- **语音反馈**: 语音确认
|
||
|
||
## 可访问性
|
||
|
||
### 无障碍支持
|
||
- **语义标签**: 为屏幕阅读器提供标签
|
||
- **焦点管理**: 键盘导航支持
|
||
- **对比度**: 高对比度模式
|
||
- **字体缩放**: 支持系统字体缩放
|
||
|
||
### 国际化支持
|
||
- **多语言**: 支持多语言界面
|
||
- **RTL布局**: 从右到左文字支持
|
||
- **文化适配**: 不同文化的视觉适配
|
||
- **时区处理**: 时间显示本地化
|
||
|
||
## 测试策略
|
||
|
||
### 单元测试
|
||
- **组件渲染测试**: Widget渲染正确性
|
||
- **动画逻辑测试**: 动画状态转换
|
||
- **主题应用测试**: 主题配置正确性
|
||
- **工具类测试**: 工具方法功能
|
||
|
||
### Widget测试
|
||
- **交互测试**: 用户交互响应
|
||
- **状态测试**: 组件状态变化
|
||
- **布局测试**: 响应式布局
|
||
- **性能测试**: 渲染性能
|
||
|
||
### 集成测试
|
||
- **端到端测试**: 完整用户流程
|
||
- **兼容性测试**: 不同设备适配
|
||
- **性能测试**: 真实设备性能
|
||
- **可访问性测试**: 无障碍功能
|
||
|
||
## 部署和维护
|
||
|
||
### 版本管理
|
||
- **API稳定性**: 向后兼容保证
|
||
- **渐进式升级**: 平滑版本升级
|
||
- **功能开关**: 新功能渐进发布
|
||
- **回滚策略**: 问题版本快速回滚
|
||
|
||
### 监控指标
|
||
- **组件使用率**: 各组件使用频率
|
||
- **性能指标**: 渲染性能和内存使用
|
||
- **用户体验**: 交互响应时间
|
||
- **错误率**: 组件异常发生率
|
||
|
||
## 最佳实践
|
||
|
||
### 开发建议
|
||
1. **组件复用**: 优先使用现有组件
|
||
2. **主题一致**: 遵循设计系统
|
||
3. **性能考虑**: 避免过度渲染
|
||
4. **可测试性**: 编写可测试代码
|
||
|
||
### 使用指南
|
||
1. **合理选择**: 根据场景选择合适组件
|
||
2. **配置优化**: 合理配置组件参数
|
||
3. **资源管理**: 注意资源生命周期
|
||
4. **用户体验**: 关注用户交互体验
|
||
|
||
## 总结
|
||
|
||
`ui_avatarx` 模块作为 OneApp 的虚拟形象UI组件库，提供了丰富的虚拟形象展示和交互能力。通过模块化的组件设计、灵活的主题系统和流畅的动画效果，为用户提供了优秀的虚拟助手交互体验。模块具有良好的性能优化和可访问性支持，能够适应不同的设备和使用场景。
|