# CardRecognition（卡证识别控件）

卡证识别控件提供身份证、行驶证、驾驶证、护照、银行卡、港澳居民来往内地通行证、台湾居民来往大陆通行证的结构化识别服务，并支持自动分类功能，系统可自动判断所属卡证类型并返回结构化信息和卡证图片信息。

起始版本： 5.0.0(12)  
![](https://media:301785151961208850)  
使用该控件会创建弹窗，并以全模态形式展示。因此，该控件被拉起或退出时均会触发接入页面的生命周期变化，拉起时会触发页面的onPageHide，退出时则触发页面的onPageShow。  

#### 导入模块

```
import { CardRecognition, CardRecognitionResult, CardType, CardSide,
CardRecognitionConfig, ShootingMode, CardContentConfig, BankCardConfig, IdCardConfig } from '@kit.VisionKit';
```

#### CardRecognition

卡证识别控件，集成此控件可以实现卡证识别。

装饰器类型： @Component

系统能力： SystemCapability.AI.Component.CardRecognition

模型约束： 此接口仅可在Stage模型下使用。

起始版本： 5.0.0(12)

参数：  

|名称|类型|必填|装饰器类型|说明|
|:---------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------|:-|:----|:----------------------------------------------------------------------------------------------------------------------|
|supportType|[CardType](#cardtype)|是|-|表示需要识别的卡证类型。当前仅支持中国境内（香港特别行政区、澳门特别行政区、中国台湾除外）相关卡证的识别。 元服务API： 从版本5.0.0(12)开始，该接口支持在元服务中使用。|
|cardSide|[CardSide](#cardside)|否|-|表示需要识别的卡证页面。默认值：DEFAULT。 元服务API： 从版本5.0.0(12)开始，该接口支持在元服务中使用。|
|callback^(deprecated)^|[Callback](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-base#callback)\<[CallbackParam](#callbackparamdeprecated)\>|是|-|卡证识别结果的返回。callback和onResult参数同时配置时只有callback生效。 元服务API： 从版本5.0.0(12)开始，该接口支持在元服务中使用。 说明： 从5.1.1(19)开始废弃。建议使用onResult替代。|
|onResult|[Callback](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-base#callback)\<[CardRecognitionResult](#cardrecognitionresult)\>|是|-|卡证识别结果的返回。callback和onResult参数同时配置时只有callback生效。 元服务API： 从版本5.1.1(19)开始，该接口支持在元服务中使用。 起始版本： 5.1.1(19)|
|cardRecognitionConfig|[CardRecognitionConfig](#cardrecognitionconfig)|否|-|卡证识别配置项。 元服务API： 从版本5.0.0(12)开始，该接口支持在元服务中使用。|

#### build

build(): void

用于创建[CardRecognition](#cardrecognition)对象的构造函数，开发者无需调用此方法。

元服务API： 从版本5.0.0(12)开始，该接口支持在元服务中使用。

系统能力： SystemCapability.AI.Component.CardRecognition

模型约束： 此接口仅可在Stage模型下使用。

起始版本： 5.0.0(12)  

#### CardType

支持识别的卡证类型的枚举值。

系统能力： SystemCapability.AI.Component.CardRecognition

模型约束： 此接口仅可在Stage模型下使用。

起始版本： 5.0.0(12)  

|名称|值|说明|
|:--------------------------------|:-|:----------------------------------------------------------------|
|CARD_AUTO|0|自动识别卡证类型，不预设类型。 元服务API： 从版本5.0.0(12)开始，该接口支持在元服务中使用。|
|CARD_ID|1|身份证。 元服务API： 从版本5.0.0(12)开始，该接口支持在元服务中使用。|
|CARD_BANK|2|银行卡。 元服务API： 从版本5.0.0(12)开始，该接口支持在元服务中使用。|
|CARD_PASSPORT|3|护照。 元服务API： 从版本5.0.0(12)开始，该接口支持在元服务中使用。|
|CARD_DRIVER_LICENSE|4|驾驶证。 元服务API： 从版本5.0.0(12)开始，该接口支持在元服务中使用。|
|CARD_VEHICLE_LICENSE|5|行驶证。 元服务API： 从版本5.0.0(12)开始，该接口支持在元服务中使用。|
|CARD_MAINLAND_TRAVEL_PERMIT_HK_MO|6|港澳居民来往内地通行证。 元服务API： 从版本6.1.1(24)开始，该接口支持在元服务中使用。 起始版本： 6.1.1(24)|
|CARD_MAINLAND_TRAVEL_PERMIT_TW|7|台湾居民来往大陆通行证。 元服务API： 从版本6.1.1(24)开始，该接口支持在元服务中使用。 起始版本： 6.1.1(24)|

#### CardSide

需要识别的卡证页面的枚举值。

元服务API： 从版本5.0.0(12)开始，该接口支持在元服务中使用。

系统能力： SystemCapability.AI.Component.CardRecognition

模型约束： 此接口仅可在Stage模型下使用。

起始版本： 5.0.0(12)  

|名称|值|说明|
|:------|:-|:----------------------|
|FRONT|0|身份证人像面或其他卡证正面。|
|BACK|1|身份证国徽面或其他卡证反面。|
|DEFAULT|2|卡证默认面。如身份证为人像面，其他卡证为正面。|

#### CallbackParam^(deprecated)^

卡证识别结果返回的参数。

元服务API： 从版本5.0.0(12)开始，该接口支持在元服务中使用。

系统能力： SystemCapability.AI.Component.CardRecognition

模型约束： 此接口仅可在Stage模型下使用。

起始版本： 5.0.0(12)  
![](https://media:301785151961232851)  
从5.1.1(19)开始废弃。建议使用[CardRecognitionResult](#cardrecognitionresult)替代。  

|名称|类型|只读|可选|说明|
|:-------|:-----------------------------------------|:-|:-|:---------------------------------------------------------------------------------------|
|code|number|否|否|返回的结果码（200：识别成功，-1：识别失败）。|
|cardType|[CardType](#cardtype)|否|是|卡证类型。默认值：CARD_AUTO。|
|cardInfo|Record\<string, Record\<string, string\>\>|否|是|卡证信息。默认值：undefined。 对于双面卡证，包含信息为"front"和"back"。 对于单面卡证，包含信息为"main"。更多信息参考 [卡证信息](#卡证信息)。|

#### CardRecognitionResult

卡证识别结果返回的参数。

元服务API： 从版本5.1.1(19)开始，该接口支持在元服务中使用。

系统能力： SystemCapability.AI.Component.CardRecognition

模型约束： 此接口仅可在Stage模型下使用。

起始版本： 5.1.1(19)  

|名称|类型|只读|可选|说明|
|:-------|:-----------------------------------------|:-|:-|:----------------------------------------------------------------------------------------|
|code|number|否|否|返回的结果码： 200：识别成功。 1008701001：未识别。 1008701002：识别失败。 1008701003：部分识别失败。 1008701004：未完成识别。|
|cardType|[CardType](#cardtype)|否|是|卡证类型。默认值：CARD_AUTO。|
|cardInfo|Record\<string, Record\<string, string\>\>|否|是|卡证信息。默认值：undefined。 对于双面卡证，包含信息为"front"和"back"。 对于单面卡证，包含信息为"main"。 更多信息参考 [卡证信息](#卡证信息)。|

#### CardRecognitionConfig

卡证识别配置项。

系统能力： SystemCapability.AI.Component.CardRecognition

模型约束： 此接口仅可在Stage模型下使用。

起始版本： 5.0.0(12)  

|名称|类型|只读|可选|说明|
|:------------------------|:--------------------------------------|:-|:-|:-------------------------------------------------------------------------------------------------------------------------------------------------|
|defaultShootingMode|[ShootingMode](#shootingmode)|否|是|拍摄模式，默认值：ShootingMode.MANUAL。 元服务API： 从版本5.0.0(12)开始，该接口支持在元服务中使用。|
|isPhotoSelectionSupported|boolean|否|是|是否支持从图库选图。 - true为显示图库按钮并支持从图库选图。 - false为不显示图库按钮且不支持从图库选图。 默认值：true。 元服务API： 从版本5.0.0(12)开始，该接口支持在元服务中使用。|
|setCardMargins|number|否|是|设置经裁剪的卡证图片预留边距。范围\[10,10000\]。 若设定值大于原图某边边距，此边边距取原图，不做裁剪。 若设定值小于最小值10，则使用默认值10。 默认值：10。单位：px。 元服务API： 从版本5.0.3(15)开始，该接口支持在元服务中使用。 起始版本： 5.0.3(15)|
|cardContentConfig|[CardContentConfig](#cardcontentconfig)|否|是|卡证内容配置。 元服务API： 从版本5.0.0(12)开始，该接口支持在元服务中使用。|

#### ShootingMode

拍摄模式的枚举值。

元服务API： 从版本5.0.0(12)开始，该接口支持在元服务中使用。

系统能力： SystemCapability.AI.Component.CardRecognition

模型约束： 此接口仅可在Stage模型下使用。

起始版本： 5.0.0(12)  

|名称|值|说明|
|:-----|:-|:----|
|AUTO|0|自动拍摄。|
|MANUAL|1|手动拍摄。|

#### CardContentConfig

卡证内容配置项，可设置各类型卡证的具体配置。

系统能力： SystemCapability.AI.Component.CardRecognition

模型约束： 此接口仅可在Stage模型下使用。

起始版本： 5.0.0(12)  

|名称|类型|只读|可选|说明|
|:-------|:--------------------------------|:-|:-|:---------------------------------------------------------------|
|bankCard|[BankCardConfig](#bankcardconfig)|否|是|识别银行卡的具体配置。 元服务API： 从版本5.0.0(12)开始，该接口支持在元服务中使用。|
|idCard|[IdCardConfig](#idcardconfig)|否|是|识别身份证的具体配置。 元服务API： 从版本5.0.2(14)开始，该接口支持在元服务中使用。 起始版本：5.0.2(14)。|

#### BankCardConfig

银行卡识别的具体配置。

元服务API： 从版本5.0.0(12)开始，该接口支持在元服务中使用。

系统能力： SystemCapability.AI.Component.CardRecognition

模型约束： 此接口仅可在Stage模型下使用。

起始版本： 5.0.0(12)  

|名称|类型|只读|可选|说明|
|:----------------------|:------|:-|:-|:------------------------------------------------------------|
|isBankNumberDialogShown|boolean|否|是|识别到银行卡后是否弹出银行卡号确认弹框，true为识别后弹出确认弹框，false为识别后不弹出确认弹框，默认值：true。|

#### IdCardConfig

身份证识别的具体配置。

系统能力： SystemCapability.AI.Component.CardRecognition

模型约束： 此接口仅可在Stage模型下使用。

起始版本： 5.0.2(14)  

|名称|类型|只读|可选|说明|
|:-----------------------|:------|:-|:-|:-------------------------------------------------------------------------|
|isPhotoNeeded|boolean|否|是|识别到身份证人像面后是否需要返回身份证的人像图片。 true：需要返回身份证人像照片。 false：不需要返回身份证人像照片。 默认值：false。|
|isQualityDetectionNeeded|boolean|否|是|是否开启质量检测。 true：开启质量检测。 false：不开启质量检测。 默认值：false。|

#### 卡证信息

具体证件相关信息，包含身份证人像面和国徽面、银行卡、护照、驾驶证正反面、行驶证正反面、港澳居民来往内地通行证正反面、台湾居民来往大陆通行证正反面。

身份证人像面

起始版本： 5.0.0(12)  

|参数名|类型|说明|
|:----------------------|:-----|:-------------------------------------------------------------------------------------------------------------------|
|name|string|姓名。|
|sex|string|性别。|
|nationality|string|民族。|
|birth|string|出生日期。|
|address|string|住址。|
|idNumber|string|公民身份号码。|
|cardImageUri|string|身份证人像面图片uri（不含背景）。|
|originalImageUri|string|身份证人像面图片uri（含背景）。|
|photoUri|string|身份证人像面内的人像图片uri。仅在isPhotoNeeded为true时返回。 起始版本：5.0.2(14)。|
|photoLocation|string|人像图片在cardImageUri字段所代表的身份证（人像面）图片内的坐标。按top、left作为左上角顶点，width、height人像图片的宽高。 仅在isPhotoNeeded为true时返回。 起始版本：5.0.2(14)。|
|completenessProbability|string|完整的概率。取值范围：(0,1)。值越大，完整的概率越大。 起始版本：5.0.2(14)。|
|reflectionProbability|string|反光的概率。取值范围：(0,1)。值越大，反光的概率越大。 起始版本：5.0.2(14)。|
|clarityProbability|string|清晰的概率。取值范围：(0,1)。值越大，清晰的概率越大。 起始版本：5.0.2(14)。|
|occlusionProbability|string|遮挡的概率。取值范围：(0,1)。值越大，遮挡的概率越大。 起始版本：5.0.2(14)。|

身份证国徽面

起始版本： 5.0.0(12)  

|参数名|类型|说明|
|:----------------------|:-----|:--------------------------------------------|
|authority|string|签发机关。|
|validPeriod|string|有效期限。|
|cardImageUri|string|身份证国徽面图片uri（不含背景）。|
|originalImageUri|string|身份证国徽面图片uri（含背景）。|
|completenessProbability|string|完整的概率。取值范围：(0,1)。值越大，完整的概率越大。 起始版本：5.0.2(14)。|
|reflectionProbability|string|反光的概率。取值范围：(0,1)。值越大，反光的概率越大。 起始版本：5.0.2(14)。|
|clarityProbability|string|清晰的概率。取值范围：(0,1)。值越大，清晰的概率越大。 起始版本：5.0.2(14)。|
|occlusionProbability|string|遮挡的概率。取值范围：(0,1)。值越大，遮挡的概率越大。 起始版本：5.0.2(14)。|

银行卡

起始版本： 5.0.0(12)  

|参数名|类型|说明|
|:---------------|:-----|:--------------------------------------------------------------------------------------------------------------|
|bankNum|string|银行卡号。|
|validPeriod|string|有效期限。|
|cardImageUri|string|银行卡图片uri（不含背景）。|
|originalImageUri|string|银行卡图片uri（含背景）。|
|cardNumImageUri|string|银行卡号图片uri。 起始版本：6.1.1(24)。|
|isCropped|string|是否成功裁剪卡证图片。 取值范围如下。 "1"：成功裁剪，此时返回的cardImageUri为不含背景的卡证图片。 "0"：未成功裁剪，此时返回的cardImageUri为含背景的卡证图片。 起始版本：6.1.1(24)。|
|luhnCheckResult|string|银行卡号是否符合卢恩算法的校验结果。 取值范围如下。 "-1"：未进行校验。 "0"：不符合卢恩算法。 "1"：符合卢恩算法。 起始版本：6.1.1(24)。|

护照

起始版本： 5.0.0(12)  

|参数名|类型|说明|
|:---------------|:-----|:-------------|
|cardNum|string|护照号码。|
|name|string|姓名。|
|sex|string|性别。|
|nationality|string|国籍。|
|birth|string|出生日期。|
|address|string|出生地点。|
|issueDate|string|签发日期。|
|issuePlace|string|签发地点。|
|expiryDate|string|有效期至。|
|authority|string|签发机关。|
|pochn|string|因私护照。|
|cardImageUri|string|护照图片uri（不含背景）。|
|originalImageUri|string|护照图片uri（含背景）。|

驾驶证正面

起始版本： 5.0.0(12)  

|参数名|类型|说明|
|:---------------|:-----|:----------------|
|cardNum|string|证号。|
|name|string|姓名。|
|sex|string|性别。|
|nationality|string|国籍。|
|birth|string|出生日期。|
|address|string|住址。|
|dateOfFirstIssue|string|初次领证日期。|
|carClass|string|准驾车型。|
|validPeriodStart|string|有效期限-起始。|
|validPeriodEnd|string|有效期限-终止。|
|cardImageUri|string|驾驶证正面图片uri（不含背景）。|
|originalImageUri|string|驾驶证正面图片uri（含背景）。|

驾驶证反面

起始版本： 5.0.0(12)  

|参数名|类型|说明|
|:---------------|:-----|:----------------|
|cardNum|string|证号。|
|name|string|姓名。|
|archivesNum|string|档案编号。|
|record|string|记录。|
|cardImageUri|string|驾驶证反面图片uri（不含背景）。|
|originalImageUri|string|驾驶证反面图片uri（含背景）。|

行驶证正面

起始版本： 5.0.0(12)  

|参数名|类型|说明|
|:-----------------|:-----|:----------------|
|licensePlateNumber|string|号牌号码。|
|vehicleType|string|车辆类型。|
|owner|string|所有人。|
|address|string|住址。|
|useCharacter|string|使用性质。|
|model|string|品牌型号。|
|vin|string|车辆识别代码。|
|engineNum|string|发动机号码。|
|registerDate|string|注册日期。|
|issueDate|string|发证日期。|
|cardImageUri|string|行驶证正面图片uri（不含背景）。|
|originalImageUri|string|行驶证正面图片uri（含背景）。|

行驶证反面

起始版本： 5.0.0(12)  

|参数名|类型|说明|
|:---------------|:-----|:----------------|
|cardNum|string|号牌号码。|
|size|string|外廓尺寸。|
|remark|string|备注。|
|record|string|检验记录。|
|cardImageUri|string|行驶证反面图片uri（不含背景）。|
|originalImageUri|string|行驶证反面图片uri（含背景）。|

港澳居民来往内地通行证正面

起始版本： 6.1.1(24)  

|参数名|类型|说明|
|:----------|:-----|:----|
|name|string|姓名。|
|englishName|string|英文名。|
|birth|string|出生日期。|
|sex|string|性别。|
|validPeriod|string|有效期限。|
|authority|string|签发机关。|
|idNumber|string|证件号码。|
|numbers|string|换证次数。|

港澳居民来往内地通行证反面

起始版本： 6.1.1(24)  

|参数名|类型|说明|
|:-------|:-----|:-----|
|name|string|身份证姓名。|
|idNumber|string|身份证号码。|

台湾居民来往大陆通行证正面

起始版本： 6.1.1(24)  

|参数名|类型|说明|
|:----------|:-----|:----|
|name|string|姓名。|
|englishName|string|英文名。|
|birth|string|出生日期。|
|sex|string|性别。|
|validPeriod|string|有效期限。|
|authority|string|签发机关。|
|address|string|签发地点。|
|idNumber|string|证件号码。|
|numbers|string|换证次数。|

台湾居民来往大陆通行证反面

起始版本： 6.1.1(24)  

|参数名|类型|说明|
|:-------|:-----|:-----|
|name|string|身份证姓名。|
|idNumber|string|身份证号码。|