keyboard/keyBoard/Class/AiTalk/V/KBChatTableView_Usage.md

KBChatTableView 使用说明

概述

KBChatTableView 是一个完整的聊天 UI 组件，支持：

• ✅ 用户消息（右侧气泡）
• ✅ AI 消息（左侧气泡 + 语音播放按钮）
• ✅ 时间戳（自动插入，5 分钟间隔）
• ✅ 语音播放功能
• ✅ 打字机效果

快速开始

1. 在 ViewController 中引入

#import "KBChatTableView.h"

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

2. 初始化并布局

- (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. 添加消息

添加用户消息

[self.chatView addUserMessage:@"你好"];

添加 AI 消息（带语音）

NSString *text = @"你好，很高兴见到你！";
NSTimeInterval duration = 6.0; // 6 秒
NSData *audioData = ...; // 从 TTS 获取的音频数据

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

添加 AI 消息（无语音）

[self.chatView addAssistantMessage:@"你好"
                     audioDuration:0
                         audioData:nil];

4. 打字机效果

// 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. 其他操作

// 清空所有消息
[self.chatView clearMessages];

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

集成到 KBAiMainVC

替换现有的 KBAiChatView

在 KBAiMainVC.m 中：

// 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):

self.bubbleView.backgroundColor = [UIColor colorWithRed:0.94 green:0.94 blue:0.94 alpha:1.0];

AI 消息 (KBChatAssistantMessageCell.m):

self.bubbleView.backgroundColor = [UIColor colorWithRed:0.2 green:0.2 blue:0.2 alpha:0.7];

修改时间戳间隔

在 KBChatTableView.m 中修改：

static const NSTimeInterval kTimestampInterval = 5 * 60; // 改为你想要的秒数

注意事项

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

完整示例

// 模拟对话
[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];
});