JSQMessagesViewController附件消息处理：文件传输功能实现
项目地址: https://gitcode.com/gh_mirrors/js/JSQMessagesViewController 你是否在开发聊天应用时遇到文件传输功能实现难题？是否想让用户轻松发送图片、音频、视频等多种类型附件？本文将带你从零开始，利用JSQMessagesViewController框架快速实现稳定高效的文件传输功能，让你的聊天应用体验更上一层楼。读完本文，你将掌握自定义文件消息类型、实现传输进度显示、处理网络异常等核心技能。
附件消息处理基础
JSQMessagesViewController通过JSQMediaItem类体系实现附件消息处理，所有文件传输功能均基于这一抽象基类扩展。该框架已内置图片、音频、视频和位置四种媒体类型支持，覆盖大多数常见聊天场景需求。
媒体消息核心类结构
框架将媒体消息分为文本消息和媒体消息两大类，通过JSQMessage的isMediaMessage属性区分。当isMediaMessage为YES时，消息内容存储在media属性中，该属性遵循JSQMessageMediaData协议，定义了媒体消息的基本行为。
媒体消息生命周期
媒体消息从创建到显示经历三个关键阶段：初始化、传输处理和完成显示。以图片消息为例，典型生命周期如下：
- 创建媒体项实例：使用
JSQPhotoMediaItem初始化，可选择立即提供图片数据或延迟加载 - 添加到消息队列：包装为
JSQMessage对象添加到数据源 - 显示占位视图：传输过程中显示加载指示器(JSQMessagesMediaPlaceholderView.h)
- 更新媒体数据：数据加载完成后更新媒体项属性
- 刷新UI显示：调用
collectionView.reloadData()更新界面
官方文档提供了完整的集成指南，详细说明如何配置基础媒体消息功能(Documentation/getting_started.md)。
内置文件类型传输实现
JSQMessagesViewController为常见文件类型提供了开箱即用的传输解决方案，无需从零开发核心功能。以下是三种主要文件类型的实现方法：
图片消息传输
图片消息通过JSQPhotoMediaItem实现，支持本地图片和网络图片两种加载方式。对于网络图片，推荐先初始化空媒体项，待下载完成后再更新图片数据：
// 创建图片媒体项（初始无图片）
JSQPhotoMediaItem *photoItem = [[JSQPhotoMediaItem alloc] initWithImage:nil];
photoItem.appliesMediaViewMaskAsOutgoing = YES;
// 创建消息对象
JSQMessage *message = [JSQMessage messageWithSenderId:senderId
senderDisplayName:displayName
date:[NSDate date]
media:photoItem];
// 添加到数据源
[self.messages addObject:message];
[self finishSendingMessageAnimated:YES];
// 异步下载图片
dispatch_async(dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_DEFAULT, 0), ^{
NSData *imageData = [NSData dataWithContentsOfURL:imageURL];
UIImage *image = [UIImage imageWithData:imageData];
dispatch_async(dispatch_get_main_queue(), ^{
// 更新图片数据
photoItem.image = image;
[self.collectionView reloadData];
});
});
框架提供了默认的图片气泡样式，通过JSQMessagesBubbleImageFactory类生成。如需自定义气泡样式，可修改气泡图片工厂配置：
// 创建自定义气泡样式
JSQMessagesBubbleImageFactory *bubbleFactory = [[JSQMessagesBubbleImageFactory alloc] init];
JSQMessagesBubbleImage *outgoingBubble = [bubbleFactory outgoingMessagesBubbleImageWithColor:[UIColor jsq_messageBubbleBlueColor]];
JSQMessagesBubbleImage *incomingBubble = [bubbleFactory incomingMessagesBubbleImageWithColor:[UIColor jsq_messageBubbleLightGrayColor]];
音频消息传输
音频消息通过JSQAudioMediaItem实现，支持本地文件和网络音频流。核心属性包括audioData（音频数据）和delegate（播放状态回调）：
// 创建音频媒体项
JSQAudioMediaViewAttributes *attributes = [[JSQAudioMediaViewAttributes alloc] init];
JSQAudioMediaItem *audioItem = [[JSQAudioMediaItem alloc] initWithData:nil audioViewAttributes:attributes];
audioItem.delegate = self;
// 设置音频数据（可来自文件或网络）
[audioItem setAudioDataWithUrl:audioFileURL];
// 创建并发送消息
JSQMessage *message = [JSQMessage messageWithSenderId:senderId
senderDisplayName:displayName
date:[NSDate date]
media:audioItem];
音频播放控制通过AVAudioPlayer实现，JSQAudioMediaItem已内置播放状态管理。如需自定义音频播放器UI，可通过audioViewAttributes属性配置进度条颜色、播放按钮样式等视觉属性。
视频消息传输
视频消息使用JSQVideoMediaItem类，通过fileURL指定视频资源路径，isReadyToPlay属性标识视频是否可播放状态：
// 创建视频媒体项（初始不可播放）
JSQVideoMediaItem *videoItem = [[JSQVideoMediaItem alloc] initWithFileURL:nil isReadyToPlay:NO];
videoItem.thumbnailImage = [self generateThumbnailFromVideoURL:videoURL];
// 创建消息
JSQMessage *message = [JSQMessage messageWithSenderId:senderId
senderDisplayName:displayName
date:[NSDate date]
media:videoItem];
// 异步准备视频
dispatch_async(dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_DEFAULT, 0), ^{
// 下载或处理视频文件...
dispatch_async(dispatch_get_main_queue(), ^{
videoItem.fileURL = processedVideoURL;
videoItem.isReadyToPlay = YES;
[self.collectionView reloadData];
});
});
视频缩略图可通过thumbnailImage属性设置，推荐在视频准备期间显示，提升用户体验。框架会自动处理视频播放界面，支持全屏切换和基本播放控制。
自定义文件类型实现
虽然框架提供了常见媒体类型支持，但实际开发中常需传输文档、压缩包等自定义文件类型。这时需要创建JSQMediaItem子类，实现自定义文件的传输和显示逻辑。
创建自定义文件媒体项
以PDF文件传输为例，创建JSQFileMediaItem子类：
// JSQFileMediaItem.h
#import "JSQMediaItem.h"
@interface JSQFileMediaItem : JSQMediaItem <JSQMessageMediaData, NSCoding, NSCopying>
@property (nonatomic, strong, nullable) NSData *fileData;
@property (nonatomic, copy, nullable) NSString *fileName;
@property (nonatomic, copy, nullable) NSString *fileType;
@property (nonatomic, assign) CGFloat fileSize;
- (instancetype)initWithFileData:(nullable NSData *)fileData
fileName:(NSString *)fileName
fileType:(NSString *)fileType;
@end
实现核心方法，重点关注媒体视图创建和尺寸计算：
// JSQFileMediaItem.m
@implementation JSQFileMediaItem
- (UIView *)mediaView {
if (self.fileData) {
UIView *fileView = [[UIView alloc] initWithFrame:CGRectMake(0, 0, 200, 60)];
fileView.backgroundColor = [UIColor lightGrayColor];
// 添加文件名标签
UILabel *nameLabel = [[UILabel alloc] initWithFrame:CGRectMake(10, 5, 150, 20)];
nameLabel.text = self.fileName;
nameLabel.font = [UIFont systemFontOfSize:14];
[fileView addSubview:nameLabel];
// 添加文件大小标签
NSString *sizeText = [NSString stringWithFormat:@"%.2f KB", self.fileSize/1024.0];
UILabel *sizeLabel = [[UILabel alloc] initWithFrame:CGRectMake(10, 30, 150, 20)];
sizeLabel.text = sizeText;
sizeLabel.font = [UIFont systemFontOfSize:12];
sizeLabel.textColor = [UIColor darkGrayColor];
[fileView addSubview:sizeLabel];
// 添加文件类型图标
UIImageView *iconView = [[UIImageView alloc] initWithFrame:CGRectMake(170, 5, 25, 25)];
iconView.image = [self fileTypeIcon];
[fileView addSubview:iconView];
// 应用气泡样式
[JSQMessagesMediaViewBubbleImageMasker applyBubbleImageMaskToMediaView:fileView isOutgoing:self.appliesMediaViewMaskAsOutgoing];
return fileView;
}
return [JSQMessagesMediaPlaceholderView viewWithActivityIndicator];
}
- (CGSize)mediaViewDisplaySize {
return CGSizeMake(200, 60); // 固定文件消息视图尺寸
}
// 根据文件类型返回对应图标
- (UIImage *)fileTypeIcon {
if ([self.fileType isEqualToString:@"pdf"]) {
return [UIImage imageNamed:@"pdf_icon"];
} else if ([self.fileType isEqualToString:@"doc"]) {
return [UIImage imageNamed:@"doc_icon"];
}
return [UIImage imageNamed:@"default_icon"];
}
@end
集成自定义文件类型到消息流
创建自定义媒体项后，需在消息视图控制器中注册并实现数据源方法：
// 在JSQMessagesViewController子类中
- (UICollectionViewCell *)collectionView:(UICollectionView *)collectionView cellForItemAtIndexPath:(NSIndexPath *)indexPath {
JSQMessagesCollectionViewCell *cell = [super collectionView:collectionView cellForItemAtIndexPath:indexPath];
JSQMessage *message = [self.messages objectAtIndex:indexPath.item];
if (message.isMediaMessage) {
id<JSQMessageMediaData> media = message.media;
if ([media isKindOfClass:[JSQFileMediaItem class]]) {
// 自定义文件消息处理
cell.mediaView.backgroundColor = [UIColor clearColor];
}
}
return cell;
}
文件传输高级功能
传输进度显示实现
为提升用户体验，文件传输过程中应显示进度指示器。可通过KVO监听文件传输进度，实时更新UI：
// 在自定义媒体项中添加进度属性
@property (nonatomic, assign) float progress;
// 传输文件时更新进度
- (void)startFileTransfer {
NSURLSessionDownloadTask *task = [self.session downloadTaskWithURL:self.remoteURL];
[task resume];
}
// 在NSURLSessionDownloadDelegate回调中
- (void)URLSession:(NSURLSession *)session downloadTask:(NSURLSessionDownloadTask *)downloadTask didWriteData:(int64_t)bytesWritten totalBytesWritten:(int64_t)totalBytesWritten totalBytesExpectedToWrite:(int64_t)totalBytesExpectedToWrite {
float progress = (float)totalBytesWritten / totalBytesExpectedToWrite;
self.progress = progress;
// 主线程更新UI
dispatch_async(dispatch_get_main_queue(), ^{
[self.delegate fileTransferProgressUpdated:self.progress];
});
}
在媒体视图中添加进度条控件，根据进度属性更新显示：
// 在mediaView方法中添加进度条
UIProgressView *progressView = [[UIProgressView alloc] initWithFrame:CGRectMake(10, 50, 180, 5)];
progressView.progress = self.progress;
progressView.tag = 1001; // 用于后续查找更新
[fileView addSubview:progressView];
// 提供更新进度的方法
- (void)updateProgress:(float)progress {
self.progress = progress;
UIProgressView *progressView = (UIProgressView *)[self.mediaView viewWithTag:1001];
progressView.progress = progress;
}
断点续传与网络异常处理
实际应用中需处理网络中断、文件过大等异常情况。可通过NSURLSession的后台下载功能实现断点续传：
// 配置支持后台传输的NSURLSession
NSURLSessionConfiguration *config = [NSURLSessionConfiguration backgroundSessionConfigurationWithIdentifier:@"file_transfer_session"];
self.session = [NSURLSession sessionWithConfiguration:config delegate:self delegateQueue:nil];
// 实现后台传输完成处理
- (void)URLSessionDidFinishEventsForBackgroundURLSession:(NSURLSession *)session {
dispatch_async(dispatch_get_main_queue(), ^{
if (self.completionHandler) {
self.completionHandler();
self.completionHandler = nil;
}
});
}
文件传输失败时，提供重试机制：
// 在媒体视图中添加重试按钮
UIButton *retryButton = [[UIButton alloc] initWithFrame:CGRectMake(170, 35, 25, 25)];
[retryButton setImage:[UIImage imageNamed:@"retry_icon"] forState:UIControlStateNormal];
[retryButton addTarget:self action:@selector(retryTransfer:) forControlEvents:UIControlEventTouchUpInside];
[fileView addSubview:retryButton];
气泡样式与媒体视图美化
JSQMessagesViewController提供了灵活的气泡样式定制功能，通过JSQMessagesBubbleImageFactory可创建各种形状和颜色的气泡：
// 创建带阴影的气泡样式
JSQMessagesBubbleImageFactory *factory = [[JSQMessagesBubbleImageFactory alloc] init];
factory.outgoingBubbleImageCapInsets = UIEdgeInsetsMake(22, 26, 22, 26);
factory.incomingBubbleImageCapInsets = UIEdgeInsetsMake(22, 26, 22, 26);
UIColor *outgoingColor = [UIColor colorWithRed:0.23 green:0.70 blue:0.92 alpha:1.00];
JSQMessagesBubbleImage *outgoingBubble = [factory outgoingMessagesBubbleImageWithColor:outgoingColor];
UIColor *incomingColor = [UIColor colorWithRed:0.88 green:0.88 blue:0.88 alpha:1.00];
JSQMessagesBubbleImage *incomingBubble = [factory incomingMessagesBubbleImageWithColor:incomingColor];
媒体视图遮罩通过JSQMessagesMediaViewBubbleImageMasker实现，确保媒体内容适配气泡形状：
// 应用气泡遮罩
[JSQMessagesMediaViewBubbleImageMasker applyBubbleImageMaskToMediaView:mediaView isOutgoing:YES];
完整文件传输流程示例
以下是一个完整的图片消息发送流程，包含选择图片、上传服务器、显示进度和最终显示的全流程：
// 1. 选择图片后回调
- (void)imagePickerController:(UIImagePickerController *)picker didFinishPickingMediaWithInfo:(NSDictionary<UIImagePickerControllerInfoKey,id> *)info {
[picker dismissViewControllerAnimated:YES completion:nil];
UIImage *selectedImage = info[UIImagePickerControllerOriginalImage];
// 2. 创建媒体项（初始无图片，显示加载指示器）
JSQPhotoMediaItem *photoItem = [[JSQPhotoMediaItem alloc] initWithImage:nil];
photoItem.appliesMediaViewMaskAsOutgoing = YES;
// 3. 创建消息并添加到数据源
JSQMessage *message = [JSQMessage messageWithSenderId:self.senderId
senderDisplayName:self.senderName
date:[NSDate date]
media:photoItem];
[self.messages addObject:message];
[self finishSendingMessageAnimated:YES];
// 4. 压缩并上传图片
NSData *imageData = UIImageJPEGRepresentation(selectedImage, 0.7);
[self uploadImageData:imageData toURL:[NSURL URLWithString:@"https://your-server.com/upload"] completion:^(NSURL *downloadURL, NSError *error) {
if (downloadURL) {
// 5. 下载完成后更新媒体项
dispatch_async(dispatch_get_main_queue(), ^{
photoItem.image = [UIImage imageWithData:imageData];
[self.collectionView reloadData];
});
} else {
// 处理上传失败
NSLog(@"Image upload failed: %@", error.localizedDescription);
}
} progress:^(float progress) {
// 6. 更新进度（可通过自定义属性实现）
photoItem.progress = progress;
[self.collectionView reloadItemsAtIndexPaths:@[[NSIndexPath indexPathForItem:self.messages.count-1 inSection:0]]];
}];
}
实际项目应用案例
示例应用中的媒体处理
JSQMessagesViewController提供的Demo项目展示了完整的媒体消息处理流程，包括图片选择、位置发送和音频录制等功能(JSQMessagesDemo/DemoMessagesViewController.m)。其中附件选择通过工具条按钮触发：
// DemoMessagesViewController.m 中的附件选择
- (void)didPressAccessoryButton:(UIButton *)sender {
[self.inputToolbar.contentView.textView resignFirstResponder];
UIActionSheet *sheet = [[UIActionSheet alloc] initWithTitle:NSLocalizedString(@"Media messages", nil)
delegate:self
cancelButtonTitle:NSLocalizedString(@"Cancel", nil)
destructiveButtonTitle:nil
otherButtonTitles:NSLocalizedString(@"Send photo", nil),
NSLocalizedString(@"Send location", nil),
NSLocalizedString(@"Send video", nil),
NSLocalizedString(@"Send audio", nil), nil];
[sheet showFromToolbar:self.inputToolbar];
}
选择不同选项会调用对应的媒体处理方法，如发送图片时调用addPhotoMediaMessage：
// DemoModelData.m
- (void)addPhotoMediaMessage {
UIImage *image = [UIImage imageNamed:@"goldengate"];
JSQPhotoMediaItem *photoItem = [[JSQPhotoMediaItem alloc] initWithImage:image];
photoItem.appliesMediaViewMaskAsOutgoing = YES;
JSQMessage *message = [JSQMessage messageWithSenderId:kJSQDemoAvatarIdSquires
senderDisplayName:kJSQDemoAvatarDisplayNameSquires
date:[NSDate date]
media:photoItem];
[self.messages addObject:message];
}
性能优化建议
处理大量媒体消息时，需注意以下性能优化点：
- 图片压缩：发送前压缩图片尺寸和质量，推荐使用
UIImageJPEGRepresentation并设置适当压缩率 - 懒加载：仅加载当前可见区域的媒体内容，滚动时暂停加载
- 缓存策略：使用
NSCache缓存已加载的媒体内容，避免重复下载 - 异步处理：所有网络请求和媒体处理放在后台线程执行
- 内存管理：及时清理不可见的媒体视图缓存，调用
clearCachedMediaViews方法
总结与后续学习
JSQMessagesViewController提供了强大的媒体消息处理框架，通过JSQMediaItem体系可轻松实现各类文件传输功能。核心要点包括：
- 利用内置媒体项处理图片、音频和视频传输
- 通过继承
JSQMediaItem实现自定义文件类型 - 使用
JSQMessagesMediaPlaceholderView显示传输状态 - 应用气泡遮罩美化媒体消息外观
官方文档(Documentation/getting_started.md)提供了更多高级功能说明，建议深入阅读源码中的注释了解内部实现机制。
下一步可探索：
- 实现文件预览功能
- 添加文件大小限制和类型过滤
- 集成云存储服务（如AWS S3）优化文件传输
- 添加文件消息的长按菜单（保存、转发等功能）
掌握这些技能后，你将能够构建媲美商业聊天应用的文件传输体验，为用户提供流畅便捷的多媒体通信功能。
如果你觉得本文对你有帮助，请点赞收藏并关注后续教程，下期将带来"JSQMessagesViewController高级定制：气泡动画与主题切换"。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
