TZImagePickerController使用指南：从新手到专家
项目地址: https://gitcode.com/gh_mirrors/tz/TZImagePickerController 引言：告别原生相册选择器的痛点
你是否还在为UIImagePickerController的功能单一而烦恼？是否需要一个支持多选、原图、视频且兼容iOS10+的图片选择解决方案？本文将系统讲解TZImagePickerController的安装配置、核心功能、高级定制及性能优化，帮助开发者在15分钟内掌握这个功能全面的图片选择框架。
读完本文你将获得：
- 3种快速集成方式（CocoaPods/Carthage/手动）
- 多选/原图/视频选择的完整实现
- 10+自定义UI样式的实用技巧
- 性能优化与常见问题解决方案
- 从基础使用到源码级定制的全流程指南
一、框架概述与核心优势
TZImagePickerController是一个功能增强版的图片选择框架，作为UIImagePickerController的替代品，它提供了以下核心特性：
核心优势对比
| 功能特性 | TZImagePickerController | 系统UIImagePickerController |
|---|---|---|
| 多选支持 | ✅ 支持9张以上批量选择 | ❌ 仅支持单选 |
| 原图选项 | ✅ 可选择原图/压缩图 | ❌ 不支持 |
| 视频处理 | ✅ 支持选择/预览/编辑 | ❌ 基础支持 |
| 预览功能 | ✅ 内置预览控制器 | ❌ 需自定义 |
| UI定制 | ✅ 全面自定义接口 | ❌ 几乎不可定制 |
| 最低支持 | ✅ iOS10+ | ✅ iOS2+ |
二、快速集成指南
2.1 CocoaPods安装（推荐）
# 完整版本（包含所有功能）
pod 'TZImagePickerController'
# 基础版本（不含定位功能）
pod 'TZImagePickerController/Basic'
⚠️ 注意：执行
pod search若无法找到最新版本，请执行以下命令更新本地spec缓存：cd ~/Desktop && pod setup
2.2 Carthage安装
github "banchichen/TZImagePickerController"
2.3 手动安装
- 克隆仓库：
git clone https://gitcode.com/gh_mirrors/tz/TZImagePickerController.git
- 将
TZImagePickerController文件夹拖拽至项目 - 导入头文件：
#import "TZImagePickerController.h"
2.4 必要的Info.plist配置
添加以下隐私权限描述（根据实际使用功能选择）：
<key>Privacy - Camera Usage Description</key>
<string>需要访问相机拍摄照片</string>
<key>Privacy - Photo Library Usage Description</key>
<string>需要访问相册选择照片</string>
<key>Privacy - Microphone Usage Description</key>
<string>需要访问麦克风录制视频</string>
<key>Privacy - Location When In Use Usage Description</key>
<string>需要访问位置信息用于照片定位</string>
<key>Prevent limited photos access alert</key>
<true/>
三、基础功能实现
3.1 最简实现代码
// 导入头文件
#import "TZImagePickerController.h"
// 遵循代理
@interface ViewController () <TZImagePickerControllerDelegate>
@end
// 实现选择功能
- (void)showImagePicker {
// 初始化选择器（最大选择9张）
TZImagePickerController *imagePicker = [[TZImagePickerController alloc]
initWithMaxImagesCount:9
delegate:self];
// 设置完成回调（block方式）
[imagePicker setDidFinishPickingPhotosHandle:^(NSArray<UIImage *> *photos,
NSArray *assets,
BOOL isSelectOriginalPhoto) {
// 处理选中的照片
self.selectedPhotos = photos;
[self.collectionView reloadData];
}];
// 模态展示
[self presentViewController:imagePicker animated:YES completion:nil];
}
// 代理方式处理结果（二选一）
- (void)imagePickerController:(TZImagePickerController *)picker
didFinishPickingPhotos:(NSArray<UIImage *> *)photos
sourceAssets:(NSArray *)assets
isSelectOriginalPhoto:(BOOL)isSelectOriginalPhoto {
// 处理选中结果
[picker dismissViewControllerAnimated:YES completion:nil];
}
3.2 核心属性配置
// 基本配置
imagePicker.maxImagesCount = 9; // 最大选择数
imagePicker.allowPickingOriginalPhoto = YES; // 允许选原图
imagePicker.allowPickingVideo = YES; // 允许选视频
imagePicker.allowPreview = YES; // 允许预览
// 高级配置
imagePicker.photoWidth = 828; // 导出图片宽度
imagePicker.showSelectedIndex = YES; // 显示选择序号
imagePicker.autoDismiss = YES; // 自动dismiss
imagePicker.preferredLanguage = @"zh-Hans"; // 优先中文
四、高级功能详解
4.1 视频选择与编辑
// 配置视频选择
imagePicker.allowPickingVideo = YES;
imagePicker.allowEditVideo = YES; // 允许编辑视频
imagePicker.videoMaximumDuration = 60; // 最长录制时间(秒)
imagePicker.presetName = AVAssetExportPresetMediumQuality; // 导出质量
// 视频选择回调
imagePicker.didFinishPickingVideoHandle = ^(UIImage *coverImage, PHAsset *asset) {
NSLog(@"视频封面: %@, 资源: %@", coverImage, asset);
};
// 视频编辑回调
imagePicker.didFinishPickingAndEditingVideoHandle = ^(UIImage *coverImage, NSString *outputPath, NSString *errorMsg) {
if (errorMsg) {
NSLog(@"视频编辑失败: %@", errorMsg);
} else {
NSLog(@"编辑后视频路径: %@", outputPath);
}
};
4.2 图片裁剪功能
// 单选模式下启用裁剪
imagePicker.allowCrop = YES; // 允许裁剪
imagePicker.cropRect = CGRectMake(0, 0, 300, 300); // 裁剪区域
imagePicker.needCircleCrop = YES; // 圆形裁剪框
imagePicker.scaleAspectFillCrop = YES; // 等比填充裁剪
4.3 自定义UI样式
// 导航栏样式
imagePicker.naviBgColor = [UIColor whiteColor];
imagePicker.naviTitleColor = [UIColor blackColor];
imagePicker.naviTitleFont = [UIFont systemFontOfSize:18 weight:UIFontWeightMedium];
// 按钮样式
imagePicker.oKButtonTitleColorNormal = [UIColor systemBlueColor];
imagePicker.doneBtnTitleStr = @"完成";
imagePicker.cancelBtnTitleStr = @"取消";
// 选中图标颜色
imagePicker.iconThemeColor = [UIColor colorWithRed:31/255.0 green:185/255.0 blue:34/255.0 alpha:1.0];
// 自定义单元格样式
imagePicker.assetCellDidSetModelBlock = ^(TZAssetCell *cell, UIImageView *imageView, UIImageView *selectImageView, UILabel *indexLabel, UIView *bottomView, UILabel *timeLength, UIImageView *videoImgView) {
// 设置选中框样式
selectImageView.layer.cornerRadius = 15;
selectImageView.layer.borderWidth = 2;
};
4.4 多语言支持
// 设置首选语言
imagePicker.preferredLanguage = @"en"; // 英文
// imagePicker.preferredLanguage = @"zh-Hant"; // 繁体中文
// imagePicker.preferredLanguage = @"vi"; // 越南语
// 自定义语言包
NSBundle *customBundle = [NSBundle bundleWithPath:[[NSBundle mainBundle] pathForResource:@"custom" ofType:@"bundle"]];
imagePicker.languageBundle = customBundle;
五、性能优化策略
5.1 内存优化配置
// 限制GIF预览帧数（默认50帧）
[TZImagePickerConfig sharedInstance].gifPreviewMaxImagesCount = 30;
// 关闭图片缩放（默认YES）
imagePicker.notScaleImage = NO;
// 控制并发数（通过修改源码实现）
// 在TZImageManager.m中调整NSOperationQueue的maxConcurrentOperationCount
5.2 大列表优化
// 使用基础版本（无定位功能）
pod 'TZImagePickerController/Basic'
// 实现资源过滤（只显示符合条件的资源）
- (BOOL)isAssetCanBeDisplayed:(PHAsset *)asset {
// 过滤过小的图片
if (asset.pixelWidth < 300 || asset.pixelHeight < 300) {
return NO;
}
return YES;
}
5.3 iCloud资源处理
// 显示iCloud资源下载进度（默认已实现）
// 可在TZAssetCell.m中自定义进度条样式
// 处理iCloud同步错误
imagePicker.didFinishPickingPhotosHandle = ^(NSArray<UIImage *> *photos, NSArray *assets, BOOL isSelectOriginalPhoto) {
for (NSDictionary *info in infos) {
NSError *error = info[UIImagePickerControllerError];
if (error && [TZCommonTools isICloudSyncError:error]) {
NSLog(@"iCloud资源同步失败: %@", error.localizedDescription);
}
}
};
六、常见问题解决方案
6.1 导航栏颜色异常
问题：在iOS15+上导航栏颜色不生效
解决：
if (@available(iOS 15.0, *)) {
UINavigationBarAppearance *appearance = [[UINavigationBarAppearance alloc] init];
appearance.backgroundColor = [UIColor whiteColor];
imagePicker.navigationBar.standardAppearance = appearance;
imagePicker.navigationBar.scrollEdgeAppearance = appearance;
}
6.2 照片选择数量限制
问题：需要动态修改最大可选数量
解决：
// 初始化后仍可修改
imagePicker.maxImagesCount = 6;
// 实现选择限制提示
- (BOOL)isAssetCanBeSelected:(PHAsset *)asset {
if (imagePicker.selectedAssets.count >= imagePicker.maxImagesCount) {
[imagePicker showAlertWithTitle:[NSString stringWithFormat:@"最多只能选择%ld张照片", (long)imagePicker.maxImagesCount]];
return NO;
}
return YES;
}
6.3 与第三方导航库冲突
问题：集成WRNavigationBar/GKNavigationBar后导航栏异常
解决：
// WRNavigationBar解决方案
[WRNavigationBar wr_setBlackList:@[@"TZImagePickerController",
@"TZPhotoPreviewController"]];
// GKNavigationBar解决方案（需升级至2.0.4+）
[GKNavigationBarViewController setIgnoreViewControllerNames:@[@"TZImagePickerController"]];
6.4 视频导出失败
问题：部分安卓拍摄的视频导出失败
解决：
// 关闭视频转向修正（默认NO）
imagePicker.needFixComposition = NO;
// 或升级至2.2.6+版本
七、版本迁移指南
3.x版本重大变更
- 最低支持版本：从iOS8提升至iOS10
- 移除的类：TZLocationManager（移至Location子spec）
- 新增特性：Dark Mode支持、隐私清单文件
- API变更：部分block属性重命名
从2.x迁移到3.x
// 旧代码
TZImagePickerController *picker = [[TZImagePickerController alloc]
initWithMaxImagesCount:9
delegate:self];
// 新代码（无变化）
TZImagePickerController *picker = [[TZImagePickerController alloc]
initWithMaxImagesCount:9
delegate:self];
// 旧代码（已废弃）
picker.takePictureImageName = @"camera";
// 新代码
picker.takePictureImage = [UIImage imageNamed:@"camera"];
八、总结与进阶
TZImagePickerController凭借其丰富的功能、灵活的定制能力和良好的兼容性，已成为iOS图片选择领域的事实标准。通过本文介绍的基础配置、高级功能和优化技巧，开发者可以快速实现专业级的图片选择功能。
进阶学习路径
- 源码阅读：重点关注TZImageManager的资源加载机制
- 扩展开发：基于TZImagePreviewController实现独立预览功能
- 性能调优：通过Instruments分析并优化内存占用
官方资源
- 完整Demo：仓库中包含所有功能演示
- 钉钉群：33192786（技术支持）
- 项目地址：https://gitcode.com/gh_mirrors/tz/TZImagePickerController
掌握这些知识后，你将能够应对从简单选择到复杂编辑的各种图片处理场景，为用户提供流畅、专业的媒体选择体验。
附录：常用API速查表
| 功能 | 核心类 | 关键方法/属性 |
|---|---|---|
| 基础选择 | TZImagePickerController | initWithMaxImagesCount:delegate: |
| 多选控制 | TZImagePickerController | maxImagesCount/minImagesCount |
| 原图选择 | TZImagePickerController | isSelectOriginalPhoto |
| 视频编辑 | TZImagePickerController | allowEditVideo/presetName |
| UI定制 | TZImagePickerController | 各种UI相关block属性 |
| 资源过滤 | TZImagePickerControllerDelegate | isAssetCanBeDisplayed: |
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
