Module Overview
The generateBarcode module can generate barcode images from text or byte arrays. Currently, the supported barcode formats are EAN-8, EAN-13, UPC-A, UPC-E, Codabar, Code 39, Code 93, Code 128, ITF-14, QR Code, Data Matrix, PDF417 and Aztec. Currently, the generation of MULTIFUNCTIONAL CODE is not supported.
To help you quickly get started, you are advised to refer to the official sample project.
Since: 4.1.0(11)
ErrorCorrectionLevel
Error correction rate enumeration. A higher error correction level improves a barcode's ability to be recognized even when it is physically damaged (such as scratches, stains, or partial obstruction). However, it also increases the image's complexity and overall size. In contrast, a lower error correction level produces a simpler, more compact code, but with reduced resilience to damage and scanning errors.
Model restriction: This API can be used only in the stage model.
Atomic service API: This API can be used in atomic services since API version 5.0.2(14).
System capability: SystemCapability.Multimedia.Scan.GenerateBarcode
Since: 4.1.0(11)
| Name | Value | Description |
|---|---|---|
| LEVEL_L | 0 | 7% error correction rate. |
| LEVEL_M | 1 | 15% error correction rate. |
| LEVEL_Q | 2 | 25% error correction rate. |
| LEVEL_H | 3 | 30% error correction rate. |
CreateOptions
Sets parameters for generating a barcode image.
Model restriction: This API can be used only in the stage model.
Atomic service API: This API can be used in atomic services since API version 5.0.2(14).
System capability: SystemCapability.Multimedia.Scan.GenerateBarcode
Since: 4.1.0(11)
| Name | Type | Read-Only | Optional | Description |
|---|---|---|---|---|
| scanType | scanCore.ScanType | No | No | Type of the barcode to be generated. |
| width | number | No | No | Barcode width, in pixels. The value range is [200, 4096]. |
| height | number | No | No | Barcode height, in pixels. The value range is [200, 4096]. |
| margin | number | No | Yes | Minimum margin of the generated barcode image, in px. The value ranges from 1 to 10. The default value is 1. |
| level | ErrorCorrectionLevel | No | Yes | Error correction level. The default value is LEVEL_H. This parameter is valid only when a QR code is generated. |
| backgroundColor | number | No | Yes | Background color of the generated barcode image. The value is a color in HEX format. The default value is 0xFFFFFF. |
| pixelMapColor | number | No | Yes | Color of the generated barcode image. The value is a color in HEX format. The default value is 0x000000. |
Suggestions on setting parameters for generating a barcode image:
Background color and barcode color of the barcode image
You are advised to use the default background color (white) and barcode color (black). The barcode recognition will be deteriorated if the contrast between the background color and barcode color is small.
Minimum barcode image margin
You are advised to use the default minimum margin, which is 1 px. The value ranges from 1 to 10.
Barcode image size
- When you generate a barcode of the QR Code, Data Matrix, or Aztec format, it is recommended that width and height be set to the same value ranging from 200 to 4096, in px. Otherwise, the generated barcode image would be too small to recognize.
- When you generate a barcode of the EAN-8, EAN-13, UPC-A, UPC-E, Codabar, Code 39, Code 93, Code 128, ITF-14, or PDF417 format, it is recommended that the ratio between the values of width and height be 2:1 and that the value of width be greater than 400, in px. Otherwise, the generated barcode image is too small, making it hard to be recognized.
Example:
import { scanCore, generateBarcode } from '@kit.ScanKit';
// The QR code is used as an example.
let options: generateBarcode.CreateOptions = {
scanType: scanCore.ScanType.QR_CODE,
width: 200,
height: 200,
margin: 1,
level: generateBarcode.ErrorCorrectionLevel.LEVEL_H,
backgroundColor: 0xFFFFFF,
pixelMapColor: 0x000000
}; createBarcode
createBarcode(content: string, options: CreateOptions): Promise<image.PixelMap>
Generates and returns a barcode image from text. This API uses a promise to return the result.
Model restriction: This API can be used only in the stage model.
Atomic service API: This API can be used in atomic services since API version 5.0.2(14).
System capability: SystemCapability.Multimedia.Scan.GenerateBarcode
Since: 4.1.0(11)
Parameters:
| Parameter | Type | Mandatory | Description |
|---|---|---|---|
| content | string | Yes | Character string used to generate a barcode image. You can check "Table 1 Restrictions on the content parameter" below to learn more about the restrictions on this parameter. |
| options | CreateOptions | Yes | Configuration for generating a barcode image. |
Returns:
| Type | Description |
|---|---|
| Promise<image.PixelMap> | Promise used to return the generated barcode image object. |
Error codes:
For details about the error codes, please refer to Universal Error Codes and ArkTS API Error Codes.
| ID | Error Message |
|---|---|
| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. |
| 1000500001 | Internal error. |
Example:
import { image } from '@kit.ImageKit';
import { scanCore, generateBarcode } from '@kit.ScanKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
// The following uses a QR code as an example to describe the parameters for generating a barcode image.
const content: string = 'Huawei@HMSCore';
const options: generateBarcode.CreateOptions = {
scanType: scanCore.ScanType.QR_CODE,
width: 200,
height: 200
};
generateBarcode.createBarcode(content, options).then((data: image.PixelMap) => {
// The barcode image is generated successfully, and the PixelMap object of the generated barcode image is returned.
hilog.info(0x0001, '[Scan Sample]',
`Succeeded in getting PixelMap by promise with options, isResultAvailable: ${!!data}`);
}).catch((err: BusinessError) => {
// The barcode image fails to be generated, and an error message is returned.
hilog.error(0x0001, '[Scan Sample]',
`Failed to get PixelMap by promise with options. Code: ${err.code}, message: ${err.message}`);
}); Table 1 Restrictions on the content parameter
| Barcode Type | Restriction |
|---|---|
| QR Code | Chinese characters are supported. The value can contain a maximum of 512 characters. If the content is too long, the barcode will be complex and cannot be easily recognized. |
| Aztec | Chinese characters are supported. The value can contain a maximum of 512 characters. If the content is too long, the barcode will be complex and cannot be easily recognized. |
| PDF417 | Chinese characters are supported. The value can contain a maximum of 512 characters. If the content is too long, the barcode will be complex and cannot be easily recognized. |
| Data Matrix | Chinese characters are not supported. The value can contain a maximum of 512 characters. If the content is too long, the barcode will be complex and cannot be easily recognized. |
| UPC-A | The string can contain 11 digits and can contain only digits. It will be converted into a 12-digit barcode image, with the last digit being a verification digit. |
| UPC-E | The string can contain 7 digits and can contain only digits. It will be converted into an 8-digit barcode image, with the last digit being a verification digit. The first digit must be 0 or 1. |
| ITF-14 | The string can contain a maximum of 80 digits and must contain an even number of digits. It will be converted into a barcode image containing an even number of digits. If the content is too long, the barcode will be complex and cannot be easily recognized. |
| EAN-8 | The string can contain 7 digits and can contain only digits. It will be converted into an 8-digit barcode image, with the last digit being a verification digit. |
| EAN-13 | The string can contain 12 digits and can contain only digits. The first digit cannot be 0. It will be converted into a 13-digit barcode image, with the last digit being a verification digit. |
| Code 39 | The value can contain a maximum of 80 bytes. If the content is too long, the barcode will be complex and cannot be easily recognized. The character set can contain digits, uppercase letters, lowercase letters, and hyphens (-). The string can contain English symbols such as $ / + % * and spaces. Note that a lowercase letter occupies two bytes. |
| Code 93 | The value can contain a maximum of 80 bytes. If the content is too long, the barcode will be complex and cannot be easily recognized. The character set can contain digits, uppercase letters, lowercase letters, and hyphens (-). The string can contain English symbols such as $ / + % * and spaces. Note that a lowercase letter occupies two bytes. |
| Code 128 | The value can contain a maximum of 80 bytes. If the content is too long, the barcode will be complex and cannot be easily recognized. The character set can contain digits, uppercase letters, lowercase letters, and hyphens (-). The string can contain English symbols such as $ / + % * and spaces. Note that a lowercase letter occupies one byte. |
| Codabar | The value can contain a maximum of 512 characters. If the content is too long, the barcode will be complex and cannot be easily recognized. The start and end characters can be any of ABCD. (In special cases, TN*E is also encoded as ABCD. ABCD is recommended.) Other characters in the barcode can be numbers, hyphens (-), dots (.), dollar signs ($), slashes (/), colons (:), and plus signs (+). |
createBarcode
createBarcode(content: string, options: CreateOptions, callback: AsyncCallback<image.PixelMap>): void
Generates and returns a barcode image from text. This API uses an asynchronous callback to return the result.
Model restriction: This API can be used only in the stage model.
Atomic service API: This API can be used in atomic services since API version 5.0.2(14).
System capability: SystemCapability.Multimedia.Scan.GenerateBarcode
Since: 4.1.0(11)
Parameters:
| Parameter | Type | Mandatory | Description |
|---|---|---|---|
| content | string | Yes | Character string used to generate a barcode image. For details about the parameter restrictions, see "Table 1 Restrictions on the content parameter" in createBarcode. |
| options | CreateOptions | Yes | Configuration for generating a barcode image. |
| callback | AsyncCallback<image.PixelMap> | Yes | Callback function. If the barcode image is generated successfully, err is undefined and data is the generated barcode image object image.PixelMap. Otherwise, data is an error object. |
Error codes:
For details about the error codes, please refer to Universal Error Codes and ArkTS API Error Codes.
| ID | Error Message |
|---|---|
| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. |
| 1000500001 | Internal error. |
Example:
import { image } from '@kit.ImageKit';
import { scanCore, generateBarcode } from '@kit.ScanKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
// The following uses a QR code as an example to describe the parameters for generating a barcode image.
const content: string = 'Huawei@HMSCore';
const options: generateBarcode.CreateOptions = {
scanType: scanCore.ScanType.QR_CODE,
width: 200,
height: 200
};
generateBarcode.createBarcode(content, options, (err: BusinessError, data: image.PixelMap) => {
// The barcode image fails to be generated, and an error message is returned.
if (err) {
hilog.error(0x0001, '[Scan Sample]',
`Failed to get PixelMap by callback with options. Code: ${err.code}, message: ${err.message}`);
return;
}
// The barcode image is generated successfully, and the PixelMap object of the generated barcode image is returned.
hilog.info(0x0001, '[Scan Sample]',
`Succeeded in getting PixelMap by callback with options, isResultAvailable : ${!!data}`);
}); createBarcode
createBarcode(content: ArrayBuffer, options: CreateOptions): Promise<image.PixelMap>
Generates and returns a barcode image from a byte array. This API uses a promise to return the result.
Model restriction: This API can be used only in the stage model.
Atomic service API: This API can be used in atomic services since API version 5.0.2(14).
System capability: SystemCapability.Multimedia.Scan.GenerateBarcode
Since: 5.0.0(12)
Parameters:
| Parameter | Type | Mandatory | Description |
|---|---|---|---|
| content | ArrayBuffer | Yes | Byte array used to generate a barcode image. You can check "Table 2 Restrictions on the content parameter" below to learn more about restrictions on this parameter. |
| options | CreateOptions | Yes | Configuration parameter for barcode image generation. ScanType supports only QR codes. |
Returns:
| Type | Description |
|---|---|
| Promise<image.PixelMap> | Promise used to return the generated barcode image object. |
Error codes:
For details about the error codes, please refer to Universal Error Codes and ArkTS API Error Codes.
| ID | Error Message |
|---|---|
| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. |
| 1000500001 | Internal error. |
Example:
import { image } from '@kit.ImageKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { scanCore, generateBarcode } from '@kit.ScanKit';
import { buffer } from '@kit.ArkTS';
@Entry
@Component
struct Index {
@State pixelMap: image.PixelMap | undefined = undefined;
build() {
Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) {
Button('generateBarcode Promise').onClick(() => {
this.pixelMap = undefined;
const content: string =
'0177C10DD10F7768600202312110000063458FD14112345678FFFFD381012610b746365409210201b66636540ad0200020000000000110e617003201000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000006645fbec664358ECF657CB40693c92da';
const contentBuffer: ArrayBuffer = buffer.from(content, 'hex').buffer; // Convert a character string that contains hexadecimal characters into an ArrayBuffer.
const options: generateBarcode.CreateOptions = {
scanType: scanCore.ScanType.QR_CODE,
width: 400,
height: 400
}; // Parameters for generating a barcode image.
generateBarcode.createBarcode(contentBuffer, options).then((pixelMap: image.PixelMap) => {
this.pixelMap = pixelMap; // The barcode image is generated successfully. The PixelMap object of the generated barcode image is returned.
hilog.info(0x0001, '[Scan Sample]', 'Succeeded in creating barCode.');
}).catch((err: BusinessError) => {
// The barcode image fails to be generated, and an error message is returned.
hilog.error(0x0001, '[Scan Sample]',
`Failed to create barCode. Code: ${err.code}, message: ${err.message}`);
});
})
// The barcode image is generated successfully and displayed.
if (this.pixelMap) {
Image(this.pixelMap).width('400px').height('400px').objectFit(ImageFit.Contain)
}
}
.width('100%')
.height('100%')
}
} Table 2 Restrictions on the content parameter
| Correction Level | Parameter Restrictions |
|---|---|
| LEVEL_L | It is recommended that the byte array length be less than or equal to 2048. If it is too long, the barcode will be complex and cannot be easily recognized. |
| LEVEL_M | It is recommended that the byte array length be less than or equal to 2048. If it is too long, the barcode will be complex and cannot be easily recognized. |
| LEVEL_Q | It is recommended that the byte array length be less than or equal to 1536. If it is too long, the barcode will be complex and cannot be easily recognized. |
| LEVEL_H | It is recommended that the byte array length be less than or equal to 1024. If it is too long, the barcode will be complex and cannot be easily recognized. |