1

keyBoard/Class/AiTalk/V/KBChatTableView_Usage.md

@@ -0,0 +1,195 @@
+# 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];
+});
+```