目录

customScan (Scanning Barcodes Using the Custom UI)

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

Start version: 4.1.0(11)

Module Import

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

ViewControl

Camera control parameters.

System capability: SystemCapability.Multimedia.Scan.ScanBarcode

Start version: 4.1.0(11)

Parameter

Type

Read-Only

Optional

Description

width

number

No

No

Width of the XComponent. Supported units are px, lpx, and vp. The default unit is vp.

height

number

No

No

Height of the XComponent. Supported units are px, lpx, and vp. The default unit is vp.

surfaceId

string

No

No

ID of the surface held by the XComponent.

  1. The values of width and height of ViewControl must be consistent with those of XComponent. The start API will match the closest camera resolution based on the set width and height. If no proper camera resolution is matched, the API will return error code 1000500001 (internal error). XComponent, the capabilities of which are provided by the UI, offers the surface for preview streams. For details, please refer to XComponent.
  2. For foldable devices, you need to adjust the width and height of XComponent as needed when the folding status changes. The start API will readapt the camera resolution ratio.

Example:

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

@Entry
@Component
struct customScanPage {
  // Set the preview stream height. The default unit is vp.
  @State cameraHeight: number = 640;
  // Set the preview stream width. The default unit is vp.
  @State cameraWidth: number = 360;
  private mXComponentController: XComponentController = new XComponentController();

  build() {
    Stack() {
      XComponent({
        id: 'componentId',
        type: XComponentType.SURFACE,
        controller: this.mXComponentController
      })
        .onLoad(() => {
          hilog.info(0x0001, '[Scan Sample]', 'onLoad is called')
          // Obtain the surface ID of XComponent.
          let surfaceId: string = this.mXComponentController.getXComponentSurfaceId();
          hilog.info(0x0001, 'viewControl', `onLoad surfaceId: ${surfaceId}`);
          // Set parameters of ViewControl.
          let viewControl: customScan.ViewControl = {
            width: this.cameraWidth,
            height: this.cameraHeight,
            surfaceId: surfaceId
          };
          try {
            customScan.start(viewControl).then((scanResult: Array<scanBarcode.ScanResult>) => {
              hilog.info(0x0001, '[Scan Sample]',
                `Succeeded in getting ScanResult by promise, scanResult is ${JSON.stringify(scanResult)}`);
            }).catch((error: BusinessError) => {
              hilog.error(0x0001, '[Scan Sample]',
                `Failed to get ScanResult by promise. Code: ${error.code}, message: ${error.message}`);
            })
          } catch (error) {
            hilog.error(0x0001, '[Scan Sample]',
              `Failed to start customScan. Code: ${error.code}, message: ${error.message}`);
          }
        })
        .height(this.cameraHeight)
        .width(this.cameraWidth)
        .position({ x: 0, y: 0 })
    }
    .alignContent(Alignment.Bottom)
    .height('100%')
    .width('100%')
    .position({ x: 0, y: 0 })
  }
}

ScanFrame

Camera preview stream (YUV).

System capability: SystemCapability.Multimedia.Scan.ScanBarcode

Start version: 5.0.0(12)

Parameter

Type

Read-Only

Optional

Description

byteBuffer

ArrayBuffer

No

No

ArrayBuffer array of the camera preview stream.

width

number

No

No

Width of the camera preview stream, in px.

height

number

No

No

Height of the camera preview stream, in px.

scanCodeRects

Array<scanBarcode.ScanCodeRect>

No

Yes

Position information for barcode image detection in the camera preview stream.

Example:

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

@Entry
@Component
struct customScanPage {
  // Set the preview stream height. The default unit is vp.
  @State cameraHeight: number = 640;
  // Set the preview stream width. The default unit is vp.
  @State cameraWidth: number = 360;
  private mXComponentController: XComponentController = new XComponentController();
  private callback: AsyncCallback<scanBarcode.ScanResult[]> =
    async (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)}`);
    }
  // Obtain ScanFrame via a callback.
  private frameCallback: AsyncCallback<customScan.ScanFrame> =
    async (error: BusinessError, frameResult: customScan.ScanFrame) => {
      if (error) {
        hilog.error(0x0001, '[Scan Sample]',
          `Failed to get ScanFrame by callback. Code: ${error.code}, message: ${error.message}`);
        return;
      }
      // Camera YUV array in byteBuffer.
      hilog.info(0x0001, '[Scan Sample]',
        `Succeeded in getting ScanFrame.byteBuffer.byteLength:  ${frameResult.byteBuffer.byteLength}`);
      hilog.info(0x0001, '[Scan Sample]',
        `Succeeded in getting ScanFrame.scanCodeRect: ${JSON.stringify(frameResult.scanCodeRects)}`);
    }

  build() {
    Stack() {
      XComponent({
        id: 'componentId',
        type: XComponentType.SURFACE,
        controller: this.mXComponentController
      })
        .onLoad(() => {
          hilog.info(0x0001, '[Scan Sample]', 'Succeeded in loading, onLoad is called.');
          // Obtain the surface ID of XComponent.
          let surfaceId: string = this.mXComponentController.getXComponentSurfaceId();
          hilog.info(0x0001, '[Scan Sample]', `Succeeded ing getting surfaceId: ${surfaceId}`);
          // Set parameters of ViewControl.
          let viewControl: customScan.ViewControl = {
            width: this.cameraWidth,
            height: this.cameraHeight,
            surfaceId: surfaceId
          };
          try {
            customScan.start(viewControl, this.callback, this.frameCallback);
          } catch (error) {
            hilog.error(0x0001, '[Scan Sample]',
              `Failed to start customScan. Code: ${error.code}, message: ${error.message}`);
          }
        })
        .height(this.cameraHeight)
        .width(this.cameraWidth)
        .position({ x: 0, y: 0 })
    }
    .alignContent(Alignment.Bottom)
    .height('100%')
    .width('100%')
    .position({ x: 0, y: 0 })
  }
}
  1. In scanCodeRects, the barcode image position information in the landscape preview stream is returned. If further processing is needed, relevant coordinates need to be converted into the coordinate system in portrait orientation. The following uses the first element in scanCodeRects as an example to describe the conversion logic of the left, top, right, bottom parameters of each element.
    // The start API returns the frameResult data using frameCallback.
    import { customScan, scanBarcode } from '@kit.ScanKit';
    import { buffer } from '@kit.ArkTS';
    // Simulate the returned frameResult: customScan.ScanFrame data of the camera preview stream.
    let frameResult: customScan.ScanFrame = {
      "width": 1920,
      "height": 1080,
      "byteBuffer": buffer.from('1', 'hex').buffer,// Simulated byteBuffer data.
      "scanCodeRects": [{
        "left": 84,
        "top": 142,
        "right": 1695,
        "bottom": 996
      }]
    };
    if (frameResult && frameResult.scanCodeRects) {
      let rect: scanBarcode.ScanCodeRect = frameResult.scanCodeRects[0];
      // Convert the dimensions of the preview stream to match the dimensions of XComponent.
      let ratio = this.scanWidth / frameResult.height;
      let left = (frameResult.height - rect.bottom) * ratio;
      let top = rect.left * ratio;
      let right = (frameResult.height - rect.top) * ratio;
      let bottom = rect.right * ratio;
    }
  2. The bounding box of the QR code area can be defined and outlined using position({x: left, y: top}), width: right - left, and height: bottom - top.

customScan.init

init(options?: scanBarcode.ScanOptions): void

Initializes the custom UI for barcode scanning.

Required permission: ohos.permission.CAMERA

System capability: SystemCapability.Multimedia.Scan.ScanBarcode

Start version: 4.1.0(11)

Parameters:

Parameter

Type

Mandatory

Description

options

scanBarcode.ScanOptions

No

Parameters for scanning barcodes using the custom UI.

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.

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

let options: scanBarcode.ScanOptions = {
  scanTypes: [scanCore.ScanType.ALL],
  enableMultiMode: true,
  enableAlbum: true
};
try {
  customScan.init(options);
} catch (error) {
  hilog.error(0x0001, '[Scan Sample]', `Failed to init customScan. Code: ${error.code}, message: ${error.message}`);
}

customScan.start

start(viewControl: ViewControl): Promise<Array<scanBarcode.ScanResult>>

Starts barcode scanning camera streams. This API uses a promise to return the scanning result asynchronously.

This API can be used only after the init API is called.

Required permission: ohos.permission.CAMERA

System capability: SystemCapability.Multimedia.Scan.ScanBarcode

Start version: 4.1.0(11)

Parameters:

Parameter

Type

Mandatory

Description

viewControl

ViewControl

Yes

Camera control parameters.

Returns:

Type

Description

Promise<Array<scanBarcode.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.

Example:

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

@Entry
@Component
struct customScanPage {
  // Set the preview stream height. The default unit is vp.
  @State cameraHeight: number = 640
  // Set the preview stream width. The default unit is vp.
  @State cameraWidth: number = 360
  private mXComponentController: XComponentController = new XComponentController();

  build() {
    Stack() {
      XComponent({
        id: 'componentId',
        type: XComponentType.SURFACE,
        controller: this.mXComponentController
      })
        .onLoad(() => {
          hilog.info(0x0001, '[Scan Sample]', 'Succeeded in loading, onLoad is called.');
          // Obtain the surface ID of XComponent.
          let surfaceId: string = this.mXComponentController.getXComponentSurfaceId();
          hilog.info(0x0001, '[Scan Sample]', `Succeeded in getting surfaceId: ${surfaceId}`);
          // Set parameters of ViewControl.
          let viewControl: customScan.ViewControl = {
            width: this.cameraWidth,
            height: this.cameraHeight,
            surfaceId: surfaceId
          };
          try {
            customScan.start(viewControl).then((scanResult: Array<scanBarcode.ScanResult>) => {
              hilog.info(0x0001, '[Scan Sample]',
                `Succeeded in getting ScanResult by promise, scanResult is ${JSON.stringify(scanResult)}`);
            }).catch((error: BusinessError) => {
              hilog.error(0x0001, '[Scan Sample]',
                `Failed to get ScanResult by promise. Code: ${error.code}, message: ${error.message}`);
            });
          } catch (error) {
            hilog.error(0x0001, '[Scan Sample]',
              `Failed to start customScan. Code: ${error.code}, message: ${error.message}`);
          }
        })
        .height(this.cameraHeight)
        .width(this.cameraWidth)
        .position({ x: 0, y: 0 })
    }
    .alignContent(Alignment.Bottom)
    .height('100%')
    .width('100%')
    .position({ x: 0, y: 0 })
  }
}

customScan.start

start(viewControl: ViewControl, callback: AsyncCallback<Array<scanBarcode.ScanResult>>, frameCallback? :AsyncCallback<ScanFrame>): void

Starts barcode scanning camera streams. This API uses a callback to return the scanning result and camera preview stream (YUV NV21 format based on 4:2:0 sampling) asynchronously.

This API can be used only after the init API is called.

Required permission: ohos.permission.CAMERA

System capability: SystemCapability.Multimedia.Scan.ScanBarcode

Start version: 4.1.0(11)

Parameters:

Parameter

Type

Mandatory

Description

viewControl

ViewControl

Yes

Camera control parameters.

callback

AsyncCallback<Array<scanBarcode.ScanResult>>

Yes

Callback used to return the result. If the operation is successful, err is undefined and data is the obtained Array<scanBarcode.ScanResult>; otherwise, err is an error object.

frameCallback

AsyncCallback<ScanFrame>

No

Callback used to return the result. If the operation is successful, err is undefined and data is the obtained camera preview stream (YUV) data ScanFrame; otherwise, err is an error object.

Start version: 5.0.0(12)

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.

Example:

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

@Entry
@Component
struct customScanPage {
  // Set the preview stream height. The default unit is vp.
  @State cameraHeight: number = 640;
  // Set the preview stream width. The default unit is vp.
  @State cameraWidth: number = 360;
  private mXComponentController: XComponentController = new XComponentController();
  // Return the custom scanning result in a callback.
  private callback: AsyncCallback<Array<scanBarcode.ScanResult>> =
    async (error: BusinessError, result: Array<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)}`);
    }
  // Obtain ScanFrame via a callback.
  private frameCallback: AsyncCallback<customScan.ScanFrame> =
    async (error: BusinessError, scanFrame: customScan.ScanFrame) => {
      if (error) {
        hilog.error(0x0001, '[Scan Sample]',
          `Failed to get ScanFrame by callback. Code: ${error.code}, message: ${error.message}`);
        return;
      }
      hilog.info(0x0001, '[Scan Sample]',
        `Succeeded in getting ScanFrame by callback, scanFrame is ${JSON.stringify(scanFrame)}`);
    }

  build() {
    Stack() {
      XComponent({
        id: 'componentId',
        type: XComponentType.SURFACE,
        controller: this.mXComponentController
      })
        .onLoad(() => {
          hilog.info(0x0001, '[Scan Sample]', 'Succeeded in loading, onLoad is called.');
          // Obtain the surface ID of XComponent.
          let surfaceId: string = this.mXComponentController.getXComponentSurfaceId();
          hilog.info(0x0001, '[Scan Sample]', `Succeeded in getting surfaceId: ${surfaceId}`);
          // Set parameters of ViewControl.
          let viewControl: customScan.ViewControl = {
            width: this.cameraWidth,
            height: this.cameraHeight,
            surfaceId: surfaceId
          };
          try {
            customScan.start(viewControl, this.callback, this.frameCallback);
          } catch (error) {
            hilog.error(0x0001, '[Scan Sample]',
              `Failed to start customScan. Code: ${error.code}, message: ${error.message}`);
          }
        })
        .height(this.cameraHeight)
        .width(this.cameraWidth)
        .position({ x: 0, y: 0 })
    }
    .alignContent(Alignment.Bottom)
    .height('100%')
    .width('100%')
    .position({ x: 0, y: 0 })
  }
}

customScan.getFlashLightStatus

getFlashLightStatus(): boolean

Obtains the camera flash light status.

This API must be used after the start API. An internal error will occur if this API is used during initialization, stop, and release of camera streams.

System capability: SystemCapability.Multimedia.Scan.ScanBarcode

Start version: 4.1.0(11)

Returns:

Type

Description

boolean

true if the flash light is opened; false otherwise.

Error codes:

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

Error Code

Error Message

1000500001

Internal error.

Example:

import { customScan } from '@kit.ScanKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

let flashLightStatus: boolean = false;
try {
  flashLightStatus = customScan.getFlashLightStatus();
// Turn on or off the flash light based on the flash light status.
  if (flashLightStatus) {
    try {
      customScan.closeFlashLight();
    } catch (error) {
      hilog.error(0x0001, '[Scan Sample]', `Failed to closeFlashLight. Code: ${error.code}, message: ${error.message}`);
    }
  } else {
    try {
      customScan.openFlashLight();
    } catch (error) {
      hilog.error(0x0001, '[Scan Sample]', `Failed to openFlashLight. Code: ${error.code}, message: ${error.message}`);
    }
  }
} catch (error) {
  hilog.error(0x0001, '[Scan Sample]', `Failed to getFlashLightStatus. Code: ${error.code}, message: ${error.message}`);
}

customScan.openFlashLight

openFlashLight(): void

Turns on the camera flash light.

This API must be used after the start API. An internal error will occur if this API is used during initialization, stop, and release of camera streams.

System capability: SystemCapability.Multimedia.Scan.ScanBarcode

Start version: 4.1.0(11)

Error codes:

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

Error Code

Error Message

1000500001

Internal error.

Example:

import { customScan } from '@kit.ScanKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

let flashLightStatus: boolean = false;
try {
  flashLightStatus = customScan.getFlashLightStatus();
// Turn on or off the flash light based on the flash light status.
  if (flashLightStatus) {
    try {
      customScan.closeFlashLight();
    } catch (error) {
      hilog.error(0x0001, '[Scan Sample]', `Failed to closeFlashLight. Code: ${error.code}, message: ${error.message}`);
    }
  } else {
    try {
      customScan.openFlashLight();
    } catch (error) {
      hilog.error(0x0001, '[Scan Sample]', `Failed to openFlashLight. Code: ${error.code}, message: ${error.message}`);
    }
  }
} catch (error) {
  hilog.error(0x0001, '[Scan Sample]', `Failed to getFlashLightStatus. Code: ${error.code}, message: ${error.message}`);
}

customScan.closeFlashLight

closeFlashLight(): void

Turns off the camera flash light.

This API must be used after the start API. An internal error will occur if this API is used during initialization, stop, and release of camera streams.

System capability: SystemCapability.Multimedia.Scan.ScanBarcode

Start version: 4.1.0(11)

Error codes:

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

Error Code

Error Message

1000500001

Internal error.

Example:

import { customScan } from '@kit.ScanKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

let flashLightStatus: boolean = false;
try {
  flashLightStatus = customScan.getFlashLightStatus();
} catch (error) {
  hilog.error(0x0001, '[Scan Sample]', `Failed to getFlashLightStatus. Code: ${error.code}, message: ${error.message}`);
}
// Turn on or off the flash light based on the flash light status.
if (flashLightStatus) {
  try {
    customScan.closeFlashLight();
  } catch (error) {
    hilog.error(0x0001, '[Scan Sample]', `Failed to closeFlashLight. Code: ${error.code}, message: ${error.message}`);
  }
} else {
  try {
    customScan.openFlashLight();
  } catch (error) {
    hilog.error(0x0001, '[Scan Sample]', `Failed to openFlashLight. Code: ${error.code}, message: ${error.message}`);
  }
}

customScan.setZoom

setZoom(zoomValue: number): void

Sets a zoom ratio for the device, with a maximum precision of two decimal places.

This API must be used after the start API.

System capability: SystemCapability.Multimedia.Scan.ScanBarcode

Start version: 5.0.0(12)

Parameters:

Parameter

Type

Mandatory

Description

zoomValue

number

Yes

Camera zoom ratio, with a maximum precision of two decimal places (for example, 1.45).

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.

Example:
import { customScan } from '@kit.ScanKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

// Set a zoom ratio for the device.
let zoomValue = 2.0;
try {
  customScan.setZoom(zoomValue);
} catch (error) {
  hilog.error(0x0001, '[Scan Sample]', `Failed to setZoom. Code: ${error.code}, message: ${error.message}`);
}

customScan.getZoom

getZoom(): number

Obtains the zoom ratio in use.

This API must be used after the start API.

System capability: SystemCapability.Multimedia.Scan.ScanBarcode

Start version: 5.0.0(12)

Returns:

Type

Description

number

Zoom ratio in use.

Error codes:

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

Error Code

Error Message

1000500001

Internal error.

Example:

import { hilog } from '@kit.PerformanceAnalysisKit';
import { customScan } from '@kit.ScanKit';

try {
// Obtain the zoom ratio.
  let zoomValue = customScan.getZoom();
  hilog.info(0x0001, '[Scan Sample]', `Succeeded in getting zoomValue, zoomValue is ${zoomValue}`);
} catch (error) {
  hilog.error(0x0001, '[Scan Sample]', `Failed to get zoomValue. Code: ${error.code}, message: ${error.message}`);
}

customScan.setFocusPoint

setFocusPoint(point: scanBarcode.Point): void

Sets the focal point for the camera. The focal point must be in the coordinate system (0-1), where the upper left corner is {0, 0} and the lower right corner is {1, 1}. This coordinate system assumes a landscape device orientation with the charging port on the right. If your app's preview page is designed for the portrait mode with the charging port at the bottom, with a width of {w} and height of {h}, then a touch point at coordinates {x, y} in the portrait mode would be converted to {y/h, 1 - x/w} in landscape mode.

This API must be used after the start API.

System capability: SystemCapability.Multimedia.Scan.ScanBarcode

Start version: 5.0.0(12)

Parameters:

Parameter

Type

Mandatory

Description

point

scanBarcode.Point

Yes

Focal point. The value range of x and y must be within [0, 1]. If a value less than 0 is passed, the value 0 is used. If a value greater than 1 is passed, the value 1 is used.

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.

Example:
import { customScan } from '@kit.ScanKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

try {
// Set the focal point.
  customScan.setFocusPoint({ x: 0.5, y: 0.5 });
} catch (error) {
  hilog.error(0x0001, '[Scan Sample]', `Failed to setFocusPoint. Code: ${error.code}, message: ${error.message}`);
}

customScan.resetFocus

resetFocus(): void

Sets the focus mode to continuous auto-focus.

This API must be used after the start API.

System capability: SystemCapability.Multimedia.Scan.ScanBarcode

Start version: 5.0.0(12)

Error codes:

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

Error Code

Error Message

1000500001

Internal error.

Example:

import { customScan } from '@kit.ScanKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

try {
// Set the focus mode to continuous auto-focus.
  customScan.resetFocus();
} catch (error) {
  hilog.error(0x0001, '[Scan Sample]', `Failed to resetFocus. Code: ${error.code}, message: ${error.message}`);
}

customScan.on('lightingFlash')

on(type: 'lightingFlash', callback: AsyncCallback<boolean>): void

Registers the flash light turn-on time. This API uses a callback to return the flash light turn-on time asynchronously when the light conditions change.

This API must be used after the start API. An internal error will occur if this API is used when camera streams are not started.

System capability: SystemCapability.Multimedia.Scan.ScanBarcode

Start version: 5.0.0(12)

Parameters:

Parameter

Type

Mandatory

Description

type

string

Yes

Event callback type, which is fixed to lightingFlash, indicating that this API is called when the environment light conditions change and the flash light needs to be turned on or off.

callback

AsyncCallback<boolean>

Yes

Callback function. If true is returned, the light is dim and the flash light can be turned on. If false is returned, the environment is light and the flash light can be turned off.

Error codes:

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

Error Code

Error Message

1000500001

Internal error.

Example:

import { BusinessError } from '@kit.BasicServicesKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { customScan } from '@kit.ScanKit';

let callback = (error: BusinessError, bool: boolean) => {
  if (error) {
    hilog.error(0x0001, '[Scan Sample]',
      `Failed to light Flash by callback. Code: ${error.code}, message: ${error.message}`);
    return;
  }
  hilog.info(0x0001, '[Scan Sample]', `Succeeded in lighting Flash by callback, bool is ${bool}`);
}

try {
  customScan.on('lightingFlash', callback);
} catch (error) {
  hilog.error(0x0001, '[Scan Sample]',
    `Failed to listen lightingFlash. Code: ${error.code}, message: ${error.message}`);
}

customScan.off('lightingFlash')

off(type: 'lightingFlash', callback?: AsyncCallback<boolean>): void

Deregisters the flash light turn-on time. This API uses a callback to return the deregistration result asynchronously.

This API must be used after the start API. An internal error will occur if this API is used when camera streams are not started.

System capability: SystemCapability.Multimedia.Scan.ScanBarcode

Start version: 5.0.0(12)

Parameters:

Parameter

Type

Mandatory

Description

type

string

Yes

Event callback type, which is fixed to lightingFlash, indicating that this API is called when the environment light conditions change and the flash light needs to be turned on or off.

callback

AsyncCallback<boolean>

No

Callback used to return the result. This parameter is optional. If this parameter is specified, the callback with on('lightingFlash') is matched. (The callback object cannot be an anonymous function.) If this parameter is not specified, all callback functions associated with lightingFlash will be deregistered.

Error codes:

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

Error Code

Error Message

1000500001

Internal error.

Example:

import { BusinessError } from '@kit.BasicServicesKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { customScan } from '@kit.ScanKit';

let callback = (error: BusinessError, bool: boolean) => {
  if (error) {
    hilog.error(0x0001, '[Scan Sample]',
      `Failed to cancel Flash by callback. Code: ${error.code}, message: ${error.message}`);
    return;
  }
  hilog.info(0x0001, '[Scan Sample]', `Succeeded in cancelling Flash by callback, bool is ${bool}`);
}
// If the callback is not specified, listening on all lightingFlash events is canceled. If the callback is specified, the event types to be listened to must be the same as those in customScan.on.
try {
  customScan.off('lightingFlash', callback);
} catch (error) {
  hilog.error(0x0001, '[Scan Sample]',
    `Failed to listen lightingFlash. Code: ${error.code}, message: ${error.message}`);
}

customScan.rescan

rescan(): void

Initiates barcode scanning again. If the scanning result is not as expected, you can call this API to trigger scanning again.

This API must be used after the start API and before the stop API. An internal error will occur if this API is used when camera streams are not started.

This API applies only when the start API uses a callback to return the result.

System capability: SystemCapability.Multimedia.Scan.ScanBarcode

Start version: 5.0.0(12)

Error codes:

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

Error Code

Error Message

1000500001

Internal error.

Example:

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

@Entry
@Component
struct customScanPage {
  // Set the preview stream height. The default unit is vp.
  @State cameraHeight: number = 640;
  // Set the preview stream width. The default unit is vp.
  @State cameraWidth: number = 360;
  private mXComponentController: XComponentController = new XComponentController();
  // Return the custom scanning result in a callback.
  private callback: AsyncCallback<Array<scanBarcode.ScanResult>> =
    async (error: BusinessError, result: Array<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)}`);
      // Trigger scanning again. If your scanning page needs to trigger scanning again without restarting the camera, call the rescan API in the asynchronous callback of the start API.
      try {
        customScan.rescan();
      } catch (error) {
        hilog.error(0x0001, '[Scan Sample]',
          `Failed to rescan customScan. Code: ${error.code}, message: ${error.message}`);
      }
    }

  build() {
    Stack() {
      XComponent({
        id: 'componentId',
        type: XComponentType.SURFACE,
        controller: this.mXComponentController
      })
        .onLoad(() => {
          hilog.info(0x0001, '[Scan Sample]', 'Succeeded in loading, onLoad is called.');
          // Obtain the surface ID of XComponent.
          let surfaceId: string = this.mXComponentController.getXComponentSurfaceId();
          hilog.info(0x0001, '[Scan Sample]', `Succeeded in getting surfaceId: ${surfaceId}`);
          // Set parameters of ViewControl.
          let viewControl: customScan.ViewControl = {
            width: this.cameraWidth,
            height: this.cameraHeight,
            surfaceId: surfaceId
          };
          try {
            customScan.start(viewControl, this.callback);
          } catch (error) {
            hilog.error(0x0001, '[Scan Sample]',
              `Failed to start customScan. Code: ${error.code}, message: ${error.message}`);
          }
        })
        .height(this.cameraHeight)
        .width(this.cameraWidth)
        .position({ x: 0, y: 0 })
    }
    .alignContent(Alignment.Bottom)
    .height('100%')
    .width('100%')
    .position({ x: 0, y: 0 })
  }
}

customScan.stop

stop(): Promise<void>

Stops barcode scanning camera streams. This API returns the result asynchronously through a promise.

This API must be used after the start API. An internal error will occur if this API is used when camera streams are not started.

System capability: SystemCapability.Multimedia.Scan.ScanBarcode

Start version: 4.1.0(11)

Returns:

Type

Description

Promise<void>

Promise object. No result is returned.

Error codes:

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

Error Code

Error Message

1000500001

Internal error.

Example:

import { hilog } from '@kit.PerformanceAnalysisKit';
import { customScan } from '@kit.ScanKit';
import { BusinessError } from '@kit.BasicServicesKit';

try {
  customScan.stop().then(() => {
    hilog.info(0x0001, '[Scan Sample]', 'Succeeded in stopping scan by promise.');
  }).catch((error: BusinessError) => {
    hilog.error(0x0001, '[Scan Sample]',
      `Failed to stop scan by promise. Code: ${error.code}, message: ${error.message}`);
  });
} catch (error) {
  hilog.error(0x0001, '[Scan Sample]',
    `Failed to stop customScan. Code: ${error.code}, message: ${error.message}`);
}

customScan.stop

stop(callback: AsyncCallback<void>): void

Stops barcode scanning camera streams. This API returns the result asynchronously through a callback.

This API must be used after the start API. An internal error will occur if this API is used when camera streams are not started.

System capability: SystemCapability.Multimedia.Scan.ScanBarcode

Start version: 4.1.0(11)

Parameters:

Parameter

Type

Mandatory

Description

callback

AsyncCallback<void>

Yes

Callback function. If the operation is successful, err is undefined; 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

1000500001

Internal error.

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

try {
  customScan.stop((error: BusinessError) => {
    if (error) {
      hilog.error(0x0001, '[Scan Sample]',
        `Failed to stop scan by callback. Code: ${error.code}, message: ${error.message}`);
      return;
    }
    hilog.info(0x0001, '[Scan Sample]', 'Succeeded in stopping scan by callback.');
  })
} catch (error) {
  hilog.error(0x0001, '[Scan Sample]',
    `Failed to stop customScan. Code: ${error.code}, message: ${error.message}`);
}

customScan.release

release(): Promise<void>

Releases barcode scanning camera streams. This API returns the result asynchronously through a promise.

You are advised to call this API after the start and stop APIs. An internal error will occur if this API is used when camera streams are not started.

System capability: SystemCapability.Multimedia.Scan.ScanBarcode

Start version: 4.1.0(11)

Returns:

Type

Description

Promise<void>

Promise object. No result is returned.

Error codes:

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

Error Code

Error Message

1000500001

Internal error.

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

try {
  customScan.release().then(() => {
    hilog.info(0x0001, '[Scan Sample]', 'Succeeded in releasing scan by promise.');
  }).catch((error: BusinessError) => {
    hilog.error(0x0001, '[Scan Sample]',
      `Failed to release scan by promise. Code: ${error.code}, message: ${error.message}`);
  })
} catch (error) {
  hilog.error(0x0001, '[Scan Sample]',
    `Failed to release customScan. Code: ${error.code}, message: ${error.message}`);
}

customScan.release

release(callback: AsyncCallback<void>): void

Releases barcode scanning camera streams. This API returns the result asynchronously through a callback.

You are advised to call this API after the start and stop APIs. An internal error will occur if this API is used when camera streams are not started.

System capability: SystemCapability.Multimedia.Scan.ScanBarcode

Start version: 4.1.0(11)

Parameters:

Parameter

Type

Mandatory

Description

callback

AsyncCallback<void>

Yes

Callback function. If the operation is successful, err is undefined; 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

1000500001

Internal error.

Example:

import { hilog } from '@kit.PerformanceAnalysisKit';
import { customScan } from '@kit.ScanKit';
import { BusinessError } from '@kit.BasicServicesKit';

try {
  customScan.release((error: BusinessError) => {
    if (error) {
      hilog.error(0x0001, '[Scan Sample]',
        `Failed to release scan by callback. Code: ${error.code}, message: ${error.message}`);
      return;
    }
    hilog.info(0x0001, '[Scan Sample]', 'Succeeded in releasing scan by callback.');
  });
} catch (error) {
  hilog.error(0x0001, '[Scan Sample]',
    `Failed to release customScan. Code: ${error.code}, message: ${error.message}`);
}