TZImagePickerController使用指南：从新手到专家

引言：告别原生相册选择器的痛点

你是否还在为UIImagePickerController的功能单一而烦恼？是否需要一个支持多选、原图、视频且兼容iOS10+的图片选择解决方案？本文将系统讲解TZImagePickerController的安装配置、核心功能、高级定制及性能优化，帮助开发者在15分钟内掌握这个功能全面的图片选择框架。

读完本文你将获得：

• 3种快速集成方式（CocoaPods/Carthage/手动）
• 多选/原图/视频选择的完整实现
• 10+自定义UI样式的实用技巧
• 性能优化与常见问题解决方案
• 从基础使用到源码级定制的全流程指南

一、框架概述与核心优势

TZImagePickerController是一个功能增强版的图片选择框架，作为UIImagePickerController的替代品，它提供了以下核心特性：

pie
    title 功能模块占比
    "多选功能" : 30
    "预览机制" : 25
    "视频支持" : 20
    "UI定制" : 15
    "性能优化" : 10

核心优势对比

功能特性	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 手动安装

1. 克隆仓库：

git clone https://gitcode.com/gh_mirrors/tz/TZImagePickerController.git

2. 将TZImagePickerController文件夹拖拽至项目
3. 导入头文件：

#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图片选择领域的事实标准。通过本文介绍的基础配置、高级功能和优化技巧，开发者可以快速实现专业级的图片选择功能。

进阶学习路径

1. 源码阅读：重点关注TZImageManager的资源加载机制
2. 扩展开发：基于TZImagePreviewController实现独立预览功能
3. 性能调优：通过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: