接口调用说明
更新时间: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 工程):
Typescript
1import {
2 OnlineOcrClient, OcrCaptureOptions, CaptureMode
3} from '@baidu/ocr-core';
4import { OnlineOcrTypes, IdCardParams } from '@baidu/ocr-online';
5
6const captureOptions = new OcrCaptureOptions();
7captureOptions.setCaptureMode(CaptureMode.AUTO);
8
9OnlineOcrClient.getInstance().scanForJSON(
10 abilityContext,
11 OnlineOcrTypes.ID_CARD_FRONT,
12 captureOptions,
13 new IdCardParams(),
14 callback
15);
采集模式
| 模式 | 枚举值 | 行为 | 适用场景 |
|---|---|---|---|
| 自动采集 | 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 资源,清理内部状态 |
Typescript
1// 初始化
2const options = new OcrOptions();
3options.putParam(OnlineAuthParams.ACCESS_TOKEN, 'your_access_token');
4const result: OcrInitResult = await OnlineOcrClient.getInstance()
5 .initializeAsync(context, options);
6
7// 释放
8OnlineOcrClient.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 创建
Typescript
1import { OcrImage } from '@baidu/ocr-core';
2import image from '@ohos.multimedia.image';
3
4// 从 PixelMap 创建
5const ocrImage: OcrImage = OcrImage.fromPixelMap(pixelMap);
通用文字识别
调用示例:
Typescript
1import { OnlineOcrClient, OcrImage, OcrJSONCallback, OcrError } from '@baidu/ocr-core';
2import { OnlineOcrTypes, GeneralBasicParams } from '@baidu/ocr-online';
3
4const ocrImage = OcrImage.fromPixelMap(pixelMap);
5const params = new GeneralBasicParams();
6
7OnlineOcrClient.getInstance().recognizeForJSON(
8 context,
9 OnlineOcrTypes.GENERAL_BASIC,
10 ocrImage,
11 params,
12 {
13 onSuccess(responseJSON: string): void {
14 console.info('识别结果: ' + responseJSON);
15 },
16 onFailure(error: OcrError): void {
17 console.error(`识别失败: ${error.message}`);
18 },
19 onCanceled(): void {}
20 } as OcrJSONCallback
21);
返回参数说明:
| 字段 | 必选 | 类型 | 说明 |
|---|---|---|---|
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 | 识别结果字符串 |
身份证识别
调用示例:
Typescript
1import { OnlineOcrClient, OcrCaptureOptions, CaptureMode, OcrJSONCallback, OcrError } from '@baidu/ocr-core';
2import { OnlineOcrTypes, IdCardParams } from '@baidu/ocr-online';
3
4const captureOptions = new OcrCaptureOptions();
5captureOptions.setCaptureMode(CaptureMode.AUTO);
6
7const params = new IdCardParams();
8params.detectDirection = true;
9params.detectRisk = true;
10
11OnlineOcrClient.getInstance().scanForJSON(
12 abilityContext,
13 OnlineOcrTypes.ID_CARD_FRONT, // 或 ID_CARD_BACK
14 captureOptions,
15 params,
16 callback
17);
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 不可用时身份证退回手动拍照,不影响其他所有识别类型 |
银行卡识别
调用示例:
Typescript
1import { OnlineOcrClient, OcrCaptureOptions, CaptureMode, OcrJSONCallback } from '@baidu/ocr-core';
2import { OnlineOcrTypes, BankCardParams } from '@baidu/ocr-online';
3
4const captureOptions = new OcrCaptureOptions();
5captureOptions.setCaptureMode(CaptureMode.AUTO);
6
7OnlineOcrClient.getInstance().scanForJSON(
8 abilityContext,
9 OnlineOcrTypes.BANK_CARD,
10 captureOptions,
11 new BankCardParams(),
12 callback
13);
BankCardResult 字段:
| 字段 | 类型 | 说明 |
|---|---|---|
cardNumber |
string | 卡号 |
bankName |
string | 银行名称 |
cardType |
string | 卡片类型(借记卡/信用卡) |
validDate |
string | 有效期 |
卡证识别(护照、营业执照、社保卡等)
其余卡证类识别使用 CommonParams 传参、CommonResult 接收结果,示例:
Typescript
1import { OnlineOcrClient, OcrCaptureOptions, CaptureMode } from '@baidu/ocr-core';
2import { OnlineOcrTypes, CommonParams } from '@baidu/ocr-online';
3
4const captureOptions = new OcrCaptureOptions();
5captureOptions.setCaptureMode(CaptureMode.MANUAL);
6
7OnlineOcrClient.getInstance().scanForJSON(
8 abilityContext,
9 OnlineOcrTypes.BUSINESS_LICENSE,
10 captureOptions,
11 new CommonParams(),
12 callback
13);
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 |
返乡证反面 |
Typescript
1const params = new CommonParams();
2params.putParam('exitentrypermit_type', 'hk_mc_passport_front');
3
4OnlineOcrClient.getInstance().scanForJSON(
5 abilityContext,
6 OnlineOcrTypes.HK_MACAU_TW_CARD,
7 captureOptions,
8 params,
9 callback
10);
交通场景文字识别
行驶证、驾驶证、车牌、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
Typescript
1interface OcrJSONCallback {
2 onSuccess(responseJSON: string): void;
3 onFailure(error: OcrError): void;
4 onCanceled(): void;
5}
OcrResultCallback
Typescript
1interface OcrResultCallback {
2 onSuccess(result: object): void;
3 onFailure(error: OcrError): void;
4 onCanceled(): void;
5}
两种回调对比:
| 对比项 | OcrJSONCallback | OcrResultCallback |
|---|---|---|
| 返回类型 | 原始 JSON 字符串 | 结构化对象 |
| 灵活性 | 高,可自行解析任意字段 | 中,受结果类字段限制 |
| 使用便捷性 | 需自行 JSON.parse |
直接访问属性 |
| 适用场景 | 需要完整服务端响应、自行处理 | 快速获取常用字段 |
评价此篇文章
