ai_chat_assistant/README_ChatPopup.md

ChatFloatingIcon 和 ChatPopup 组件说明

这两个组件用于替代原来的 FloatingIcon，解决了在 Stack 中会被上层遮挡的问题。

组件结构

ChatFloatingIcon

可拖拽的悬浮图标组件，支持：

• 自定义图标和大小
• 拖拽功能（自动吸附屏幕边缘）
• 长按开始语音输入
• 点击进入全屏聊天
• 多种动画效果

ChatPopup

基于 Overlay 的弹窗容器，负责：

• 管理 PartScreen 的显示/隐藏
• 根据图标位置自动计算弹窗位置
• 处理背景点击关闭
• 动画效果管理

使用方法

基本使用（默认AI图标）

ChatPopup(
  child: ChatFloatingIcon(
    iconSize: 80, // 可选，默认80
  ),
),

自定义图标

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),
    ),
  ),
),

添加自定义回调

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 迁移

原来的代码：

Stack(
  children: [
    // 其他内容
    FloatingIcon(),
  ],
)

新的代码：

Stack(
  children: [
    // 其他内容
    ChatPopup(
      child: ChatFloatingIcon(),
    ),
  ],
)

注意事项

1. ChatPopup 必须在有 Overlay 的 Widget 树中使用（通常是 MaterialApp 下）
2. 如果要自定义图标，建议保持圆形设计以匹配拖拽动画
3. 长按语音输入功能需要 MessageService 正确配置
4. 位置计算基于屏幕坐标，确保在正确的上下文中使用