10 KiB
10 KiB
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
功能特性
核心功能
-
虚拟形象展示
- 3D虚拟形象渲染
- 2D头像展示
- 表情动画播放
- 状态指示器
-
交互组件
- 语音交互界面
- 手势控制组件
- 触控反馈效果
- 情绪表达控件
-
动画效果
- 流畅的转场动画
- 表情切换动画
- 状态变化动画
- 自定义动画序列
-
主题定制
- 多种形象主题
- 可定制外观
- 响应式布局
- 暗黑模式支持
技术架构
目录结构
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
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
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
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);
}
主要功能:
- 语音状态可视化
- 音频波形显示
- 实时振幅反映
- 多种视觉样式
动画系统
动画类型
-
表情动画
- 面部表情切换
- 眼部动作
- 嘴部动作
- 眉毛表情
-
身体动画
- 头部转动
- 肩膀动作
- 手势动作
- 姿态变化
-
交互动画
- 点击反馈
- 悬停效果
- 拖拽响应
- 状态转换
-
环境动画
- 背景变化
- 光照效果
- 粒子效果
- 氛围营造
动画控制
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;
}
主题系统
主题配置
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加速
- 帧率控制: 智能帧率调节
- 插值优化: 高效插值算法
- 批量更新: 批量处理动画更新
交互设计
手势支持
-
点击手势
- 单击激活
- 双击特殊功能
- 长按菜单
- 多点触控
-
滑动手势
- 水平滑动切换
- 垂直滑动控制
- 旋转手势
- 缩放手势
-
自定义手势
- 手势识别器
- 手势回调
- 手势反馈
- 手势组合
反馈机制
- 视觉反馈: 动画和颜色变化
- 触觉反馈: 震动反馈
- 听觉反馈: 音效提示
- 语音反馈: 语音确认
可访问性
无障碍支持
- 语义标签: 为屏幕阅读器提供标签
- 焦点管理: 键盘导航支持
- 对比度: 高对比度模式
- 字体缩放: 支持系统字体缩放
国际化支持
- 多语言: 支持多语言界面
- RTL布局: 从右到左文字支持
- 文化适配: 不同文化的视觉适配
- 时区处理: 时间显示本地化
测试策略
单元测试
- 组件渲染测试: Widget渲染正确性
- 动画逻辑测试: 动画状态转换
- 主题应用测试: 主题配置正确性
- 工具类测试: 工具方法功能
Widget测试
- 交互测试: 用户交互响应
- 状态测试: 组件状态变化
- 布局测试: 响应式布局
- 性能测试: 渲染性能
集成测试
- 端到端测试: 完整用户流程
- 兼容性测试: 不同设备适配
- 性能测试: 真实设备性能
- 可访问性测试: 无障碍功能
部署和维护
版本管理
- API稳定性: 向后兼容保证
- 渐进式升级: 平滑版本升级
- 功能开关: 新功能渐进发布
- 回滚策略: 问题版本快速回滚
监控指标
- 组件使用率: 各组件使用频率
- 性能指标: 渲染性能和内存使用
- 用户体验: 交互响应时间
- 错误率: 组件异常发生率
最佳实践
开发建议
- 组件复用: 优先使用现有组件
- 主题一致: 遵循设计系统
- 性能考虑: 避免过度渲染
- 可测试性: 编写可测试代码
使用指南
- 合理选择: 根据场景选择合适组件
- 配置优化: 合理配置组件参数
- 资源管理: 注意资源生命周期
- 用户体验: 关注用户交互体验
总结
ui_avatarx 模块作为 OneApp 的虚拟形象UI组件库，提供了丰富的虚拟形象展示和交互能力。通过模块化的组件设计、灵活的主题系统和流畅的动画效果，为用户提供了优秀的虚拟助手交互体验。模块具有良好的性能优化和可访问性支持，能够适应不同的设备和使用场景。