Harmony 端OCR SDK 主要涉及如下几个类:API 接口类 OcrSDKKit、参数配置类 OcrSDKConfig、结果回调类 OcrResultCallback。
OcrSDKKit
OcrSDKKit 为OCR SDK 的对外接口类,主要逻辑也都是调用此类完成。
API | 功能描述 |
init() | 初始化接口 |
release() | 资源释放接口 |
startOcrByConfig() | 启动OCR识别 |
setOcrEventListener() | 设置本次OCR识别的事件回调 |
stopOcr() | 停止OCR识别 |
getVersion() | 获得当前 SDK 的版本号 |
init()
public init(context: Context)
功能介绍:OCR SDK 的初始化接口。
传入参数:
参数类型 | 参数名称 | 参数含义 |
Context | context | App 的上下文信息 |
release()
public release()
功能介绍:OCR SDK 资源释放的接口。
startOcrByConfig()
public startOcrByConfig(config: OcrSDKConfig, cb: OcrResultCallback)
功能介绍:OCR SDK 启动接口。
传入参数:
参数类型 | 参数名称 | 参数含义 |
OcrSDKConfig | config | SDK启动配置项 |
OcrResultCallback | cb | 结果回调类 |
setOcrEventListener()
public setOcrEventListener(callback: OcrEventCallback)
功能介绍:设置本次 OCR 识别的事件回调
传入参数:
参数类型 | 参数名称 | 参数含义 |
OcrEventCallback | callback | 事件对应的回调信息 |
stopOcr()
public stopOcr()
功能介绍: 停止 OCR 识别。
getVersion()
public getVersion(): string
功能介绍:获取当前版本 OCR SDK 的版本号。
OcrSDKConfig
OcrSDKConfig 是在启动 OCR SDK 时的配置实体类,主要包含了以下属性。
类型 | 名称 | 含义 | 默认值 |
OcrMode | ocrMode | 卡片识别模式 | OCR_DETECT_AUTO_MANUAL |
number | auto2ManualTimeout | 自动捕获超时(毫秒单位,最少设置5秒,内部上限30秒) | 20000毫秒 |
OcrCardType | cardType | 卡片识别类型 | COMMON_OCR |
OcrUIConfig | ocrUIConfig | 自定义UI配置 | 默认值 |
string | secretID | 请求使用的密钥信息(如果使用固定密钥模式,可传入固定密钥) | 空 |
string | secretKey | 请求使用的密钥信息(如果使用固定密钥模式,可传入固定密钥) | 空 |
string | token | 请求使用的临时 token 信息 | 空 |
boolean | cropIdCard | 开启身份证照片裁剪(去掉证件外多余的边缘、自动矫正拍摄角度)开关 | false |
boolean | cropPortrait | 人像照片裁剪(自动抠取身份证头像区域) | false |
boolean | copyWarn | 开启复印件告警 | false |
boolean | borderCheckWarn | 开启边框和框内遮挡告警 | false |
boolean | reshootWarn | 开启翻拍告警 | false |
boolean | detectPsWarn | 开启 PS 检测告警 | false |
boolean | tempIdWarn | 开启临时身份证告警 | false |
boolean | invalidDateWarn | 开启身份证有效日期不合法告警 | false |
boolean | quality | 开启图片质量分数(评价图片的模糊程度) | false |
boolean | multiCardDetect | 是否开启正反面同框识别(仅支持二代身份证正反页同框识别或临时身份证正反页同框识别) | false |
boolean | reflectWarn | 是否开启反光检测 | false |
boolean | retImageType | 图像预处理,检测图片倾斜的角度,将原本倾斜的图片围绕中心点转正,最终输出一张正的名片抠图。 | false |
boolean | retBorderCutImage | 银行卡专用,是否返回预处理(精确剪裁对齐)后的银行卡图片数据 | false |
boolean | retCardNoImage | 银行卡专用,是否返回卡号的切图图片数据,默认false。 | false |
boolean | enableQualityValue | 银行卡专用,是否返回图片质量分数(图片质量分数是评价一个图片的模糊程度的标准) | false |
OcrCardType
OCR 支持的卡片识别类型
OcrCardType 类型 | 含义 |
IDCardOCR_FRONT | 身份证人像面识别模式 |
IDCardOCR_BACK | 身份证国徽面识别模式 |
BankCardOCR | 银行卡正面识别模式 |
BusinessCardOCR | 名片卡正面识别模式 |
LicensePlateOCR | 车辆的车牌识别模式 |
VinOCR | 车辆的 VIN 识别模式 |
VehicleLicenseOCR_FRONT | 行驶证主页识别模式 |
VehicleLicenseOCR_BACK | 行驶证副页识别模式 |
DriverLicenseOCR_FRONT | 驾驶证主页识别模式 |
DriverLicenseOCR_BACK | 驾驶证副页识别模式 |
IDCardOCR_HK03 | 香港身份证03版本识别模式 |
IDCardOCR_HK18 | 香港身份证18版本识别模式 |
Exit_Entry_HK_Macao_Card | 港澳台通行证识别模式 |
HMT_RESIDENT_PERMIT_OCR | 港澳台居住证 |
MLID_PASSPORT | 国际护照识别模式 |
OcrMode
OcrMode 是一个枚举类型,列举了卡片识别模式。
OcrModeType 类型 | 代表含义 |
OCR_DETECT_MANUAL | 手动拍摄模式 |
OCR_DETECT_AUTO_MANUAL | 自动识别模式(tips:20s后提示 是否切换到手动拍摄) |
OCR_DETECT_AUTO | 自动识别模式 |
OcrResultCallback
OCR结果的回调类
export interface OcrResultCallback { /** * 成功的回调 * * @param response,服务端返回的信息 * @param requestID, 服务端的requestID * @param imageBase64Str SDK最优图jpg的base64编码 */ onSuccess: (response: string, requestID: string, imageBase64Str: string) => void; /** * 失败的回调 * * @param errorCode 错误码 * @param errMsg 错误详细信息 */ onFail: (errorCode: number, errMsg: string) => void; }
OcrEventCallback
用来监听 OCR 过程中的事件的回调
export interface OcrEventCallback { /** * 额外的参数透传 * @param type 事件类型 * @param params */ onOcrEvent: (type: OcrEventType, param: string) => void; }
OcrEventType
对应的事件类型与含义:
事件枚举 | 事件含义 |
EVENT_DETECT_RECT_INFO | 检测框信息(检测框左上角的坐标以及检测框宽高,params形如:"{ x: 0, y: 0, w: 0, h: 0}") |
EVENT_TIME_OUT | 超时事件回调(倒计时启动、暂停、结束,params形如:start、pause、end) |
EVENT_AUTO_TO_MANUAL | 自动切手动时的事件回调(params无意义,可不关注) |
OcrUIConfig
OCR 检测页面自定义UI的参数配置
类型 | 名称 | 含义 | 默认值 |
boolean | showLightIcon | 是否显示闪光灯按钮 | true |
boolean | showAlbumIcon | 是否显示相册选图按钮 | true |
boolean | showFixTips | 是否显示'请避免识别内容折角...'提示 | true |
boolean | showRectCornerLine | 是否显示四个角的线条 | true |
boolean | showIDCardLogo | 是否显示人头和国徽的轮廓(大陆身份证) | true |
boolean | keepDetectView | 检测到最佳帧后,是否销毁检测页面(需配合自定义动画效果使用) | false |
number | lightIconSize | 闪光灯图标的宽度,高度自适应 | 50 |
number | takePictureIconSize | 拍照图标的宽度,高度自适应 | 80 |
number | albumIconSize | 相册图标的宽度,高度自适应 | 50 |
string | detectNormalColor | 常规反馈Tips的颜色 | #ffffff |
string | detectCorrectColor | 正常反馈Tips颜色 | #006eff |
string | detectErrorColor | 异常反馈Tips颜色 | #e94b2c |
number | rectCornerLineWeight | 检测框四角线条的粗细 | 3 |
number | rectCornerLineLen | 检测框四角线条的长度 | 30 |
string | maskViewColorStyle | 检测页面的蒙版颜色样式 | rgba(80, 80, 80, 0.8) |
number | rectMarginTop | 检测框距离顶部的距离 | 50 |
number | rectHorizontalMargin | 检测框距离屏幕的横向距离 | 5 |
number | tipsMarginTop | tips提示距离顶部的距离 | 20 |
number | fixTipsMarginTop | fix tips提示距离顶部的距离 | 350 |
string | switchModeDialogTitleColor | 超时dialog 标题的颜色 | #000000 |
string | switchModeDialogContentColor | 超时dialog 内容的颜色 | #000000 |
string | switchModeDialogCancelColor | 超时dialog 取消按钮的颜色 | #000000 |
string | switchModeDialogConfirmColor | 超时dialog 确认按钮的颜色 | #006eff |
number | switchModeDialogTitleFontSize | 超时dialog 标题的字体大小 | 16 |
number | switchModeDialogContentFontSize | 超时dialog 内容的字体大小 | 14 |
number | switchModeDialogCancelFontSize | 超时dialog 取消按钮的字体大小 | 16 |
number | switchModeDialogConfirmFontSize | 超时dialog 确认按钮的字体大小 | 16 |
boolean | switchModeDialogConfirmOnLeft | 超时dialog 确认按钮是否显示在左侧 | false |
(param: CommonUIModel) => void | commonCustomUI | 基础自定义UI(详情参见自定义UI说明文档) | (param: CommonUIModel): void => {} |
(param: AnimationUIModel) => void | animUI | 自定义动画UI(详情参见自定义UI说明文档) | (param: AnimationUIModel): void => {} |
自定义 UI
自定义 UI 显示
OCR SDK 支持自定义 UI,可通过 OcrUIConfig 配置。使用方式如下:
// 1. 自定义配置let uiConfig = new OcrUIConfig();// 识别页面是否显示闪光灯按钮uiConfig.showLightIcon = this.showLightIcon;// 识别页面是否显示相册按钮uiConfig.showAlbumIcon = this.showAlbumIcon;// 识别页面是否显示'请避免识别内容折角...'提示uiConfig.showFixTips = this.showFixTips;// 2. 将uiConfig设置到启动参数里let config: OcrSDKConfig = new OcrSDKConfigBuilder().setOcrUIConfig(uiConfig).build();// 3. 传入启动参数OcrSDKKit.getInstance().startOcrByConfig(config, ...);
新增 UI 组件
这里主要介绍如何在核身页面增加自定义的 UI 组件以及如何绑定事件。使用方式如下:
/*** 自定义UI* @param $$*/@BuilderMyCustomUI($$: CustomUIModel) {Column() {Button('自定义的Button').onClick(() => {// 自定义UI响应事件router.back();}).margin({bottom: '3%'}).backgroundColor(Color.Blue)}.backgroundColor(Color.Red).margin({bottom: '3%'})}// 1. 自定义配置 let uiConfig = new OcrUIConfig(); // 传入自定义布局 uiConfig.commonCustomUI = this.MyCustomUI; // 2. 将uiConfig设置到启动参数里 let config: OcrSDKConfig = new OcrSDKConfigBuilder() .setOcrUIConfig(uiConfig) .build(); // 3. 传入启动参数 OcrSDKKit.getInstance().startOcrByConfig(config, ...);
自定义提示
您若需要自定义 OCR 页面的提示语,可以按照下面的方式实现(OCR SDK 的交付件中会提供一个翻译文件 ocr_custom_string.json,该文件包含了所有可进行自定义的文字)实现:
1. 打开名为 <module_name> 的 module(集成 OCR SDK 的 module)
2. 将 ocr_custom_string.json 添加到对应的语言文件夹下(<module_name>/src/main/resources/zh_CN/element/)
3. 修改 ocr_custom_string.json 中需要自定义的文字内容
4. 打包以后,您修改的内容将会覆盖 SDK 原有的提示文本。