ai_chat_assistant/README_ChatPopup.md

# 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. 位置计算基于屏幕坐标，确保在正确的上下文中使用