Barcode Scanner JavaScript Edition API Reference
BarcodeScanner is a configurable barcode scanning module featuring a pre-built UI that supports both live camera and still image decoding. Designed for effortless integration into web applications, it offers a ready-to-use, customizable interface to streamline barcode scanning implementation.
Constructor
BarcodeScanner
new BarcodeScanner(config?: BarcodeScannerConfig)
Parameters
config
(optional): Assigns the license and configures the different settings of the BarcodeScanner
, including the container, supported barcode formats, and more. This config object is of type BarcodeScannerConfig.
Code Snippet
const barcodeScanner = new Dynamsoft.BarcodeScanner({
license: "YOUR_LICENSE_KEY_HERE",
scannerViewConfig: {
// container: "#camera-view-container",
// showCloseButton: true,
},
// showUploadImageButton: true,
// scanMode: Dynamsoft.EnumScanMode.SM_MULTI_UNIQUE,
// showResultView: true,
});
Methods
launch()
Launches the scanner and optionally renders the scanning UI based on scanMode and container configuration.
launch(): Promise<BarcodeScanResult>
Returns
A promise that resolves to a BarcodeScanResult
.
Code Snippet
(async () => {
// Launch the scanner and wait for the result
try {
const result = await barcodeScanner.launch();
console.log(result); // print the BarcodeScanResult to the console
} catch (error){
console.error(error);
}
})();
dispose()
Disposes the scanner instance and cleans up all related resources.
dispose(): void
Code Snippet
barcodeScanner.dispose();
console.log("Scanner resources released.");
decode()
Decodes a barcode from an image, URL, or canvas element.
decode(imageOrFile: Blob | string | DSImageData | HTMLImageElement | HTMLVideoElement | HTMLCanvasElement,templateName?: string): Promise<CapturedResult>
Parameters
imageOrFile
: The input image source.
templateName
(optional): The name of the CaptureVisionTemplate
to be used.
Returns
A promise that resolves to a CapturedResult
.
Code Snippet
const imageUrl = 'https://example.com/image.png';
const results = barcodeScanner.decode(imageUrl);
//... do something with the results
Interfaces
BarcodeScannerConfig
Configuration options for initializing a BarcodeScanner
.
interface BarcodeScannerConfig {
license?: string;
scanMode?: EnumScanMode;
templateFilePath?: string;
utilizedTemplateNames?: UtilizedTemplateNames;
engineResourcePaths?: EngineResourcePaths;
uiPath?: string;
barcodeFormats?: EnumBarcodeFormat | Array<EnumBarcodeFormat>;
duplicateForgetTime?: number;
removePoweredByMessage?: boolean;
container?: HTMLElement | string | undefined;
onUniqueBarcodeScanned?: (result: BarcodeResultItem) => void | Promise<void>;
showResultView?: boolean;
showUploadImageButton?: boolean;
scannerViewConfig?: ScannerViewConfig;
resultViewConfig?: ResultViewConfig;
}
Property | Type | Default Value | Description |
---|---|---|---|
license | string | N/A | The to activate the barcode scanner. |
scanMode (optional) | EnumScanMode | SM_SINGLE | Defines the scan mode of the BarcodeScanner |
templateFilePath (optional) | string | N/A | Path to a CaptureVisionTemplate file used for barcode reading. |
utilizedTemplateNames (optional) | UtilizedTemplateNames | {"single": "ReadSingleBarcode", "multi_unique": "ReadBarcodes_SpeedFirst", "image": "ReadBarcodes_ReadRateFirst"} | Defines template names mapped to scanning modes. |
engineResourcePaths (optional) | EngineResourcePaths | N/A | Paths to engine resources like WASM or workers. See EngineResourcePaths for details. |
uiPath (optional) | string | N/A | Path to the custom UI (.xml template file) for the ScannerView. |
barcodeFormats (optional) | EnumBarcodeFormat | Array<EnumBarcodeFormat> | N/A | EnumBarcodeFormat or an array of EnumBarcodeFormat specifying the formats to recognize. |
duplicateForgetTime (optional) | number | 3000 | Time interval in milliseconds before duplicate barcodes can be reported again. |
removePoweredByMessage (optional) | boolean | false | Whether to remove the “powered by” message. |
container (optional) | HTMLElement | string | N/A | A container element or selector for rendering the scanner and/or result view. |
onUniqueBarcodeScanned | void | Promise<void> | N/A | A callback triggered when a unique barcode is scanned (only valid in SM_MULTI_UNIQUE). |
showResultView (optional) | boolean | false | Whether to display a result view in SM_MULTI_UNIQUE mode. |
showUploadImageButton (optional) | boolean | false | Determines the visibility of the “uploadImage” button that allows the user to upload an image for decoding. |
scannerViewConfig (optional) | ScannerViewConfig | see ScannerViewConfig | Configuration for the scanner view. |
resultViewConfig (optional) | ResultViewConfig | see ResultViewConfig | Configuration for the result view (only valid in SM_MULTI_UNIQUE). |
Code Snippet
<body>
<div id="camera-view-container" style="width: 100%; height: 80vh"></div>
<script>
const barcodeScannerConfig = {
license: "YOUR_LICENSE_KEY_HERE",
// Defines scan behavior:
// - SM_MULTI_UNIQUE: Keeps scanning and continuously collecting unique decoded barcode results.
// - SM_SINGLE: Scans once a result is found.
scanMode: Dynamsoft.EnumScanMode.SM_MULTI_UNIQUE,
// The path to your custom JSON template that defines the scanning process.
templateFilePath:'./DBR-PresetTemplates.json',
// engineResourcePaths typically is only assigned when using a framework like React/Angular/Vue where the resources are not in the same location as the script reference.
engineResourcePaths: {rootDirectory:"https://cdn.jsdelivr.net/npm/[email protected]/dist"},
barcodeFormats: [Dynamsoft.DBR.EnumBarcodeFormat.BF_QR_CODE , Dynamsoft.DBR.EnumBarcodeFormat.BF_CODE_128],
removePoweredByMessage: true,
duplicateForgetTime: 3000,
showUploadImageButton: true,
// The container for rendering the scanner and/or result view. Note that ResultView is only valid for SM_MULTI_UNIQUE mode. If not specified, a full-viewport default UI will be created.
container: "#camera-view-container",
onUniqueBarcodeScanned: (result) => {
// do something with the result
},
showResultView: true,
scannerViewConfig: {
// the ResultViewConfig goes in here - see ResultViewConfig section
},
resultViewConfig: {
// the ResultViewConfig goes in here - see ResultViewConfig section
}
};
// Initialize the BarcodeScanner with the above BarcodeScannerConfig object
const barcodeScanner = new Dynamsoft.BarcodeScanner(barcodeScannerConfig);
</script>
</body>
ScannerViewConfig
The ScannerViewConfig is used to configure the UI elements of the BarcodeScannerView. If the ScannerViewConfig is not assigned, then the library will use the default BarcodeScannerView.
interface ScannerViewConfig {
container?: HTMLElement | string | undefined;
showCloseButton?: boolean;
}
Property | Type | Default Value | Description |
---|---|---|---|
container (optional) | HTMLElement | string | undefined | N/A | A dedicated container for the ScannerView (video stream). |
showCloseButton (optional) | boolean | false | Determines the visibility of the “closeButton” button that allows the user to close the ScannerView. |
Code Snippet
const barcodeScannerViewConfig = {
showCloseButton: true // display the close button that shows up at the top right of the view
};
const barcodeScannerConfig = {
license: "YOUR_LICENSE_KEY_HERE",
scannerViewConfig: barcodeScannerViewConfig
};
ResultViewConfig
The ResultViewConfig is used to configure the UI elements of the BarcodeResultView. If the ResultViewConfig is not assigned, then the library will use the default BarcodeResultView.
interface ResultViewConfig {
container?: HTMLElement | string | undefined;
toolbarButtonsConfig?: BarcodeResultViewToolbarButtonsConfig;
}
Property | Type | Default Value | Description |
---|---|---|---|
container (optional) | HTMLElement | string | undefined | N/A | A dedicated container for the ResultView. |
toolbarButtonsConfig (optional) | BarcodeResultViewToolbarButtonsConfig | see BarcodeResultViewToolbarButtonsConfig | Configures the main bottom toolbar of the ResultView. |
Code Snippet
const barcodeResultViewConfig = {
toolbarButtonsConfig: {
clear: {
label: "Clear-all", // Changes the text label of the clear button to "Clear-all"; string is "Clear" by default
isHidden: true // Hides the clear button; false by default
},
done: {
label: "Return Home", // Changes the text label of the done button to "Return Home"; string is "Done" by default
isHidden: false // Hides the done button; false by default
}
},
}
const barcodeScannerConfig = {
license: "YOUR_LICENSE_KEY_HERE",
resultViewConfig: barcodeResultViewConfig
};
BarcodeResultViewToolbarButtonsConfig
The BarcodeResultViewToolbarButtonsConfig is used to configure the buttons of the toolbar in the BarcodeResultView.
interface BarcodeResultViewToolbarButtonsConfig {
clear?: ToolbarButtonConfig;
done?: ToolbarButtonConfig;
}
Property | Type | Description |
---|---|---|
clear (optional) | ToolbarButtonConfig | Configuration for the clear button of the toolbar. |
done (optional) | ToolbarButtonConfig | Configuration for the done button of the toolbar. |
Code Snippet
// Default value as shown below
const barcodeScannerButtonConfig = {
clear: {
label: "Clear",
isHidden: false
},
done: {
label: "Done",
isHidden: false
}
};
const barcodeResultViewConfig = {
toolbarButtonsConfig: barcodeScannerButtonConfig
};
ToolbarButtonConfig
The interface used to configure the properties of the toolbar button.
interface ToolbarButtonConfig {
label: string;
className?: string;
isHidden?: boolean;
}
Property | Type | Description |
---|---|---|
label | string | The text label of the button. |
className | string | Assigns a custom class to the button (usually to apply custom styling). |
isHidden | boolean | Hides/Shows the button in the toolbar. |
BarcodeScanResult
The BarcodeScanResult is the most basic interface that is used to represent the full barcode scan result object. It comes with a result status, the original and cropped image result, and the detailed info of the decoded barcode(s).
interface BarcodeScanResult {
status: ResultStatus;
barcodeResults?: BarcodeResultItem[];
originalImageResult?: DSImageData;
barcodeImage?: DSImageData;
}
Property | Type | Description |
---|---|---|
status (optional) | ResultStatus | The status of the barcode scanning, which can be success, cancelled, or failed (indicating that something has gone wrong during the scanning process). |
originalImageResult (optional) | DSImageData | A DSImageData object that represents the original image of the successfully decoded barcode. |
barcodeResults (optional) | Array<BarcodeResultItem> | An array of BarcodeResultItem Represents the decoded barcode(s). |
Code Snippet
(async () => {
// Launch the scanner and wait for the result
const result = await barcodeScanner.launch();
console.log(result.status.message); // prints the result status message to the console
console.log(result.status.code); // prints the result status code to the console
console.log(result.barcodeResults); // prints an array containing all the decoded barcode results to the console. Note that in SM_SINGLE mode, the length of this array is 1.
})();
UtilizedTemplateNames
An object that defines the names of templates utilized by the BarcodeScanner for different scanning modes.
interface UtilizedTemplateNames {
single: string;
multi_unique: string;
image: string;
}
Property | Type | Description |
---|---|---|
single | string | Template name used for single barcode scanning mode. |
multi_unique | string | Template name used for scanning multiple unique barcodes. |
image | string | Template name used when barcode scanning is based on a provided image input. |
Code Snippet
const barcodeScannerConfig = {
//..
utilizedTemplateNames:{
single: `ReadSingleBarcode`,
multi_unique: `ReadBarcodes_SpeedFirst`,
image: `ReadBarcodes_ReadRateFirst`,
}
//..
}
ResultStatus
ResultStatus is used to represent the status of the barcode scanning result. This status can be success, cancelled if the user closes the scanner during scanning, or failed if something went wrong during the scanning process. The code of the result status is a EnumResultStatus
.
type ResultStatus = {
code: EnumResultStatus;
message: string;
}
Enums
EnumScanMode
enum EnumScanMode {
SM_SINGLE = 0,
SM_MULTI_UNIQUE = 1
}
EnumResultStatus
enum EnumResultStatus {
RS_SUCCESS = 0,
RS_CANCELLED = 1,
RS_FAILED = 2
}