# 会话组件自动滚动底部规则文档

> 本文档描述了 `chat-conversation-component` 会话组件中自动滚动到底部的完整逻辑规则。
> 
> **最后更新**: 2025-12-30

---

## 核心状态变量

| 变量名 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| `autoToLastMsg` | `boolean` | `false` | 是否启用自动滚动到底部 |
| `scrollTouch` | `boolean` | `false` | 用户是否正在触摸滚动（touchend 后延迟 300ms 重置） |
| `mouseScroll` | `boolean` | `false` | 鼠标滚轮是否在滚动（H5专用） |
| `scrollInBottom` | `boolean` | `true` | 当前视图是否在底部 |
| `needSetLockAutoToLastMsg` | `boolean` | `true` | 是否需要检查锁定自动滚动 |
| `scrollIntoView` | `string` | `''` | 滚动目标元素ID，设为 `"last-msg"` 触发滚动 |

**文件位置**: `layers/AgentDetailData.uts`

---

## 触发自动滚动的场景

### 1. 发送消息时
- **代码位置**: `chat-conversation-component.uvue` → `handleSendMessage`
- **行为**: 设置 `autoToLastMsg = true`，调用 `scrollToLastMsg(false)`

### 2. 加载历史消息时
- **代码位置**: `layers/AgentDetailService.uts` → `handleQueryConversation`
- **行为**: 设置 `autoToLastMsg = true`

### 3. 点击"滚动到底部"按钮
- **代码位置**: `layers/ScrollManager.uts` → `scrollToLastMsg`
- **行为**: 设置 `autoToLastMsg = true`，`scrollIntoView = "last-msg"`

### 4. 流式消息更新时
- **代码位置**: `layers/AgentDetailService.uts` → `handleChangeMessageList`
- **行为**: 当 `autoToLastMsg = true` 时，发送 `streamMessageUpdate` 事件
- **响应**: 100ms 防抖后调用 `scrollToLastMsg(false)`

### 5. 消息列表/建议列表变化时
- **代码位置**: `chat-conversation-component.uvue`
- **行为**: 通过 watch 监听，调用 `handleScrollToLastMsg()`

---

## 取消自动滚动的情况

### 1. 用户主动向上滚动
- **条件**: 触摸/鼠标滚动 + 向上滚动 + 距离底部 > 50px
- **代码位置**: `layers/ScrollManager.uts` → `setIsInScrollBottom`

### 2. 消息列表为空
- **代码位置**: `layers/ScrollManager.uts` → `lockAutoToLastMsg`

---

## 滚动检测逻辑（兼容微信小程序）

```typescript
// 使用事件参数获取滚动信息
const scrollTop = e?.detail?.scrollTop ?? 0
const scrollHeight = e?.detail?.scrollHeight ?? 0

// 微信小程序使用估算值，其他平台使用 DOM 查询
// #ifdef MP-WEIXIN
const offsetHeight = 600
// #endif
// #ifndef MP-WEIXIN
const offsetHeight = uni.getElementById('msg-list')?.offsetHeight ?? 600
// #endif

const diff = scrollHeight - scrollTop - offsetHeight

// 判断是否在底部（距离 < 30px）
scrollInBottom = diff < 30

// 用户向上滚动时，距离超过 50px 才禁用自动滚动
if ((scrollTouch || mouseScroll) && isScrollingUp) {
    autoToLastMsg = diff <= 50
}
```

---

## 事件总线

| 事件名 | 发送位置 | 监听位置 | 用途 |
|--------|---------|---------|------|
| `streamMessageUpdate` | `AgentDetailService.uts` | `chat-conversation-component.uvue` | 流式消息更新触发滚动（100ms防抖）|
| `updateMessageComponent` | `AgentDetailService.uts` | `chat-conversation-component.uvue` | 更新消息组件内容 |

---

## 平台兼容性

| 平台 | 触摸检测 | 鼠标检测 | DOM 查询 |
|------|----------|----------|----------|
| 微信小程序 | `touchstart/end/cancel` | 不适用 | 使用事件参数 |
| H5/Web | `touchstart/end/cancel` | `wheel` 事件 | `uni.getElementById` |
| App | `touchstart/end/cancel` | 不适用 | `uni.getElementById` |

---

## 相关文件

| 文件 | 职责 |
|------|------|
| `layers/AgentDetailData.uts` | 状态变量定义 |
| `layers/ScrollManager.uts` | 滚动逻辑管理（跨平台兼容）|
| `layers/AgentDetailService.uts` | 消息处理与事件触发 |
| `chat-conversation-component.uvue` | 主组件，事件监听与 watch |