# KBChatTableView API 快速参考

## 📦 Import

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

---

## 🎯 初始化

```objective-c
KBChatTableView *chatView = [[KBChatTableView alloc] init];
[self.view addSubview:chatView];

[chatView mas_makeConstraints:^(MASConstraintMaker *make) {
    make.edges.equalTo(self.view);
}];
```

---

## 📝 API 方法

### 添加用户消息
```objective-c
- (void)addUserMessage:(NSString *)text;
```

**示例：**
```objective-c
[self.chatView addUserMessage:@"你好"];
```

---

### 添加 AI 消息（带语音）
```objective-c
- (void)addAssistantMessage:(NSString *)text
              audioDuration:(NSTimeInterval)duration
                  audioData:(nullable NSData *)audioData;
```

**示例：**
```objective-c
// 有语音
[self.chatView addAssistantMessage:@"你好！"
                     audioDuration:3.0
                         audioData:audioData];

// 无语音
[self.chatView addAssistantMessage:@"你好！"
                     audioDuration:0
                         audioData:nil];
```

---

### 更新最后一条 AI 消息（打字机效果）
```objective-c
- (void)updateLastAssistantMessage:(NSString *)text;
```

**示例：**
```objective-c
// 1. 先添加空消息
[self.chatView addAssistantMessage:@"" audioDuration:0 audioData:nil];

// 2. 逐步更新
[self.chatView updateLastAssistantMessage:@"你"];
[self.chatView updateLastAssistantMessage:@"你好"];
[self.chatView updateLastAssistantMessage:@"你好！"];

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

---

### 标记最后一条 AI 消息完成
```objective-c
- (void)markLastAssistantMessageComplete;
```

---

### 清空所有消息
```objective-c
- (void)clearMessages;
```

---

### 滚动到底部
```objective-c
- (void)scrollToBottom;
```

---

## 🎨 消息类型

### KBChatMessage

```objective-c
@interface KBChatMessage : NSObject

@property (nonatomic, assign) KBChatMessageType type;
@property (nonatomic, copy) NSString *text;
@property (nonatomic, strong) NSDate *timestamp;
@property (nonatomic, assign) NSTimeInterval audioDuration;
@property (nonatomic, strong, nullable) NSData *audioData;
@property (nonatomic, assign) BOOL isComplete;

// 便捷构造方法
+ (instancetype)userMessageWithText:(NSString *)text;
+ (instancetype)assistantMessageWithText:(NSString *)text
                           audioDuration:(NSTimeInterval)duration
                               audioData:(nullable NSData *)audioData;
+ (instancetype)timeMessageWithTimestamp:(NSDate *)timestamp;

@end
```

### KBChatMessageType

```objective-c
typedef NS_ENUM(NSInteger, KBChatMessageType) {
    KBChatMessageTypeUser,      // 用户消息
    KBChatMessageTypeAssistant, // AI 回复
    KBChatMessageTypeTime       // 时间戳
};
```

---

## 🔊 音频时长计算

### 方法 1：使用 AVAudioPlayer（推荐）

```objective-c
NSError *error = nil;
AVAudioPlayer *player = [[AVAudioPlayer alloc] initWithData:audioData error:&error];
NSTimeInterval duration = player ? player.duration : 0;

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

### 方法 2：估算（不准确）

```objective-c
// 假设：16kHz 采样率，单声道，16 位
NSTimeInterval duration = audioData.length / (16000.0 * 1 * 2);
```

---

## ⏰ 时间戳规则

时间戳自动插入，无需手动添加：

- ✅ 第一条消息
- ✅ 距离上一条消息 > 5 分钟
- ✅ 跨天的消息

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

---

## 🎯 完整示例

```objective-c
// 1. 用户发送消息
[self.chatView addUserMessage:@"你好"];

// 2. AI 回复（带语音）
NSString *aiText = @"你好！很高兴见到你。";
NSData *audioData = ...; // 从 TTS 获取

NSError *error = nil;
AVAudioPlayer *player = [[AVAudioPlayer alloc] initWithData:audioData error:&error];
NSTimeInterval duration = player ? player.duration : 0;

[self.chatView addAssistantMessage:aiText
                     audioDuration:duration
                         audioData:audioData];

// 3. 打字机效果
[self.chatView addAssistantMessage:@"" audioDuration:0 audioData:nil];

// 模拟流式返回
dispatch_after(dispatch_time(DISPATCH_TIME_NOW, 0.1 * NSEC_PER_SEC), dispatch_get_main_queue(), ^{
    [self.chatView updateLastAssistantMessage:@"正"];
});
dispatch_after(dispatch_time(DISPATCH_TIME_NOW, 0.2 * NSEC_PER_SEC), dispatch_get_main_queue(), ^{
    [self.chatView updateLastAssistantMessage:@"正在"];
});
dispatch_after(dispatch_time(DISPATCH_TIME_NOW, 0.3 * NSEC_PER_SEC), dispatch_get_main_queue(), ^{
    [self.chatView updateLastAssistantMessage:@"正在思考"];
});
dispatch_after(dispatch_time(DISPATCH_TIME_NOW, 0.4 * NSEC_PER_SEC), dispatch_get_main_queue(), ^{
    [self.chatView updateLastAssistantMessage:@"正在思考..."];
    [self.chatView markLastAssistantMessageComplete];
});
```

---

## 🎨 自定义配置

### 修改时间戳间隔

在 `KBChatTableView.m` 中：
```objective-c
static const NSTimeInterval kTimestampInterval = 5 * 60; // 秒
```

### 修改气泡颜色

**用户消息**（`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];
```

---

## ⚠️ 注意事项

1. **音频格式**：MP3、AAC、M4A 等 AVAudioPlayer 支持的格式
2. **线程安全**：UI 更新必须在主线程
3. **内存管理**：大量消息时考虑限制数量
4. **音频会话**：确保配置了 AVAudioSession

---

## 🔗 相关文档

- 详细使用说明：`KBChatTableView_Usage.md`
- 集成指南：`集成指南.md`
- 测试页面：`KBChatTestVC.h/m`