# KBChatTableView 使用说明

## 概述

`KBChatTableView` 是一个完整的聊天 UI 组件，支持：
- ✅ 用户消息（右侧气泡）
- ✅ AI 消息（左侧气泡 + 语音播放按钮）
- ✅ 时间戳（自动插入，5 分钟间隔）
- ✅ 语音播放功能
- ✅ 打字机效果

## 快速开始

### 1. 在 ViewController 中引入

```objective-c
#import "KBChatTableView.h"

@interface YourViewController ()
@property (nonatomic, strong) KBChatTableView *chatView;
@end
```

### 2. 初始化并布局

```objective-c
- (void)viewDidLoad {
    [super viewDidLoad];
    
    self.chatView = [[KBChatTableView alloc] init];
    self.chatView.backgroundColor = [UIColor clearColor];
    [self.view addSubview:self.chatView];
    
    [self.chatView mas_makeConstraints:^(MASConstraintMaker *make) {
        make.top.equalTo(self.view.mas_safeAreaLayoutGuideTop);
        make.left.right.equalTo(self.view);
        make.bottom.equalTo(self.recordButton.mas_top).offset(-16);
    }];
}
```

### 3. 添加消息

#### 添加用户消息
```objective-c
[self.chatView addUserMessage:@"你好"];
```

#### 添加 AI 消息（带语音）
```objective-c
NSString *text = @"你好，很高兴见到你！";
NSTimeInterval duration = 6.0; // 6 秒
NSData *audioData = ...; // 从 TTS 获取的音频数据

[self.chatView addAssistantMessage:text
                     audioDuration:duration
                         audioData:audioData];
```

#### 添加 AI 消息（无语音）
```objective-c
[self.chatView addAssistantMessage:@"你好"
                     audioDuration:0
                         audioData:nil];
```

### 4. 打字机效果

```objective-c
// 1. 添加空消息占位
[self.chatView addAssistantMessage:@""
                     audioDuration:0
                         audioData:nil];

// 2. 逐步更新文本
[self.chatView updateLastAssistantMessage:@"你"];
[self.chatView updateLastAssistantMessage:@"你好"];
[self.chatView updateLastAssistantMessage:@"你好，"];
[self.chatView updateLastAssistantMessage:@"你好，很高兴见到你！"];

// 3. 标记完成
[self.chatView markLastAssistantMessageComplete];
```

### 5. 其他操作

```objective-c
// 清空所有消息
[self.chatView clearMessages];

// 滚动到底部
[self.chatView scrollToBottom];
```

## 集成到 KBAiMainVC

### 替换现有的 KBAiChatView

在 `KBAiMainVC.m` 中：

```objective-c
// 1. 修改 import
#import "KBChatTableView.h"

// 2. 修改属性声明
@property (nonatomic, strong) KBChatTableView *chatView;

// 3. 在 setupUI 中初始化
self.chatView = [[KBChatTableView alloc] init];
self.chatView.backgroundColor = [UIColor clearColor];
[self.view addSubview:self.chatView];

[self.chatView mas_makeConstraints:^(MASConstraintMaker *make) {
    make.top.equalTo(self.transcriptLabel.mas_bottom).offset(8);
    make.left.right.equalTo(self.view);
    make.bottom.lessThanOrEqualTo(self.recordButton.mas_top).offset(-16);
}];

// 4. 在 Deepgram 回调中添加消息
- (void)deepgramStreamingManagerDidReceiveFinalTranscript:(NSString *)text {
    // ... 现有代码 ...
    
    // 添加用户消息
    [self.chatView addUserMessage:finalText];
    
    // AI 回复完成后
    [self.chatView addAssistantMessage:polishedText
                         audioDuration:audioData.length / 16000.0 // 估算时长
                             audioData:audioData];
}
```

## 时间戳显示规则

时间戳会在以下情况自动插入：
1. 第一条消息
2. 距离上一条消息超过 5 分钟
3. 跨天的消息

时间格式：
- 今天：`16:36`
- 昨天：`昨天 16:36`
- 其他：`01月23日 16:36`

## 语音播放

- 点击语音按钮播放音频
- 播放时按钮变为暂停图标
- 点击其他消息的语音按钮会停止当前播放
- 播放完成后自动恢复播放图标

## 自定义样式

### 修改气泡颜色

在对应的 Cell 文件中修改：

**用户消息** (`KBChatUserMessageCell.m`):
```objective-c
self.bubbleView.backgroundColor = [UIColor colorWithRed:0.94 green:0.94 blue:0.94 alpha:1.0];
```

**AI 消息** (`KBChatAssistantMessageCell.m`):
```objective-c
self.bubbleView.backgroundColor = [UIColor colorWithRed:0.2 green:0.2 blue:0.2 alpha:0.7];
```

### 修改时间戳间隔

在 `KBChatTableView.m` 中修改：
```objective-c
static const NSTimeInterval kTimestampInterval = 5 * 60; // 改为你想要的秒数
```

## 注意事项

1. **音频数据格式**：确保传入的 `audioData` 是 AVAudioPlayer 支持的格式（如 MP3、AAC）
2. **内存管理**：大量消息时考虑分页加载
3. **线程安全**：UI 更新需要在主线程执行
4. **音频会话**：播放音频前确保配置了 AVAudioSession

## 完整示例

```objective-c
// 模拟对话
[self.chatView addUserMessage:@"你好"];

dispatch_after(dispatch_time(DISPATCH_TIME_NOW, 1 * NSEC_PER_SEC), dispatch_get_main_queue(), ^{
    NSString *aiText = @"你好！很高兴见到你，有什么可以帮助你的吗？";
    NSData *audioData = [self generateMockAudioData]; // 模拟音频数据
    [self.chatView addAssistantMessage:aiText
                         audioDuration:6.0
                             audioData:audioData];
});
```