接口调用说明

更新时间：2026-08-14

接口调用说明

基本信息

SDK 版本	包名	MD5	适用范围	开发者
V1.0.0	platform.ocr.demo	MD5 (aip-ocr-harmonyos-sdk-V1.0.0.zip) = 2506920d8553e7aad761f60adab7b08d	HarmonyOS 5.0（API 12）及以上，phone / tablet	百度网讯科技有限公司

OCR-UI 模块

OCR SDK 内置一套默认采集 UI，包含相机预览、遮罩、提示文字、裁剪页和确认页。使用扫描接口 scanForJSON / scanForResult 即可拉起默认 UI，无需额外集成。

OCR-UI 模块调用示例

调用扫描接口示例（更详细请参考 demo 工程）：

import {
  OnlineOcrClient, OcrCaptureOptions, CaptureMode
} from '@baidu/ocr-core';
import { OnlineOcrTypes, IdCardParams } from '@baidu/ocr-online';

const captureOptions = new OcrCaptureOptions();
captureOptions.setCaptureMode(CaptureMode.AUTO);

OnlineOcrClient.getInstance().scanForJSON(
  abilityContext,
  OnlineOcrTypes.ID_CARD_FRONT,
  captureOptions,
  new IdCardParams(),
  callback
);

采集模式

模式	枚举值	行为	适用场景
自动采集	`CaptureMode.AUTO`	实时检测画面质量，满足条件自动拍摄	身份证、银行卡等固定形态证件
手动采集	`CaptureMode.MANUAL`	用户点击快门按钮手动拍摄	通用文字、票据等不规则文档

OcrCaptureConfig 详细配置

属性	类型	默认值	说明
`captureMode`	`CaptureMode`	`AUTO`	采集模式
`orientation`	`Orientation`	跟随系统	相机页方向（竖屏/横屏）
`showTitleBar`	`boolean`	`true`	是否显示顶部标题栏
`portraitProfile`	`OcrUiProfile`	默认配置	竖屏 UI 配置
`landscapeProfile`	`OcrUiProfile`	默认配置	横屏 UI 配置

OcrMaskConfig 遮罩配置

属性	类型	默认值	说明
`maskType`	`MaskType`	证件类型对应默认值	遮罩形状类型
`aspectRatio`	`number`	证件类型对应比例	遮罩区域宽高比
`widthPercent`	`number`	0.9	遮罩宽度占屏幕宽度百分比（0.0~1.0）
`verticalOffsetPercent`	`number`	0.0	遮罩垂直偏移百分比，正值下移
`guideIcon`	`Resource`	无	遮罩区域内的引导

生命周期 API

API	签名	说明
`initializeAsync`	`initializeAsync(context: common.Context, options: OcrOptions): Promise<OcrInitResult>`	初始化 SDK，注册 Adapter，完成鉴权预校验
`release`	`release(): void`	释放 SDK 资源，清理内部状态

// 初始化
const options = new OcrOptions();
options.putParam(OnlineAuthParams.ACCESS_TOKEN, 'your_access_token');
const result: OcrInitResult = await OnlineOcrClient.getInstance()
  .initializeAsync(context, options);

// 释放
OnlineOcrClient.getInstance().release();

扫描识别 API（带 UI）

扫描模式会拉起 SDK 内置相机采集页面，完成拍照、裁剪后自动送识别。

API	签名
`scanForJSON`	`scanForJSON(abilityContext: common.UIAbilityContext, ocrType: OcrType, captureOptions: OcrCaptureOptions, params: object, callback: OcrJSONCallback): void`
`scanForResult`	`scanForResult(abilityContext: common.UIAbilityContext, ocrType: OcrType, captureOptions: OcrCaptureOptions, params: object, callback: OcrResultCallback): void`

直接识别 API（无 UI）

直接识别模式不拉起 UI，业务方自行获取图片后传入 SDK 完成识别。

API	签名
`recognizeForJSON`	`recognizeForJSON(context: common.Context, ocrType: OcrType, image: OcrImage, params: object, callback: OcrJSONCallback): void`
`recognizeForResult`	`recognizeForResult(context: common.Context, ocrType: OcrType, image: OcrImage, params: object, callback: OcrResultCallback): void`

OcrImage 创建

import { OcrImage } from '@baidu/ocr-core';
import image from '@ohos.multimedia.image';

// 从 PixelMap 创建
const ocrImage: OcrImage = OcrImage.fromPixelMap(pixelMap);

通用文字识别

调用示例：

import { OnlineOcrClient, OcrImage, OcrJSONCallback, OcrError } from '@baidu/ocr-core';
import { OnlineOcrTypes, GeneralBasicParams } from '@baidu/ocr-online';

const ocrImage = OcrImage.fromPixelMap(pixelMap);
const params = new GeneralBasicParams();

OnlineOcrClient.getInstance().recognizeForJSON(
  context,
  OnlineOcrTypes.GENERAL_BASIC,
  ocrImage,
  params,
  {
    onSuccess(responseJSON: string): void {
      console.info('识别结果: ' + responseJSON);
    },
    onFailure(error: OcrError): void {
      console.error(`识别失败: ${error.message}`);
    },
    onCanceled(): void {}
  } as OcrJSONCallback
);

返回参数说明：

字段	必选	类型	说明
`direction`	否	int32	图像方向，当 `detect_direction=true` 时存在；-1 未定义、0 正向、1 逆时针 90 度、2 逆时针 180 度、3 逆时针 270 度
`log_id`	是	uint64	唯一的 log id，用于问题定位
`words_result_num`	是	uint32	识别结果数，表示 `words_result` 的元素个数
`words_result`	是	array	定位和识别结果数组
`+words`	否	string	识别结果字符串

身份证识别

调用示例：

import { OnlineOcrClient, OcrCaptureOptions, CaptureMode, OcrJSONCallback, OcrError } from '@baidu/ocr-core';
import { OnlineOcrTypes, IdCardParams } from '@baidu/ocr-online';

const captureOptions = new OcrCaptureOptions();
captureOptions.setCaptureMode(CaptureMode.AUTO);

const params = new IdCardParams();
params.detectDirection = true;
params.detectRisk = true;

OnlineOcrClient.getInstance().scanForJSON(
  abilityContext,
  OnlineOcrTypes.ID_CARD_FRONT, // 或 ID_CARD_BACK
  captureOptions,
  params,
  callback
);

IdCardParams 参数：

参数	类型	默认值	说明
`detectDirection`	boolean	false	是否检测图像朝向
`detectRisk`	boolean	false	是否检测风险（复印件、翻拍等）
`detectQuality`	boolean	false	是否返回图片质量信息
`detectPhoto`	boolean	false	是否检测头像照片
`detectCard`	boolean	false	是否检测身份证裁剪边框

IdCardResult 字段：

字段	类型	说明
`name`	string	姓名
`nation`	string	民族
`address`	string	地址
`idNumber`	string	身份证号
`birthday`	string	出生日期
`gender`	string	性别
`issueAuthority`	string	签发机关（反面）
`issueDate`	string	签发日期（反面）
`expiryDate`	string	有效期限（反面）

身份证质量检测能力 License（仅身份证需要）

除了包含远程API调用能力外，鸿蒙SDK中还集成了身份证识别的本地质量控制能力，提供给开发者本地检测身份证的功能。如果使用身份证正面/反面识别（ID_CARD_FRONT / ID_CARD_BACK），且需要自动采集质量检测功能，则还需配置 License 文件。License 用于身份证质量检测模型的离线鉴权，与在线 API 鉴权是两个独立体系，不参与上表的优先级判定。

项目	说明
是否必须	仅使用身份证识别且需要自动采集时必须。不使用身份证则完全不需要
配置位置	通过 `OcrOptions.initParams` 设置
文件位置	放置在 `src/main/resources/rawfile/` 下
绑定方式	绑定应用 bundleName 和签名指纹
失败影响	License 不可用时身份证退回手动拍照，不影响其他所有识别类型

银行卡识别

调用示例：

import { OnlineOcrClient, OcrCaptureOptions, CaptureMode, OcrJSONCallback } from '@baidu/ocr-core';
import { OnlineOcrTypes, BankCardParams } from '@baidu/ocr-online';

const captureOptions = new OcrCaptureOptions();
captureOptions.setCaptureMode(CaptureMode.AUTO);

OnlineOcrClient.getInstance().scanForJSON(
  abilityContext,
  OnlineOcrTypes.BANK_CARD,
  captureOptions,
  new BankCardParams(),
  callback
);

BankCardResult 字段：

字段	类型	说明
`cardNumber`	string	卡号
`bankName`	string	银行名称
`cardType`	string	卡片类型（借记卡/信用卡）
`validDate`	string	有效期

卡证识别（护照、营业执照、社保卡等）

其余卡证类识别使用 CommonParams 传参、CommonResult 接收结果，示例：

import { OnlineOcrClient, OcrCaptureOptions, CaptureMode } from '@baidu/ocr-core';
import { OnlineOcrTypes, CommonParams } from '@baidu/ocr-online';

const captureOptions = new OcrCaptureOptions();
captureOptions.setCaptureMode(CaptureMode.MANUAL);

OnlineOcrClient.getInstance().scanForJSON(
  abilityContext,
  OnlineOcrTypes.BUSINESS_LICENSE,
  captureOptions,
  new CommonParams(),
  callback
);

CommonParams 支持动态追加参数：

方法	说明
`putParam(key: string, value: string)`	设置字符串参数
`putBoolParam(key: string, value: boolean)`	设置布尔参数
`putNumberParam(key: string, value: number)`	设置数值参数

港澳台证件识别

港澳台证件识别需要传入 exitentrypermit_type 参数指定具体类型：

值	含义
`hk_mc_passport_front`	港澳通行证正面
`hk_mc_passport_back`	港澳通行证反面
`tw_passport_front`	台湾通行证正面
`tw_passport_back`	台湾通行证反面
`tw_return_passport_front`	台胞证正面
`tw_return_passport_back`	台胞证反面
`hk_mc_return_passport_front`	返乡证正面
`hk_mc_return_passport_back`	返乡证反面

const params = new CommonParams();
params.putParam('exitentrypermit_type', 'hk_mc_passport_front');

OnlineOcrClient.getInstance().scanForJSON(
  abilityContext,
  OnlineOcrTypes.HK_MACAU_TW_CARD,
  captureOptions,
  params,
  callback
);

交通场景文字识别

行驶证、驾驶证、车牌、VIN 码、机动车销售发票等交通类型均使用 CommonParams 和 CommonResult，仅 OcrType 常量不同：

能力	OcrType 常量	默认采集模式
行驶证	`OnlineOcrTypes.VEHICLE_LICENSE`	MANUAL
驾驶证	`OnlineOcrTypes.DRIVING_LICENSE`	MANUAL
车辆证照混贴	`OnlineOcrTypes.MIXED_MULTI_VEHICLE`	MANUAL
车牌	`OnlineOcrTypes.LICENSE_PLATE`	MANUAL
VIN 码	`OnlineOcrTypes.VIN_CODE`	MANUAL
机动车销售发票	`OnlineOcrTypes.VEHICLE_INVOICE`	MANUAL
二手车销售发票	`OnlineOcrTypes.USED_VEHICLE_INVOICE`	MANUAL
车辆合格证	`OnlineOcrTypes.VEHICLE_CERTIFICATE`	MANUAL
机动车登记证书	`OnlineOcrTypes.VEHICLE_REGISTRATION_CERTIFICATE`	MANUAL
磅单	`OnlineOcrTypes.WEIGHT_NOTE`	MANUAL
快递面单	`OnlineOcrTypes.WAYBILL`	MANUAL
道路运输证	`OnlineOcrTypes.ROAD_TRANSPORT_CERTIFICATE`	MANUAL

回调接口

OcrJSONCallback

interface OcrJSONCallback {
  onSuccess(responseJSON: string): void;
  onFailure(error: OcrError): void;
  onCanceled(): void;
}

OcrResultCallback

interface OcrResultCallback {
  onSuccess(result: object): void;
  onFailure(error: OcrError): void;
  onCanceled(): void;
}

两种回调对比：

对比项	OcrJSONCallback	OcrResultCallback
返回类型	原始 JSON 字符串	结构化对象
灵活性	高，可自行解析任意字段	中，受结果类字段限制
使用便捷性	需自行 `JSON.parse`	直接访问属性
适用场景	需要完整服务端响应、自行处理	快速获取常用字段

快速入门

FAQ