127 lines
2.9 KiB
Markdown
127 lines
2.9 KiB
Markdown
# ChatFloatingIcon 和 ChatPopup 组件说明
|
||
|
||
这两个组件用于替代原来的 `FloatingIcon`，解决了在 Stack 中会被上层遮挡的问题。
|
||
|
||
## 组件结构
|
||
|
||
### ChatFloatingIcon
|
||
可拖拽的悬浮图标组件，支持：
|
||
- 自定义图标和大小
|
||
- 拖拽功能（自动吸附屏幕边缘）
|
||
- 长按开始语音输入
|
||
- 点击进入全屏聊天
|
||
- 多种动画效果
|
||
|
||
### ChatPopup
|
||
基于 Overlay 的弹窗容器，负责：
|
||
- 管理 PartScreen 的显示/隐藏
|
||
- 根据图标位置自动计算弹窗位置
|
||
- 处理背景点击关闭
|
||
- 动画效果管理
|
||
|
||
## 使用方法
|
||
|
||
### 基本使用（默认AI图标）
|
||
```dart
|
||
ChatPopup(
|
||
child: ChatFloatingIcon(
|
||
iconSize: 80, // 可选，默认80
|
||
),
|
||
),
|
||
```
|
||
|
||
### 自定义图标
|
||
```dart
|
||
ChatPopup(
|
||
child: ChatFloatingIcon(
|
||
iconSize: 60,
|
||
icon: Container(
|
||
width: 60,
|
||
height: 60,
|
||
decoration: const BoxDecoration(
|
||
color: Colors.blue,
|
||
shape: BoxShape.circle,
|
||
),
|
||
child: const Icon(Icons.chat, color: Colors.white),
|
||
),
|
||
),
|
||
),
|
||
```
|
||
|
||
### 添加自定义回调
|
||
```dart
|
||
ChatPopup(
|
||
child: ChatFloatingIcon(
|
||
iconSize: 70,
|
||
onTap: () {
|
||
// 自定义点击事件
|
||
},
|
||
onPositionChanged: (position) {
|
||
// 位置变化回调
|
||
},
|
||
onDragStart: () {
|
||
// 拖拽开始
|
||
},
|
||
onDragEnd: () {
|
||
// 拖拽结束
|
||
},
|
||
),
|
||
),
|
||
```
|
||
|
||
## 参数说明
|
||
|
||
### ChatFloatingIcon 参数
|
||
- `iconSize`: 图标大小，默认80
|
||
- `icon`: 自定义图标Widget，不传则使用默认AI图标
|
||
- `onTap`: 点击回调，默认进入全屏聊天
|
||
- `onLongPress`: 长按开始回调，默认开始语音输入
|
||
- `onLongPressUp`: 长按结束回调，默认结束语音输入
|
||
- `onLongPressEnd`: 长按结束详细回调
|
||
- `onDragStart`: 拖拽开始回调
|
||
- `onDragEnd`: 拖拽结束回调
|
||
- `onPositionChanged`: 位置变化回调
|
||
|
||
### ChatPopup 参数
|
||
- `child`: 子组件，通常是ChatFloatingIcon
|
||
- `chatSize`: 聊天框大小，默认320x450
|
||
|
||
## 功能特性
|
||
|
||
1. **避免遮挡**: 使用 Overlay 显示弹窗，不会被 Stack 上层遮挡
|
||
2. **位置自适应**: 根据图标位置自动计算弹窗显示位置
|
||
3. **保持原有逻辑**: 与原 FloatingIcon 功能完全兼容
|
||
4. **灵活自定义**: 支持自定义图标、回调等
|
||
5. **动画丰富**: 保持原有的各种动画效果
|
||
|
||
## 迁移指南
|
||
|
||
### 从 FloatingIcon 迁移
|
||
原来的代码：
|
||
```dart
|
||
Stack(
|
||
children: [
|
||
// 其他内容
|
||
FloatingIcon(),
|
||
],
|
||
)
|
||
```
|
||
|
||
新的代码：
|
||
```dart
|
||
Stack(
|
||
children: [
|
||
// 其他内容
|
||
ChatPopup(
|
||
child: ChatFloatingIcon(),
|
||
),
|
||
],
|
||
)
|
||
```
|
||
|
||
## 注意事项
|
||
|
||
1. ChatPopup 必须在有 Overlay 的 Widget 树中使用（通常是 MaterialApp 下）
|
||
2. 如果要自定义图标，建议保持圆形设计以匹配拖拽动画
|
||
3. 长按语音输入功能需要 MessageService 正确配置
|
||
4. 位置计算基于屏幕坐标，确保在正确的上下文中使用 |