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

KBChatTableView API 快速参考

📦 Import

#import "KBChatTableView.h"

---

🎯 初始化

KBChatTableView *chatView = [[KBChatTableView alloc] init];
[self.view addSubview:chatView];

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

---

📝 API 方法

添加用户消息

- (void)addUserMessage:(NSString *)text;

示例：

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

---

添加 AI 消息（带语音）

- (void)addAssistantMessage:(NSString *)text
              audioDuration:(NSTimeInterval)duration
                  audioData:(nullable NSData *)audioData;

示例：

// 有语音
[self.chatView addAssistantMessage:@"你好！"
                     audioDuration:3.0
                         audioData:audioData];

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

---

更新最后一条 AI 消息（打字机效果）

- (void)updateLastAssistantMessage:(NSString *)text;

示例：

// 1. 先添加空消息
[self.chatView addAssistantMessage:@"" audioDuration:0 audioData:nil];

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

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

---

标记最后一条 AI 消息完成

- (void)markLastAssistantMessageComplete;

---

清空所有消息

- (void)clearMessages;

---

滚动到底部

- (void)scrollToBottom;

---

🎨 消息类型

KBChatMessage

@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

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

---

🔊 音频时长计算

方法 1：使用 AVAudioPlayer（推荐）

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：估算（不准确）

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

---

⏰ 时间戳规则

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

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

时间格式：

• 今天：16:36
• 昨天：昨天 16:36
• 其他：01月23日 16:36

---

🎯 完整示例

// 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 中：

static const NSTimeInterval kTimestampInterval = 5 * 60; // 秒

修改气泡颜色

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

---

⚠️ 注意事项

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

---

🔗 相关文档

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