The card recognition control provides structured recognition services for ID cards, vehicle licenses, driver's licenses, passports, bank cards, Mainland Travel Permits for Hong Kong and Macao Residents, and Mainland Travel Permits for Taiwan Residents. The system can automatically determine the type of a certificate and return its structured information as well as image information.
Since: 5.0.0(12)
Using this control will create and display a modal pop-up window. Therefore, starting and exiting this control will both trigger a lifecycle change of the accessed page. Specifically, starting the control will trigger onPageHide of the page, while exiting the control will trigger onPageShow.
Modules to Import
import { CardRecognition, CardRecognitionResult, CardType, CardSide,
CardRecognitionConfig, ShootingMode, CardContentConfig, BankCardConfig, IdCardConfig } from '@kit.VisionKit'; CardRecognition
Card recognition control, which can be integrated to implement card recognition.
Decorator: @Component
System capability: SystemCapability.AI.Component.CardRecognition
Model restriction: This API can be used only in the stage model.
Since: 5.0.0(12)
Parameters:
| Name | Type | Mandatory | Decorator Type | Description |
|---|---|---|---|---|
| supportType | CardType | Yes | - | Supported card types. Currently, only cards issued in the Chinese mainland (excluding Hong Kong SAR, Macao SAR, and Taiwan (China)) can be recognized. Atomic service API: This API can be used in atomic services since version 5.0.0(12). |
| cardSide | CardSide | No | - | Side of a card to be recognized. The default value is DEFAULT. Atomic service API: This API can be used in atomic services since version 5.0.0(12). |
| callback(deprecated) | Callback<CallbackParam> | Yes | - | Used to return the card recognition result. If both callback and onResult are configured, only callback takes effect. Atomic service API: This API can be used in atomic services since version 5.0.0(12). NOTE This parameter has been deprecated since version 5.1.1(19). You are advised to use onResult instead. |
| onResult | Callback<CardRecognitionResult> | Yes | - | Used to return the card recognition result. If both callback and onResult are configured, only callback takes effect. Atomic service API: This API can be used in atomic services since version 5.1.1(19). Since: 5.1.1(19) |
| cardRecognitionConfig | CardRecognitionConfig | No | - | Card recognition configuration. Atomic service API: This API can be used in atomic services since version 5.0.0(12). |
[h2]build
build(): void
Constructs a CardRecognition object. You do not need to call this method.
Atomic service API: This API can be used in atomic services since version 5.0.0(12).
System capability: SystemCapability.AI.Component.CardRecognition
Model restriction: This API can be used only in the stage model.
Since: 5.0.0(12)
CardType
Enumeration of supported card types.
System capability: SystemCapability.AI.Component.CardRecognition
Model restriction: This API can be used only in the stage model.
Since: 5.0.0(12)
| Name | Value | Description |
|---|---|---|
| CARD_AUTO | 0 | Automatic card type recognition is used, and no card type is preset. Atomic service API: This API can be used in atomic services since version 5.0.0(12). |
| CARD_ID | 1 | ID card. Atomic service API: This API can be used in atomic services since version 5.0.0(12). |
| CARD_BANK | 2 | Bank card. Atomic service API: This API can be used in atomic services since version 5.0.0(12). |
| CARD_PASSPORT | 3 | Passport. Atomic service API: This API can be used in atomic services since version 5.0.0(12). |
| CARD_DRIVER_LICENSE | 4 | Driver's license. Atomic service API: This API can be used in atomic services since version 5.0.0(12). |
| CARD_VEHICLE_LICENSE | 5 | Vehicle license. Atomic service API: This API can be used in atomic services since version 5.0.0(12). |
| CARD_MAINLAND_TRAVEL_PERMIT_HK_MO | 6 | Mainland Travel Permit for Hong Kong and Macao Residents Atomic service API: This API can be used in atomic services since version 6.1.1(24). Since: 6.1.1(24) |
| CARD_MAINLAND_TRAVEL_PERMIT_TW | 7 | Mainland Travel Permit for Taiwan Residents Atomic service API: This API can be used in atomic services since version 6.1.1(24). Since: 6.1.1(24) |
CardSide
Enumeration of card sides to be recognized.
Atomic service API: This API can be used in atomic services since version 5.0.0(12).
System capability: SystemCapability.AI.Component.CardRecognition
Model restriction: This API can be used only in the stage model.
Since: 5.0.0(12)
| Name | Value | Description |
|---|---|---|
| FRONT | 0 | Portrait side of an ID card or front side of any other cards. |
| BACK | 1 | National emblem side of an ID card or back side of any other cards. |
| DEFAULT | 2 | Default side. For example, the value is the portrait side of an ID card or the front side of any other cards. |
CallbackParam(deprecated)
Card recognition result parameters.
Atomic service API: This API can be used in atomic services since version 5.0.0(12).
System capability: SystemCapability.AI.Component.CardRecognition
Model restriction: This API can be used only in the stage model.
Since: 5.0.0(12)
This parameter has been deprecated since version 5.1.1(19). You are advised to use CardRecognitionResult instead.
| Name | Type | Read-Only | Optional | Description |
|---|---|---|---|---|
| code | number | No | No | Result code (200: recognition success; -1: recognition failure). |
| cardType | CardType | No | Yes | Card type. The default value is CARD_AUTO. |
| cardInfo | Record<string, Record<string, string>> | No | Yes | Card information. Default value: undefined For a double-sided card, the information is front and back. For a single-sided card, the information is main. For details, see Card Information. |
CardRecognitionResult
Card recognition result parameters.
Atomic service API: This API can be used in atomic services since version 5.1.1(19).
System capability: SystemCapability.AI.Component.CardRecognition
Model restriction: This API can be used only in the stage model.
Since: 5.1.1(19)
| Name | Type | Read-Only | Optional | Description |
|---|---|---|---|---|
| code | number | No | No | Result code. 200: The recognition is successful. 1008701001: Unrecognized. 1008701002: The recognition failed. 1008701003: Partial recognition failed. 1008701004: Recognition not completed. |
| cardType | CardType | No | Yes | Card type. The default value is CARD_AUTO. |
| cardInfo | Record<string, Record<string, string>> | No | Yes | Card information. Default value: undefined For a double-sided card, the information is front and back. For a single-sided card, the information is main. For details, see Card Information. |
CardRecognitionConfig
Card recognition configuration.
System capability: SystemCapability.AI.Component.CardRecognition
Model restriction: This API can be used only in the stage model.
Since: 5.0.0(12)
| Name | Type | Read-Only | Optional | Description |
|---|---|---|---|---|
| defaultShootingMode | ShootingMode | No | Yes | Photo shooting mode. The default value is ShootingMode.MANUAL. Atomic service API: This API can be used in atomic services since version 5.0.0(12). |
| isPhotoSelectionSupported | boolean | No | Yes | Indicates whether images can be selected from the gallery. - true: yes (The gallery button is displayed and images can be selected from the gallery.) - false: no (The gallery button is not displayed and images cannot be selected from the gallery.) Default value: true. Atomic service API: This API can be used in atomic services since version 5.0.0(12). |
| setCardMargins | number | No | Yes | Margins around a cropped card image. Value range: [10, 10000] If the specified margins are greater than the margin of any side of the original image, that side will retain its original margin and not be cropped. If the specified value is less than the minimum value 10, the default value 10 will be used. The default value is 10. The unit is px. Atomic service API: This API can be used in atomic services since version 5.0.3(15). Since: 5.0.3(15) |
| cardContentConfig | CardContentConfig | No | Yes | Card content configuration. Atomic service API: This API can be used in atomic services since version 5.0.0(12). |
ShootingMode
Enumeration of shooting modes.
Atomic service API: This API can be used in atomic services since version 5.0.0(12).
System capability: SystemCapability.AI.Component.CardRecognition
Model restriction: This API can be used only in the stage model.
Since: 5.0.0(12)
| Name | Value | Description |
|---|---|---|
| AUTO | 0 | Automatic shooting. |
| MANUAL | 1 | Manual shooting. |
CardContentConfig
Card content configuration. You can set specific parameters for each type of card.
System capability: SystemCapability.AI.Component.CardRecognition
Model restriction: This API can be used only in the stage model.
Since: 5.0.0(12)
| Name | Type | Read-Only | Optional | Description |
|---|---|---|---|---|
| bankCard | BankCardConfig | No | Yes | Specific configuration for bank card recognition. Atomic service API: This API can be used in atomic services since version 5.0.0(12). |
| idCard | IdCardConfig | No | Yes | Specific configuration for ID card recognition. Atomic service API: This API can be used in atomic services since version 5.0.2(14). Since: 5.0.2(14) |
BankCardConfig
Specific configuration for bank card recognition.
Atomic service API: This API can be used in atomic services since version 5.0.0(12).
System capability: SystemCapability.AI.Component.CardRecognition
Model restriction: This API can be used only in the stage model.
Since: 5.0.0(12)
| Name | Type | Read-Only | Optional | Description |
|---|---|---|---|---|
| isBankNumberDialogShown | boolean | No | Yes | Indicates whether to display a confirmation dialog box for the bank card number after a bank card is recognized. The value true indicates yes and the value false indicates no. The default value is true. |
IdCardConfig
Specific configuration for ID card recognition.
System capability: SystemCapability.AI.Component.CardRecognition
Model restriction: This API can be used only in the stage model.
Since: 5.0.2(14)
| Name | Type | Read-Only | Optional | Description |
|---|---|---|---|---|
| isPhotoNeeded | boolean | No | Yes | Indicates whether to return the portrait image of an ID card after the portrait side of the ID card is recognized. true: yes false: no The default value is false. |
| isQualityDetectionNeeded | boolean | No | Yes | Indicates whether to enable quality check. true: yes false: no The default value is false. |
Card Information
Detailed information about a certificate, including the portrait side and national emblem side of an ID card, bank card, passport, front and back sides of a driver's license, front and back sides of a vehicle license, front and back sides of a Mainland Travel Permit for Hong Kong and Macao Residents, and front and back sides of a Mainland Travel Permit for Taiwan Residents.
Portrait side of an ID card.
Since: 5.0.0(12)
| Parameter | Type | Description |
|---|---|---|
| name | string | Name. |
| sex | string | Gender. |
| nationality | string | Ethnicity. |
| birth | string | Date of birth. |
| address | string | Address. |
| idNumber | string | Identification number. |
| cardImageUri | string | Image URI of the portrait side of an ID card (excluding the background). |
| originalImageUri | string | Image URI of the portrait side of an ID card (including the background). |
| photoUri | string | Image URI of the portrait on the portrait side of an ID card. This parameter is returned only when isPhotoNeeded is set to true. Since: 5.0.2(14) |
| photoLocation | string | Coordinates of a portrait image within an ID card image (portrait side) specified by cardImageUri. In the parameter value, top, left, width, and height indicate the top point, left point, width, and height of the portrait image, respectively. This parameter is returned only when isPhotoNeeded is set to true. Since: 5.0.2(14) |
| completenessProbability | string | Probability of completeness. The value range is (0, 1). A larger value indicates a higher probability of completeness. Since: 5.0.2(14) |
| reflectionProbability | string | Probability of light reflection. The value range is (0, 1). A larger value indicates a higher probability of light reflection. Since: 5.0.2(14) |
| clarityProbability | string | Probability of clarity. The value range is (0, 1). A larger value indicates a higher probability of clarity. Since: 5.0.2(14) |
| occlusionProbability | string | Probability of occlusion. The value range is (0, 1). A larger value indicates a higher probability of occlusion. Since: 5.0.2(14) |
National emblem side of an ID card.
Since: 5.0.0(12)
| Parameter | Type | Description |
|---|---|---|
| authority | string | Issuing authority. |
| validPeriod | string | Validity period. |
| cardImageUri | string | Image URI of the national emblem side of an ID card (excluding the background). |
| originalImageUri | string | Image URI of the national emblem side of an ID card (including the background). |
| completenessProbability | string | Probability of completeness. The value range is (0, 1). A larger value indicates a higher probability of completeness. Since: 5.0.2(14) |
| reflectionProbability | string | Probability of light reflection. The value range is (0, 1). A larger value indicates a higher probability of light reflection. Since: 5.0.2(14) |
| clarityProbability | string | Probability of clarity. The value range is (0, 1). A larger value indicates a higher probability of clarity. Since: 5.0.2(14) |
| occlusionProbability | string | Probability of occlusion. The value range is (0, 1). A larger value indicates a higher probability of occlusion. Since: 5.0.2(14) |
Bank card.
Since: 5.0.0(12)
| Parameter | Type | Description |
|---|---|---|
| bankNum | string | Bank card number. |
| validPeriod | string | Validity period. |
| cardImageUri | string | Image URI of a bank card (excluding the background). |
| originalImageUri | string | Image URI of a bank card (including the background). |
| cardNumImageUri | string | URI of a bank card number image. Since: 6.1.1(24) |
| isCropped | string | Whether the card image is successfully cropped. The value can be: "1": The card image is successfully cropped. In this case, the returned cardImageUri is a card image without the background. "0": The card image fails to be cropped. In this case, the returned cardImageUri is a card image with the background. Since: 6.1.1(24) |
| luhnCheckResult | string | Whether the bank card number meets the Luhn algorithm verification result. The value can be: "-1": No verification is performed. "0": The bank card number does not comply with the Luhn algorithm. "1": The bank card number complies with the Luhn algorithm. Since: 6.1.1(24) |
Passport.
Since: 5.0.0(12)
| Parameter | Type | Description |
|---|---|---|
| cardNum | string | Passport number. |
| name | string | Name. |
| sex | string | Gender. |
| nationality | string | Nationality. |
| birth | string | Date of birth. |
| address | string | Place of birth. |
| issueDate | string | Date of issue. |
| issuePlace | string | Place of issue. |
| expiryDate | string | Expiration date. |
| authority | string | Issuing authority. |
| pochn | string | Passport for private affairs. |
| cardImageUri | string | Image URI of a passport (excluding the background). |
| originalImageUri | string | Image URI of a passport (including the background). |
Front side of a driver's license.
Since: 5.0.0(12)
| Parameter | Type | Description |
|---|---|---|
| cardNum | string | License number. |
| name | string | Name. |
| sex | string | Gender. |
| nationality | string | Nationality. |
| birth | string | Date of birth. |
| address | string | Address. |
| dateOfFirstIssue | string | Date of first issue. |
| carClass | string | License class. |
| validPeriodStart | string | Start date of the validity period. |
| validPeriodEnd | string | End date of the validity period. |
| cardImageUri | string | Image URI of the front side of a driver's license (excluding the background). |
| originalImageUri | string | Image URI of the front side of a driver's license (including the background). |
Back side of a driver's license.
Since: 5.0.0(12)
| Parameter | Type | Description |
|---|---|---|
| cardNum | string | License number. |
| name | string | Name. |
| archivesNum | string | Archive number. |
| record | string | Record. |
| cardImageUri | string | Image URI of the back side of a driver's license (excluding the background). |
| originalImageUri | string | Image URI of the back side of a driver's license (including the background). |
Front side of a vehicle license.
Since: 5.0.0(12)
| Parameter | Type | Description |
|---|---|---|
| licensePlateNumber | string | License plate number. |
| vehicleType | string | Vehicle type. |
| owner | string | Owner. |
| address | string | Address. |
| useCharacter | string | Use character. |
| model | string | Brand and model. |
| vin | string | Vehicle identification number. |
| engineNum | string | Engine number. |
| registerDate | string | Registration date. |
| issueDate | string | Issue date. |
| cardImageUri | string | Image URI of the front side of a vehicle license (excluding the background). |
| originalImageUri | string | Image URI of the front side of a vehicle license (including the background). |
Back side of a vehicle license.
Since: 5.0.0(12)
| Parameter | Type | Description |
|---|---|---|
| cardNum | string | License plate number. |
| size | string | Vehicle dimensions. |
| remark | string | Remarks. |
| record | string | Inspection records. |
| cardImageUri | string | Image URI of the back side of a vehicle license (excluding the background). |
| originalImageUri | string | Image URI of the back side of a vehicle license (including the background). |
Front side of a mainland travel permit for Hong Kong and Macao residents:
Since: 6.1.1(24)
| Parameter | Type | Description |
|---|---|---|
| name | string | Name. |
| englishName | string | English name. |
| birth | string | Date of birth. |
| sex | string | Gender. |
| validPeriod | string | Validity period. |
| authority | string | Issuing authority. |
| idNumber | string | ID card number. |
| numbers | string | Number of renewals. |
Back side of a mainland travel permit for Hong Kong and Macao residents.
Since: 6.1.1(24)
| Parameter | Type | Description |
|---|---|---|
| name | string | Name on an ID card. |
| idNumber | string | ID number. |
Front side of a mainland travel permit for Taiwan residents.
Since: 6.1.1(24)
| Parameter | Type | Description |
|---|---|---|
| name | string | Name. |
| englishName | string | English name. |
| birth | string | Date of birth. |
| sex | string | Gender. |
| validPeriod | string | Validity period. |
| authority | string | Issuing authority. |
| address | string | Place of issue. |
| idNumber | string | ID card number. |
| numbers | string | Number of renewals. |
Back side of a mainland travel permit for Taiwan residents.
Since: 6.1.1(24)
| Parameter | Type | Description |
|---|---|---|
| name | string | Name on an ID card. |
| idNumber | string | ID number. |