@ohos.scan (扫描)

导入模块

import { scan } from '@kit.BasicServicesKit';

ScanErrorCode

定义扫描错误码的枚举。

系统能力： SystemCapability.Print.PrintFramework

ConstraintType

定义参数约束类型的枚举。

系统能力： SystemCapability.Print.PrintFramework

PhysicalUnit

定义物理单位的枚举。

系统能力： SystemCapability.Print.PrintFramework

OptionValueType

定义选项值类型的枚举。

系统能力： SystemCapability.Print.PrintFramework

ScannerSyncMode

定义扫描仪同步模式的枚举。

系统能力： SystemCapability.Print.PrintFramework

ScannerDiscoveryMode

定义扫描仪发现模式的枚举。

系统能力： SystemCapability.Print.PrintFramework

Range

定义范围的接口。

系统能力： SystemCapability.Print.PrintFramework

属性：

ScannerParameter

定义扫描仪参数的接口。

系统能力： SystemCapability.Print.PrintFramework

属性：

ScannerOptionValue

定义扫描仪选项值的接口。当对应选项的约束类型为SCAN_CONSTRAINT_STRING_LIST时，选项取值应为optionConstraintString集合中的字符串。

系统能力： SystemCapability.Print.PrintFramework

属性：

PictureScanProgress

定义图片扫描进度的接口。

系统能力： SystemCapability.Print.PrintFramework

属性：

ScannerDevice

定义扫描仪设备的接口。

系统能力： SystemCapability.Print.PrintFramework

属性：

ScannerSyncDevice

定义扫描仪同步设备的接口。

系统能力： SystemCapability.Print.PrintFramework

属性：

scan.init

init(): Promise<void>

初始化扫描服务，必须在调用其它扫描接口前完成初始化。使用Promise异步回调。使用完毕后需调用exit()退出扫描服务，释放资源。

需要权限： ohos.permission.PRINT

系统能力： SystemCapability.Print.PrintFramework

返回值：

错误码：

示例：

import { scan } from '@kit.BasicServicesKit';
import { BusinessError } from '@kit.BasicServicesKit';

scan.init().then(() => {
    console.info('scan init success');
}).catch((error: BusinessError) => {
    console.error(`Failed to init scan. Code: ${error.code}, message: ${error.message}`);
});

scan.exit

exit(): Promise<void>

退出扫描服务。使用Promise异步回调。扫描服务退出后，其它扫描方法将不可用，如需再次使用需重新调用init()。

需要权限： ohos.permission.PRINT

系统能力： SystemCapability.Print.PrintFramework

返回值：

错误码：

示例：

import { scan } from '@kit.BasicServicesKit';
import { BusinessError } from '@kit.BasicServicesKit';

scan.exit().then(() => {
    console.info('scan exit success');
}).catch((error: BusinessError) => {
    console.error(`Failed to exit scan. Code: ${error.code}, message: ${error.message}`);
});

scan.startScannerDiscovery

startScannerDiscovery(): Promise<void>

开始发现扫描仪，发现的扫描仪设备信息通过on('scanDeviceFound')事件回调通知。需在调用init()完成初始化后使用。使用Promise异步回调。

需要权限： ohos.permission.PRINT

系统能力： SystemCapability.Print.PrintFramework

返回值：

错误码：

示例：

import { scan } from '@kit.BasicServicesKit';
import { BusinessError } from '@kit.BasicServicesKit';

scan.startScannerDiscovery().then(() => {
    console.info('start scanner discovery success');
}).catch((error: BusinessError) => {
    console.error(`Failed to start scanner discovery. Code: ${error.code}, message: ${error.message}`);
});

scan.openScanner

openScanner(scannerId: string): Promise<void>

打开扫描仪。需在调用init()完成初始化后使用。使用Promise异步回调。在使用完毕后，需调用closeScanner()关闭扫描仪，释放资源。

需要权限： ohos.permission.PRINT

系统能力： SystemCapability.Print.PrintFramework

参数：

返回值：

错误码：

示例：

import { scan } from '@kit.BasicServicesKit';
import { BusinessError } from '@kit.BasicServicesKit';

let scannerId: string = 'scanner_001';
scan.openScanner(scannerId).then(() => {
    console.info('open scanner success');
}).catch((error: BusinessError) => {
    console.error(`Failed to open scanner. Code: ${error.code}, message: ${error.message}`);
});

scan.closeScanner

closeScanner(scannerId: string): Promise<void>

关闭扫描仪。使用Promise异步回调。扫描仪关闭后，将不能再对该扫描仪执行参数获取、设置、扫描等操作。如需再次使用需重新调用openScanner()。

需要权限： ohos.permission.PRINT

系统能力： SystemCapability.Print.PrintFramework

参数：

返回值：

错误码：

示例：

import { scan } from '@kit.BasicServicesKit';
import { BusinessError } from '@kit.BasicServicesKit';

let scannerId: string = 'scanner_001';
scan.closeScanner(scannerId).then(() => {
    console.info('close scanner success');
}).catch((error: BusinessError) => {
    console.error(`Failed to close scanner. Code: ${error.code}, message: ${error.message}`);
});

scan.getScannerParameter

getScannerParameter(scannerId: string): Promise<ScannerParameter[]>

获取扫描仪参数。使用Promise异步回调。必须在调用openScanner()打开扫描仪之后才能调用此方法。应用可通过此方法获取参数索引（optionIndex），用于setScannerParameter、setScanAutoOption和getScannerCurrentSetting等方法的调用。

需要权限： ohos.permission.PRINT

系统能力： SystemCapability.Print.PrintFramework

参数：

返回值：

错误码：

示例：

import { scan } from '@kit.BasicServicesKit';
import { BusinessError } from '@kit.BasicServicesKit';

let scannerId: string = 'scanner_001';
scan.getScannerParameter(scannerId).then((parameters: scan.ScannerParameter[]) => {
    console.info('get scanner parameters success: ' + JSON.stringify(parameters));
}).catch((error: BusinessError) => {
    console.error(`Failed to get scanner parameters. Code: ${error.code}, message: ${error.message}`);
});

scan.setScannerParameter

setScannerParameter(scannerId: string, optionIndex: number, value: ScannerOptionValue): Promise<void>

设置扫描仪参数。使用Promise异步回调。必须在调用openScanner()打开扫描仪之后才能调用此方法。

需要权限： ohos.permission.PRINT

系统能力： SystemCapability.Print.PrintFramework

参数：

返回值：

错误码：

示例：

import { scan } from '@kit.BasicServicesKit';
import { BusinessError } from '@kit.BasicServicesKit';

let scannerId: string = 'scanner_001';
let optionIndex: number = 1;
let value: scan.ScannerOptionValue = {
    valueType: scan.OptionValueType.SCAN_TYPE_INT,
    numValue: 100
};
scan.setScannerParameter(scannerId, optionIndex, value).then(() => {
    console.info('set scanner parameter success');
}).catch((error: BusinessError) => {
    console.error(`Failed to set scanner parameter. Code: ${error.code}, message: ${error.message}`);
});

scan.setScanAutoOption

setScanAutoOption(scannerId: string, optionIndex: number): Promise<void>

设置扫描选项为自动模式，由扫描仪自动确定该选项的取值。使用Promise异步回调。必须在调用openScanner()打开扫描仪之后才能调用此方法。

需要权限： ohos.permission.PRINT

系统能力： SystemCapability.Print.PrintFramework

参数：

返回值：

错误码：

示例：

import { scan } from '@kit.BasicServicesKit';
import { BusinessError } from '@kit.BasicServicesKit';

let scannerId: string = 'scanner_001';
let optionIndex: number = 1;
scan.setScanAutoOption(scannerId, optionIndex).then(() => {
    console.info('set scan auto option success');
}).catch((error: BusinessError) => {
    console.error(`Failed to set scan auto option. Code: ${error.code}, message: ${error.message}`);
});

scan.getScannerCurrentSetting

getScannerCurrentSetting(scannerId: string, optionIndex: number): Promise<ScannerOptionValue>

获取当前扫描仪设置。使用Promise异步回调。必须在调用openScanner()打开扫描仪之后才能调用此方法。

需要权限： ohos.permission.PRINT

系统能力： SystemCapability.Print.PrintFramework

参数：

返回值：

错误码：

示例：

import { scan } from '@kit.BasicServicesKit';
import { BusinessError } from '@kit.BasicServicesKit';

let scannerId: string = 'scanner_001';
let optionIndex: number = 1;
scan.getScannerCurrentSetting(scannerId, optionIndex).then((value: scan.ScannerOptionValue) => {
    console.info('get scanner current setting success: ' + JSON.stringify(value));
}).catch((error: BusinessError) => {
    console.error(`Failed to get scanner current setting. Code: ${error.code}, message: ${error.message}`);
});

scan.startScan

startScan(scannerId: string, batchMode: boolean): Promise<void>

开始扫描。使用Promise异步回调。必须在调用openScanner()打开扫描仪之后才能调用此方法。扫描过程中可通过getPictureScanProgress()获取扫描进度；需要取消扫描时，可调用cancelScan()。

需要权限： ohos.permission.PRINT

系统能力： SystemCapability.Print.PrintFramework

参数：

返回值：

错误码：

示例：

import { scan } from '@kit.BasicServicesKit';
import { BusinessError } from '@kit.BasicServicesKit';

let scannerId: string = 'scanner_001';
let batchMode: boolean = true;
scan.startScan(scannerId, batchMode).then(() => {
    console.info('start scan success');
}).catch((error: BusinessError) => {
    console.error(`Failed to start scan. Code: ${error.code}, message: ${error.message}`);
});

scan.cancelScan

cancelScan(scannerId: string): Promise<void>

取消扫描。使用Promise异步回调。必须在开始扫描之后才能调用此方法。

需要权限： ohos.permission.PRINT

系统能力： SystemCapability.Print.PrintFramework

参数：

返回值：

错误码：

示例：

import { scan } from '@kit.BasicServicesKit';
import { BusinessError } from '@kit.BasicServicesKit';

let scannerId: string = 'scanner_001';
scan.cancelScan(scannerId).then(() => {
    console.info('cancel scan success');
}).catch((error: BusinessError) => {
    console.error(`Failed to cancel scan. Code: ${error.code}, message: ${error.message}`);
});

scan.getPictureScanProgress

getPictureScanProgress(scannerId: string): Promise<PictureScanProgress>

获取图片扫描进度。使用Promise异步回调。必须在开始扫描之后才能调用此方法。

需要权限： ohos.permission.PRINT

系统能力： SystemCapability.Print.PrintFramework

参数：

返回值：

错误码：

示例：

import { scan } from '@kit.BasicServicesKit';
import { BusinessError } from '@kit.BasicServicesKit';

let scannerId: string = 'scanner_001';
scan.getPictureScanProgress(scannerId).then((progress: scan.PictureScanProgress) => {
    console.info('get picture scan progress success: ' + JSON.stringify(progress));
}).catch((error: BusinessError) => {
    console.error(`Failed to get picture scan progress. Code: ${error.code}, message: ${error.message}`);
});

scan.on

on(type: 'scanDeviceFound', callback: Callback<ScannerDevice>): void

注册扫描仪设备发现事件回调，当调用startScannerDiscovery发现新的扫描仪设备时会触发此事件。使用callback异步回调。

需要权限： ohos.permission.PRINT

系统能力： SystemCapability.Print.PrintFramework

参数：

错误码：

示例：

import { scan } from '@kit.BasicServicesKit';

scan.on('scanDeviceFound', (device: scan.ScannerDevice) => {
    console.info('scan device found: ' + JSON.stringify(device));
});

scan.off

off(type: 'scanDeviceFound', callback?: Callback<ScannerDevice>): void

取消注册扫描仪设备发现事件回调。

需要权限： ohos.permission.PRINT

系统能力： SystemCapability.Print.PrintFramework

参数：

错误码：

示例：

import { scan } from '@kit.BasicServicesKit';

let callback = (device: scan.ScannerDevice) => {
    console.info('scan device found: ' + JSON.stringify(device));
};
scan.on('scanDeviceFound', callback);
// 取消注册
scan.off('scanDeviceFound', callback);

scan.on

on(type: 'scanDeviceSync', callback: Callback<ScannerSyncDevice>): void

注册扫描仪设备同步事件回调，当扫描仪设备状态发生变化（如扫描仪设备ID变更或掉线）时会触发此事件，通知应用同步维护扫描仪列表。使用callback异步回调。适用于应用需要持续跟踪扫描仪设备状态变化的场景，如扫描仪重新连接时更新本地设备信息。

需要权限： ohos.permission.MANAGE_PRINT_JOB

系统能力： SystemCapability.Print.PrintFramework

参数：

错误码：

示例：

import { scan } from '@kit.BasicServicesKit';

scan.on('scanDeviceSync', (device: scan.ScannerSyncDevice) => {
    console.info('scan device sync: ' + JSON.stringify(device));
});

scan.off

off(type: 'scanDeviceSync', callback?: Callback<ScannerSyncDevice>): void

取消注册扫描仪设备同步事件回调。

需要权限： ohos.permission.MANAGE_PRINT_JOB

系统能力： SystemCapability.Print.PrintFramework

参数：

错误码：

示例：

import { scan } from '@kit.BasicServicesKit';

let callback = (device: scan.ScannerSyncDevice) => {
    console.info('scan device sync: ' + JSON.stringify(device));
};
scan.on('scanDeviceSync', callback);
// 取消注册
scan.off('scanDeviceSync', callback);