demo/TencentCloudDemo/TencentCloudDemo.xcodeprojdemo/OcrSwiftDemo/OcrSwiftDemo.xcodeprojOcrSDK 文件夹,展开 Localizable.strings 后可以看到多个语言目录:en.lproj/ - 英文zh-Hans.lproj/ - 简体中文zh-Hant.lproj/ - 繁体中文id.lproj/ - 印尼语
Localizable.strings 文件// 修改前"ocr_cancel"="Cancel";// 修改为"ocr_cancel"="Close";
TencentCloudDemo)
OcrSDK 文件夹下的 Localizable.strings 文件
OcrSDK 目录下会自动生成新的语言目录(如 ja.lproj/)Localizable.strings 文件(初始内容为英文)
OcrSDKInfo.plist 文件,请删除它,避免影响 App Store 审核。
.bundle 文件(如 OcrSDK.bundle)拖拽到项目中CustomConfigUI 进行配置:OcrOverseasCustomConfigUI *custom = [[OcrOverseasCustomConfigUI alloc] init];// 设置自定义多语言 bundle 路径custom.custLanguageBundlePath = [[NSBundle mainBundle] pathForResource:@"CustomOcrSDK" ofType:@"bundle"];// 指定使用的语言文件custom.custLanguageFile = @"zh-Hans.lproj";OcrCloudConfig *cloudConfig = [[OcrCloudConfig alloc] init];cloudConfig.customConfigUI = custom;
let custom = OcrOverseasCustomConfigUI()// 设置自定义多语言 bundle 路径custom.custLanguageBundlePath = Bundle.main.path(forResource: "CustomOcrSDK", ofType: "bundle")// 指定使用的语言文件custom.custLanguageFile = "en.lproj"let cloudConfig = OcrCloudConfig()cloudConfig.customConfigUI = custom
demo/TencentCloudDemo/TencentCloudDemo.xcodeprojdemo/OcrSwiftDemo/OcrSwiftDemo.xcodeproj

OcrOverseasCustomConfigUI *customUI = [[OcrOverseasCustomConfigUI alloc] init];// 设置自定义 UI bundle 路径customUI.custBundlePath = [[NSBundle mainBundle] pathForResource:@"CustOCR" ofType:@"bundle"];OcrCloudConfig *cloudConfig = [[OcrCloudConfig alloc] init];cloudConfig.customConfigUI = customUI;
let customUI = OcrOverseasCustomConfigUI()// 设置自定义 UI bundle 路径customUI.custBundlePath = Bundle.main.path(forResource: "CustOCR", ofType: "bundle")let cloudConfig = OcrCloudConfig()cloudConfig.customConfigUI = customUI;
OcrOverseasViewDelegate 是 SDK 与业务方进行 UI 交互的核心协议。所有方法均为 @optional,未实现时 SDK 使用默认行为。OcrOverseasCustomConfigUI *customUI = [[OcrOverseasCustomConfigUI alloc] init];customUI.delegate = self; // self 遵循 OcrOverseasViewDelegateOcrCloudConfig *cloudConfig = [[OcrCloudConfig alloc] init];cloudConfig.customConfigUI = customUI;
let customUI = OcrOverseasCustomConfigUI()customUI.delegate = self // self 遵循 OcrOverseasViewDelegatelet cloudConfig = OcrCloudConfig()cloudConfig.customConfigUI = customUI
authView 为当前识别页面的根 View。可在此时向 authView 上添加自定义业务组件(如品牌 Logo、提示横幅等)。- (void)onMainViewCreate:(UIView *)authView;
- (void)onMainViewCreate:(UIView *)authView {// 在识别页右上角叠加 LogoUIImageView *logo = [[UIImageView alloc] initWithImage:[UIImage imageNamed:@"brand_logo"]];logo.translatesAutoresizingMaskIntoConstraints = NO;[authView addSubview:logo];[NSLayoutConstraint activateConstraints:@[[logo.topAnchor constraintEqualToAnchor:authView.safeAreaLayoutGuide.topAnchor constant:12],[logo.trailingAnchor constraintEqualToAnchor:authView.trailingAnchor constant:-16],[logo.widthAnchor constraintEqualToConstant:80],[logo.heightAnchor constraintEqualToConstant:30],]];}
onMainViewCreate 中添加的业务组件或释放相关资源。- (void)onMainViewDestroy;
- (void)onMainViewDestroy {NSLog(@"OCR 页面已关闭");// 清理自定义组件引用,释放资源}
- (void)onEventParamMap:(NSDictionary *)paramMap;
Key 常量 | 类型 | 说明 |
TXYOcrSdkEventParamMapCenterMarkRect | NSString(CGRect 的字符串形式) | 当前取景框在屏幕中的位置和尺寸(CGRect),可用于对齐自定义组件 |
TXYOcrSdkEventTimeoutStatus | NSString | 倒计时状态: "start"(开始倒计时)、"stop"(倒计时暂停)、"end"(超时) |
TXYOcrSdkEventSwitchToManualMode | 任意非 nil 值 | 已切换至手动拍摄模式 |
- (void)onEventParamMap:(NSDictionary *)paramMap {// 获取取景框位置,用于对齐自定义提示组件NSString *rectStr = paramMap[TXYOcrSdkEventParamMapCenterMarkRect];if (rectStr) {CGRect markRect = CGRectFromString(rectStr);// 将自定义组件定位到取景框正下方self.hintLabel.frame = CGRectMake(markRect.origin.x,CGRectGetMaxY(markRect) + 12,markRect.size.width,30);}// 监听倒计时状态NSString *timeoutStatus = paramMap[TXYOcrSdkEventTimeoutStatus];if ([timeoutStatus isEqualToString:@"start"]) {NSLog(@"开始倒计时");} else if ([timeoutStatus isEqualToString:@"end"]) {NSLog(@"倒计时超时");}}
YES 时 SDK 不展示默认确认弹窗,由业务方自行实现。- (BOOL)onShowBestFrameConfirmDialog:(NSDictionary *)infoimageView:(UIImageView *)imageViewparentView:(UIView *)parentViewconfirmBlock:(void(^)(void))confirmBlockcancelBlock:(void(^)(void))cancelBlock;
OcrOverseasCustomConfigUI.showBestImgConfirmDialog = YES,此回调才会触发。参数 | 说明 |
info[OcrDialogInfoKeyTitle] | 弹窗标题文案(已按语言设置本地化) |
info[OcrDialogInfoKeyMessage] | 弹窗描述文案 |
imageView | 包含最佳帧图片的 UIImageView,可直接添加到自定义弹窗中展示 |
parentView | 当前识别页面的根 View,将自定义弹窗添加到此 View 上 |
confirmBlock | 用户确认后必须调用,SDK 将继续上传流程 |
cancelBlock | 用户取消后必须调用,SDK 将重新采集 |
- (BOOL)onShowBestFrameConfirmDialog:(NSDictionary *)infoimageView:(UIImageView *)imageViewparentView:(UIView *)parentViewconfirmBlock:(void(^)(void))confirmBlockcancelBlock:(void(^)(void))cancelBlock {// 构建自定义弹窗UIAlertController *alert = [UIAlertControlleralertControllerWithTitle:info[OcrDialogInfoKeyTitle]message:info[OcrDialogInfoKeyMessage]preferredStyle:UIAlertControllerStyleAlert];[alert addAction:[UIAlertAction actionWithTitle:@"Use This Photo"style:UIAlertActionStyleDefaulthandler:^(UIAlertAction *_) {if (confirmBlock) confirmBlock(); // 必须调用}]];[alert addAction:[UIAlertAction actionWithTitle:@"Retake"style:UIAlertActionStyleCancelhandler:^(UIAlertAction *_) {if (cancelBlock) cancelBlock(); // 必须调用}]];// 找到当前最顶层 ViewController 进行 presentUIViewController *topVC = [self topViewController];[topVC presentViewController:alert animated:YES completion:nil];return YES; // 返回 YES,SDK 不展示默认弹窗}
YES 时由业务方展示自定义弹窗。- (BOOL)onShowNextSideDialog:(NSDictionary *)infoparentView:(UIView *)parentViewconfirmBlock:(void(^)(void))confirmBlock;
参数 | 说明 |
info[OcrDialogInfoKeyTitle] | 弹窗标题 |
info[OcrDialogInfoKeyMessage] | 弹窗描述 |
parentView | 当前识别页面的根 View |
confirmBlock | 用户点击确认后必须调用,SDK 继续翻面识别流程 |
- (BOOL)onShowNextSideDialog:(NSDictionary *)infoparentView:(UIView *)parentViewconfirmBlock:(void(^)(void))confirmBlock {UIAlertController *alert = [UIAlertControlleralertControllerWithTitle:info[OcrDialogInfoKeyTitle]message:info[OcrDialogInfoKeyMessage]preferredStyle:UIAlertControllerStyleAlert];[alert addAction:[UIAlertAction actionWithTitle:@"OK"style:UIAlertActionStyleDefaulthandler:^(UIAlertAction *_) {if (confirmBlock) confirmBlock(); // 必须调用}]];[[self topViewController] presentViewController:alert animated:YES completion:nil];return YES;}
OCR_DETECT_AUTO_MANUAL)倒计时超时后,SDK 调用此方法询问用户是否切换为手动拍摄模式。返回 YES 时由业务方展示自定义弹窗。- (BOOL)onShowChangeModeDialog:(NSDictionary *)infoparentView:(UIView *)parentViewconfirmBlock:(void(^)(void))confirmBlockcancelBlock:(void(^)(void))cancelBlock;
参数 | 说明 |
confirmBlock | 用户点击"切换手动"后调用,SDK 进入手动拍摄模式 |
cancelBlock | 用户点击"继续等待"后调用,SDK 重启倒计时 |
- (BOOL)onShowChangeModeDialog:(NSDictionary *)infoparentView:(UIView *)parentViewconfirmBlock:(void(^)(void))confirmBlockcancelBlock:(void(^)(void))cancelBlock {UIAlertController *alert = [UIAlertControlleralertControllerWithTitle:info[OcrDialogInfoKeyTitle]message:info[OcrDialogInfoKeyMessage]preferredStyle:UIAlertControllerStyleAlert];[alert addAction:[UIAlertAction actionWithTitle:@"Switch to Manual"style:UIAlertActionStyleDefaulthandler:^(UIAlertAction *_) {if (confirmBlock) confirmBlock();}]];[alert addAction:[UIAlertAction actionWithTitle:@"Keep Waiting"style:UIAlertActionStyleCancelhandler:^(UIAlertAction *_) {if (cancelBlock) cancelBlock();}]];[[self topViewController] presentViewController:alert animated:YES completion:nil];return YES;}
YES 时由业务方展示自定义错误弹窗。- (BOOL)onShowCloudErrorDialog:(NSDictionary *)infoparentView:(UIView *)parentViewretryBlock:(void(^_Nullable)(void))retryBlockexitBlock:(void(^)(void))exitBlock;
参数 | 说明 |
info[OcrDialogInfoKeyTitle] | 错误弹窗标题 |
info[OcrDialogInfoKeyMessage] | 错误描述(已按错误码本地化) |
info[OcrDialogInfoKeyErrorCode] | 服务端错误码(NSNumber,如 @(400101)) |
retryBlock | 用户点击"重试"后调用。为 nil 时表示此次错误不可重试,弹窗中不应显示重试按钮 |
exitBlock | 用户点击"退出"后调用,SDK 将触发失败回调,必须调用其中一个 |
- (BOOL)onShowCloudErrorDialog:(NSDictionary *)infoparentView:(UIView *)parentViewretryBlock:(void(^_Nullable)(void))retryBlockexitBlock:(void(^)(void))exitBlock {NSString *title = info[OcrDialogInfoKeyTitle] ?: @"Recognition Failed";NSString *message = info[OcrDialogInfoKeyMessage] ?: @"Please try again.";UIAlertController *alert = [UIAlertControlleralertControllerWithTitle:titlemessage:messagepreferredStyle:UIAlertControllerStyleAlert];// 仅在可重试时显示重试按钮if (retryBlock) {[alert addAction:[UIAlertAction actionWithTitle:@"Retry"style:UIAlertActionStyleDefaulthandler:^(UIAlertAction *_) {retryBlock();}]];}[alert addAction:[UIAlertAction actionWithTitle:@"Exit"style:UIAlertActionStyleCancelhandler:^(UIAlertAction *_) {exitBlock(); // 必须调用}]];[[self topViewController] presentViewController:alert animated:YES completion:nil];return YES;}
YES 时由业务方展示自定义权限引导弹窗。- (BOOL)onShowCameraPermissionDialog:(NSDictionary *)infoparentView:(UIView *)parentViewsettingsBlock:(void(^)(void))settingsBlockcancelBlock:(void(^)(void))cancelBlock;
参数 | 说明 |
settingsBlock | 用户点击"前往设置"后调用,SDK 将自动跳转至系统设置页 |
cancelBlock | 用户点击"取消/不授权"后调用,SDK 触发失败回调( TXY_SDK_CAMERA_PERMISSION_ERROR_CODE) |
- (BOOL)onShowCameraPermissionDialog:(NSDictionary *)infoparentView:(UIView *)parentViewsettingsBlock:(void(^)(void))settingsBlockcancelBlock:(void(^)(void))cancelBlock {UIAlertController *alert = [UIAlertControlleralertControllerWithTitle:@"Camera Permission Required"message:@"Please allow camera access in Settings to continue."preferredStyle:UIAlertControllerStyleAlert];[alert addAction:[UIAlertAction actionWithTitle:@"Go to Settings"style:UIAlertActionStyleDefaulthandler:^(UIAlertAction *_) {settingsBlock(); // SDK 自动跳转设置}]];[alert addAction:[UIAlertAction actionWithTitle:@"Cancel"style:UIAlertActionStyleCancelhandler:^(UIAlertAction *_) {cancelBlock();}]];[[self topViewController] presentViewController:alert animated:YES completion:nil];return YES;}
onShowLoading,请求结束后调用 onHideLoading。返回 YES 时 SDK 不展示内置 Loading,由业务方完全控制 Loading UI。- (BOOL)onShowLoading:(NSDictionary *)info parentView:(UIView *)parentView;- (BOOL)onHideLoading:(UIView *)parentView;
Key 常量 | 值 | 说明 |
OcrDialogInfoKeyLoadingType | OcrLoadingTypeOcrProcessing("loadingTypeOcrProcessing") | OCR 识别请求处理中 |
OcrDialogInfoKeyLoadingType | OcrLoadingTypeImagePicking("loadingTypeImagePicking") | 打开相册选图中 |
onShowLoading 和 onHideLoading 必须配对实现。若 onShowLoading 返回 YES 但 onHideLoading 返回 NO,SDK 内部 HUD 隐藏逻辑将不会执行,可能导致 Loading 残留- (BOOL)onShowLoading:(NSDictionary *)info parentView:(UIView *)parentView {// 移除旧 Loading(防止重复添加)[[parentView viewWithTag:9527] removeFromSuperview];UIView *container = [[UIView alloc] initWithFrame:parentView.bounds];container.tag = 9527;container.backgroundColor = [UIColor colorWithWhite:0 alpha:0.4];container.autoresizingMask = UIViewAutoresizingFlexibleWidth | UIViewAutoresizingFlexibleHeight;UIActivityIndicatorView *indicator;if (@available(iOS 13.0, *)) {indicator = [[UIActivityIndicatorView alloc] initWithActivityIndicatorStyle:UIActivityIndicatorViewStyleLarge];} else {indicator = [[UIActivityIndicatorView alloc] initWithActivityIndicatorStyle:UIActivityIndicatorViewStyleWhiteLarge];}indicator.center = container.center;indicator.autoresizingMask = UIViewAutoresizingFlexibleTopMargin | UIViewAutoresizingFlexibleBottomMargin| UIViewAutoresizingFlexibleLeftMargin | UIViewAutoresizingFlexibleRightMargin;[container addSubview:indicator];[indicator startAnimating];[parentView addSubview:container];return YES;}- (BOOL)onHideLoading:(UIView *)parentView {UIView *loading = [parentView viewWithTag:9527];[loading removeFromSuperview];return loading != nil; // 有 Loading 才返回 YES}
confirmBlock、cancelBlock、exitBlock、settingsBlock 等 Block 在用户交互完成后必须调用其中一个,否则 SDK 流程将无法继续,识别页面将永久卡住。YES:业务方接管该 UI,SDK 不展示默认实现。NO(或不实现该方法):SDK 使用内置默认 UI。parentView 是 SDK 识别页面的 View,在 onMainViewDestroy 后即被回收,请勿在回调外部长期持有。文档反馈