1

keyBoard/Class/AiTalk/V/API_快速参考.md

@@ -0,0 +1,251 @@
+# 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`