Harmony API 概览

最近更新时间:2024-07-17 15:56:11

我的收藏
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 $$
*/
@Builder
MyCustomUI($$: 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 原有的提示文本。