252 lines
5.8 KiB
Markdown
252 lines
5.8 KiB
Markdown
# 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`
|