FAQ

Q：demo 工程为何提示 token 还未获取成功，无法使用识别功能？

A：识别需要 access_token 作为参数，token 需要通过网络获取，网络环境较差的情况下返回较慢。请确认设备可访问 aip.baidubce.com，并且 demo/src/main/resources/rawfile/local.properties 中 access_token 已填写为有效值。

Q：关于身份证识别的两种模式？

A：身份证识别的自动采集模式依赖本地质量检测模型和 License 文件。如果您不需要自动采集能力，可以在 OcrCaptureOptions 中将 captureMode 设置为 CaptureMode.MANUAL，并移除 rawfile 下的 License 文件和模型目录，此时 SDK 使用手动拍照模式。

Q：scanForJSON 和 recognizeForJSON 有什么区别？

A：

1// scanForJSON：拉起相机页，用户拍照后自动识别
2OnlineOcrClient.getInstance().scanForJSON(
3  abilityContext, ocrType, captureOptions, params, callback);
4
5// recognizeForJSON：直接传图识别
6const image = OcrImage.fromPixelMap(pixelMap);
7OnlineOcrClient.getInstance().recognizeForJSON(
8  context, ocrType, image, params, callback);

Q：AUTO 模式为什么退回了 MANUAL？

A：AUTO 模式需要该识别类型支持自动采集，且本地质量检测模型初始化成功。以下情况会自动退回手动拍照：

支持 AUTO 模式的类型：身份证正面/反面（id_card.front / id_card.back）。其他类型默认使用手动拍照。排查方法：查看 IdCardFrameSampler 标签日志，确认 FrameSampler 初始化结果。

Q：相机权限如何处理？

A：SDK 在启动采集页时会自动检测 ohos.permission.CAMERA 权限状态：

1. 已授权：直接打开相机。
2. 未申请：触发系统权限弹窗。
3. 用户拒绝：回调 onFailure，code 为 PERMISSION_DENIED，stage 为 CAPTURE。

业务方也可选择在调用 scanForJSON 前自行申请权限：

1import abilityAccessCtrl from '@ohos.abilityAccessCtrl';
2
3const atManager = abilityAccessCtrl.createAtManager();
4const result = await atManager.requestPermissionsFromUser(
5  context, ['ohos.permission.CAMERA']);
6
7if (result.authResults[0] === 0) {
8  // 已授权，可以调用 scanForJSON
9} else {
10  // 用户拒绝，引导用户到设置页开启
11}

module.json5 中 CAMERA 权限声明必须包含 reason 字段，否则系统不会弹出权限弹窗。

Q：出现 UNSUPPORTED_OCR_TYPE 错误怎么办？

A：该错误表示当前 SDK 未注册该识别类型。常见原因：

验证方法：初始化成功后调用 result.getSupportedTypes() 确认目标类型在列表中。

Q：code 和 errorCode 有什么区别？

A：OcrError 中有两个错误标识字段：

业务方先判断 code 确定错误大类；需要细分服务端错误时再读 errorCode 原值；stage 字段辅助定位错误发生在哪个阶段。

Q：如何获取服务端错误详情？

A：当服务端返回 error_code != 0 时，SDK 会将信息映射到 OcrError：

同时 code 字段设置为 SERVER_ERROR，stage 为 RECOGNIZE。使用 logId 联系百度技术支持排查。

Q：initializeAsync 和 initialize 有什么区别？

A：

推荐使用 initializeAsync：

1try {
2  const result = await OnlineOcrClient.getInstance().initializeAsync(context, options);
3  // 初始化成功
4} catch (error) {
5  // 初始化失败
6}

Q：如何判断某个 OcrType 是否支持？

A：初始化成功后通过 OcrInitResult 查询：

1const result = await OnlineOcrClient.getInstance().initializeAsync(context, options);
2const supportedTypes = result.getSupportedTypes();
3
4if (supportedTypes.has(OnlineOcrTypes.ID_CARD_FRONT)) {
5  // 支持身份证正面识别
6}

对不支持的类型调用 scanForJSON / recognizeForJSON，会收到 UNSUPPORTED_OCR_TYPE 错误。

Q：release() 后还能继续使用吗？

A：不能。release() 会释放所有资源（关闭相机、停止后台任务、断开网络连接）。释放后需重新调用 initializeAsync 才能再次使用。推荐生命周期模式：

1@Entry
2@Component
3struct MyPage {
4  async aboutToAppear(): Promise<void> {
5    await OnlineOcrClient.getInstance().initializeAsync(context, options);
6  }
7
8  aboutToDisappear(): void {
9    OnlineOcrClient.getInstance().release();
10  }
11}

release() 会立即取消正在进行的识别任务，未完成的回调会收到 onCanceled。