目录

scanBarcode (Scanning Barcodes Using the Default UI)

This module provides the capability of scanning barcodes using the default UI.

Start version: 4.0.0(10)

Module Import

import { scanBarcode } from '@kit.ScanKit';

ScanResult

Scanning result.

System capability: SystemCapability.Multimedia.Scan.ScanBarcode

Start version: 4.0.0(10)

Parameter

Type

Read-Only

Optional

Description

scanType

scanCore.ScanType

No

No

Barcode type.

Atomic service API: This API can be used in atomic services since API version 4.1.0(11).

originalValue

string

No

No

Barcode recognition result.

Atomic service API: This API can be used in atomic services since API version 4.1.0(11).

scanCodeRect

ScanCodeRect

No

Yes

Barcode position information.

Start version: 4.1.0(11)

cornerPoints

Array<Point>

No

Yes

Barcode position information, which contains the coordinates of the four corner points of the QR code.

Start version: 5.0.0(12)

NOTE:

This parameter is returned only by the detectBarcode.decodeImage API.

ScanCodeRect

Barcode position information. The barcode position is not returned when the default barcode scanning APIs (startScan and startScanForResult) are used.

System capability: SystemCapability.Multimedia.Scan.ScanBarcode

Start version: 4.1.0(11)

Parameter

Type

Read-Only

Optional

Description

left

number

No

No

X coordinate of the upper left corner of the bounding rectangle, in px.

top

number

No

No

Y coordinate of the upper left corner of the bounding rectangle, in px.

right

number

No

No

X coordinate of the lower right corner of the bounding rectangle, in px.

bottom

number

No

No

Y coordinate of the lower right corner of the bounding rectangle, in px.

Point

Defines the coordinates of a point. This coordinate system uses the top-left corner as the origin {0, 0}. It's based on the device held horizontally, with the charging port on the right side.

System capability: SystemCapability.Multimedia.Scan.ScanBarcode

Start version: 5.0.0(12)

Parameter

Type

Read-Only

Optional

Description

x

number

No

No

X-axis coordinate. The unit is px.

y

number

No

No

Y-axis coordinate. The unit is px.

ScanOptions

Barcode scan and recognition parameters.

Atomic service API: This API can be used in atomic services since API version 4.1.0(11).

System capability: SystemCapability.Multimedia.Scan.ScanBarcode

Start version: 4.0.0(10)

Parameter

Type

Read-Only

Optional

Description

scanTypes

Array<scanCore.ScanType>

No

Yes

Barcode scan type. The default value is ALL (indicating that all types of barcodes are scanned).

enableMultiMode

boolean

No

Yes

Indicates whether to enable the multi-barcode scanning mode. The default value is false.

  • true: yes
  • false: no

enableAlbum

boolean

No

Yes

Indicates whether to enable gallery-based barcode scanning. The default value is true.

  • true: yes
  • false: no
CAUTION:

This parameter controls only gallery-based barcode scanning of the capability to scan barcodes using the default UI, and supports only single barcode recognition.

Example:

import { scanBarcode, scanCore } from '@kit.ScanKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { BusinessError } from '@kit.BasicServicesKit';

// Define scanning parameters.
let options: scanBarcode.ScanOptions = { scanTypes: [scanCore.ScanType.ALL], enableMultiMode: true, enableAlbum: true };
try {
  scanBarcode.startScanForResult(getContext(this), options).then((result: scanBarcode.ScanResult) => {
    hilog.info(0x0001, '[Scan Sample]',
      `Succeeded in getting ScanResult by promise with options, result is ${JSON.stringify(result)}`);
  }).catch((error: BusinessError) => {
    hilog.error(0x0001, '[Scan Sample]',
      `Failed to get ScanResult by promise with options. Code: ${error.code}, message: ${error.message}`);
  });
} catch (error) {
  hilog.error(0x0001, '[Scan Sample]', `Failed to startScanForResult. Code: ${error.code}, message: ${error.message}`);
}

scanBarcode.startScanForResult

startScanForResult(context: common.Context, options?: ScanOptions): Promise<ScanResult>

Scans barcodes using the default UI based on input parameters. This API uses a promise to return the result asynchronously. This API must be called in the lifecycles of the UI and component.

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 4.1.0(11).

System capability: SystemCapability.Multimedia.Scan.ScanBarcode

Start version: 4.1.0(11)

Parameters:

Parameter

Type

Mandatory

Description

context

common.Context

Yes

App context.

options

ScanOptions

No

Parameters for starting barcode scanning.

Returns:

Type

Description

Promise<ScanResult>

Promise object, used to return the scanning result.

Error codes:

For details about the error codes, please refer to ArkTS API Error Codes.

Error Code

Error Message

401

Parameter error. Possible causes: 1. Incorrect parameter types; 2. Parameter verification failed.

1000500001

Internal error.

1000500002

The user canceled the barcode scanning.

Example:
import { scanCore, scanBarcode } from '@kit.ScanKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { BusinessError } from '@kit.BasicServicesKit';

// Define scanning parameters.
let options: scanBarcode.ScanOptions = { scanTypes: [scanCore.ScanType.ALL], enableMultiMode: true, enableAlbum: true };
try {
  scanBarcode.startScanForResult(getContext(this), options).then((result: scanBarcode.ScanResult) => {
    hilog.info(0x0001, '[Scan Sample]',
      `Succeeded in getting ScanResult by promise with options, result is ${JSON.stringify(result)}`);
  }).catch((error: BusinessError) => {
    hilog.error(0x0001, '[Scan Sample]',
      `Failed to get ScanResult by promise with options. Code: ${error.code}, message: ${error.message}`);
  });
} catch (error) {
  hilog.error(0x0001, '[Scan Sample]', `Failed to startScanForResult. Code: ${error.code}, message: ${error.message}`);
}

scanBarcode.startScanForResult

startScanForResult(context: common.Context, callback: AsyncCallback<ScanResult>): void

Opens the default scanning UI to scan barcodes. This API uses a callback to return the result asynchronously. This API must be called in the lifecycles of the UI and component.

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 4.1.0(11).

System capability: SystemCapability.Multimedia.Scan.ScanBarcode

Start version: 4.1.0(11)

Parameters:

Parameter

Type

Mandatory

Description

context

common.Context

Yes

App context.

callback

AsyncCallback<ScanResult>

Yes

Callback function. If the operation is successful, err is undefined and data is the obtained scanning result object ScanResult; otherwise, err is an error object.

Error codes:

For details about the error codes, please refer to ArkTS API Error Codes.

Error Code

Error Message

401

Parameter error. Possible causes: 1. Incorrect parameter types; 2. Parameter verification failed.

1000500001

Internal error.

1000500002

The user canceled the barcode scanning.

Example:
import { scanBarcode } from '@kit.ScanKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { BusinessError } from '@kit.BasicServicesKit';

// Open the barcode scanning UI.
try {
  scanBarcode.startScanForResult(getContext(this), (error: BusinessError, result: scanBarcode.ScanResult) => {
    if (error) {
      hilog.error(0x0001, '[Scan Sample]',
        `Failed to get ScanResult by callback. Code: ${error.code}, message: ${error.message}`);
      return;
    }
    hilog.info(0x0001, '[Scan Sample]',
      `Succeeded in getting ScanResult by callback, result is ${JSON.stringify(result)}`);
  });
} catch (error) {
  hilog.error(0x0001, '[Scan Sample]', `Failed to startScanForResult. Code: ${error.code}, message: ${error.message}`);
}

scanBarcode.startScanForResult

startScanForResult(context: common.Context, options: ScanOptions, callback: AsyncCallback<ScanResult>): void

Scans barcodes using the default UI based on input parameters. This API uses a callback to return the result asynchronously. This API must be called in the lifecycles of the UI and component.

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 4.1.0(11).

System capability: SystemCapability.Multimedia.Scan.ScanBarcode

Start version: 4.1.0(11)

Parameters:

Parameter

Type

Mandatory

Description

context

common.Context

Yes

App context.

options

ScanOptions

Yes

Parameters for starting barcode scanning.

callback

AsyncCallback<ScanResult>

Yes

Callback function. If the operation is successful, err is undefined and data is the obtained scanning result object ScanResult; otherwise, err is an error object.

Error codes:

For details about the error codes, please refer to ArkTS API Error Codes.

Error Code

Error Message

401

Parameter error. Possible causes: 1. Incorrect parameter types; 2. Parameter verification failed.

1000500001

Internal error.

1000500002

The user canceled the barcode scanning.

Example:
import { scanCore, scanBarcode } from '@kit.ScanKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { BusinessError } from '@kit.BasicServicesKit';

// Define scanning parameters.
let options: scanBarcode.ScanOptions = { scanTypes: [scanCore.ScanType.ALL], enableMultiMode: true, enableAlbum: true };
// Open the barcode scanning UI.
try {
  scanBarcode.startScanForResult(getContext(this), options, (error: BusinessError, result: scanBarcode.ScanResult) => {
    if (error) {
      hilog.error(0x0001, '[Scan Sample]',
        `Failed to get ScanResult by callback with options. Code: ${error.code}, message: ${error.message}`);
      return;
    }
    hilog.info(0x0001, '[Scan Sample]',
      `Succeeded in getting ScanResult by callback with options, result is ${JSON.stringify(result)}`);
  });
} catch (error) {
  hilog.error(0x0001, '[Scan Sample]', `Failed to startScanForResult. Code: ${error.code}, message: ${error.message}`);
}

scanBarcode.startScan(deprecated)

startScan(options?: ScanOptions): Promise<ScanResult>

Scans barcodes using the default UI based on input parameters. This API uses a promise to return the scanning result asynchronously.

Deprecation description: This API is deprecated from API version 4.1.0(11). You are advised to use startScanForResult instead.

System capability: SystemCapability.Multimedia.Scan.ScanBarcode

Start version: 4.0.0(10)

Parameters:

Parameter

Type

Mandatory

Description

options

ScanOptions

No

Parameters for starting barcode scanning.

Returns:

Type

Description

Promise<ScanResult>

Promise object, used to return the scanning result.

Error codes:

For details about the error codes, please refer to ArkTS API Error Codes.

Error Code

Error Message

401

Parameter error. Possible causes: 1. Incorrect parameter types; 2. Parameter verification failed.

Example:
import { scanCore, scanBarcode } from '@kit.ScanKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { BusinessError } from '@kit.BasicServicesKit';

// Set input parameters for starting barcode scanning.
let options: scanBarcode.ScanOptions = { scanTypes: [scanCore.ScanType.ALL], enableMultiMode: true, enableAlbum: true };
try {
  scanBarcode.startScan(options).then((result: scanBarcode.ScanResult) => {
    hilog.info(0x0001, '[Scan Sample]',
      `Succeeded in getting ScanResult by promise with options, result is ${JSON.stringify(result)}`);
  }).catch((error: BusinessError) => {
  // Return the error occurred during barcode scanning.
    hilog.error(0x0001, '[Scan Sample]',
      `Failed to get ScanResult by promise with options. Code: ${error.code}, message: ${error.message}`);
  });
} catch (error) {
  hilog.error(0x0001, '[Scan Sample]', `Failed to startScan. Code: ${error.code}, message: ${error.message}`);
}

scanBarcode.startScan(deprecated)

startScan(callback: AsyncCallback<ScanResult>): void

Opens the default scanning UI to scan barcodes. This API uses a callback to return the barcode scanning result asynchronously.

Deprecation description: This API is deprecated from API version 4.1.0(11). You are advised to use startScanForResult instead.

System capability: SystemCapability.Multimedia.Scan.ScanBarcode

Start version: 4.0.0(10)

Parameters:

Parameter

Type

Mandatory

Description

callback

AsyncCallback<ScanResult>

Yes

Callback function. If the operation is successful, err is undefined and data is the obtained scanning result object ScanResult; otherwise, err is an error object.

Error codes:

For details about the error codes, please refer to ArkTS API Error Codes.

Error Code

Error Message

401

Parameter error. Possible causes: 1. Incorrect parameter types; 2. Parameter verification failed.

Example:
import { scanBarcode } from '@kit.ScanKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { BusinessError } from '@kit.BasicServicesKit';

try {
  scanBarcode.startScan((error: BusinessError, result: scanBarcode.ScanResult) => {
  // Error callback for returning the error occurred during barcode scanning.
    if (error) {
      hilog.error(0x0001, '[Scan Sample]',
        `Failed to get ScanResult by callback. Code: ${error.code}, message: ${error.message}`);
      return;
    }
    hilog.info(0x0001, '[Scan Sample]',
      `Succeeded in getting ScanResult by callback, result is ${JSON.stringify(result)}`);
  });
} catch (error) {
  hilog.error(0x0001, '[Scan Sample]', `Failed to startScan. Code: ${error.code}, message: ${error.message}`);
}

scanBarcode.startScan(deprecated)

startScan(options: ScanOptions, callback: AsyncCallback<ScanResult>): void

Scans barcodes using the default UI based on input parameters. This API uses a callback to return the scanning result asynchronously.

Deprecation description: This API is deprecated from API version 4.1.0(11). You are advised to use startScanForResult instead.

System capability: SystemCapability.Multimedia.Scan.ScanBarcode

Start version: 4.0.0(10)

Parameters:

Parameter

Type

Mandatory

Description

options

ScanOptions

Yes

Parameters for starting barcode scanning.

callback

AsyncCallback<ScanResult>

Yes

Callback function. If the operation is successful, err is undefined and data is the obtained scanning result object ScanResult; otherwise, err is an error object.

Error codes:

For details about the error codes, please refer to ArkTS API Error Codes.

Error Code

Error Message

401

Parameter error. Possible causes: 1. Incorrect parameter types; 2. Parameter verification failed.

Example:
import { scanCore, scanBarcode } from '@kit.ScanKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { BusinessError } from '@kit.BasicServicesKit';

// Set input parameters for starting barcode scanning.
let options: scanBarcode.ScanOptions = { scanTypes: [scanCore.ScanType.ALL], enableMultiMode: true, enableAlbum: true };
try {
  scanBarcode.startScan(options, (error: BusinessError, result: scanBarcode.ScanResult) => {
  // Error callback for returning the error occurred during barcode scanning.
    if (error) {
      hilog.error(0x0001, '[Scan Sample]',
        `Failed to get ScanResult by callback with options. Code: ${error.code}, message: ${error.message}`);
      return;
    }
    hilog.info(0x0001, '[Scan Sample]',
      `Succeeded in getting ScanResult by callback with options, result is ${JSON.stringify(result)}`);
  });
} catch (error) {
  hilog.error(0x0001, '[Scan Sample]', `Failed to startScan. Code: ${error.code}, message: ${error.message}`);
}