Skip to content

Commit 21338f0

Browse files
Dynamsoft-HenryDynamsoft-Henry
authored
Merge pull request #457 from dynamsoft-docs/preview
update to internal commit 41e48563
2 parents a0c9aa3 + c4e50b4 commit 21338f0

File tree

3 files changed

+197
-2
lines changed

3 files changed

+197
-2
lines changed

‎programming/javascript/user-guide/assets/scannerView1103000.png

341 KB
Loading

‎programming/javascript/user-guide/barcode-scanner-customization-v10.5.3000.md

Lines changed: 191 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,191 @@
1+
---
2+
layout: default-layout
3+
needAutoGenerateSidebar: true
4+
needGenerateH3Content: true
5+
noTitleIndex: true
6+
title: Dynamsoft Barcode Scanner JavaScript Edition Customization
7+
keywords: Documentation, Barcode Scanner, Dynamsoft Barcode Scanner JavaScript Edition, customization
8+
description: Dynamsoft Barcode Scanner customization
9+
---
10+
11+
# Customize Your BarcodeScanner
12+
13+
- [Specify the barcode format](#specify-the-barcode-format)
14+
- [Use customized template](#use-customized-template)
15+
- [Config the pre-built UIs](#config-the-pre-built-uis)
16+
- [Use BarcodeScanner in frameworks](#use-barcodescanner-in-frameworks)
17+
18+
## Specify the barcode format
19+
20+
Specifying the target barcode formats not only speeds up the recognition process but also improves accuracy. This is one of the most common customization needs. BarcodeScanner provides two ways to specify the barcode formats. For example, if your target formats are `QR_CODE` and `CODE_128`:
21+
22+
> [!NOTE]
23+
> See [all supported barcode formats](https://officecn.dynamsoft.com:808/barcode-reader/barcode-types/).
24+
25+
### Option 1: Set via BarcodeScannerConfig
26+
27+
Add the following configuration in [`BarcodeScannerConfig`]({{ site.js_api }}barcode-scanner.html#barcodescannerconfig):
28+
29+
```js
30+
const barcodeScanner = new Dynamsoft.BarcodeScanner({
31+
// ...
32+
barcodeFormats:[Dynamsoft.DBR.EnumBarcodeFormat.BF_QR_CODE , Dynamsoft.DBR.EnumBarcodeFormat.BF_CODE_128],
33+
// ...
34+
});
35+
```
36+
37+
### Option 2: Specify in a template file
38+
39+
The benefit of this approach is that the template file can be reused across different platforms or programming languages, ensuring performance consistency across scenarios. To do this, follow these steps:
40+
41+
1. Open `dist\DBR-PresetTemplates.json` in your code editor. This file contains all the preset templates related to barcode reading.
42+
43+
2. Add the `BarcodeFormatIds` to the `BarcodeReaderTaskSettingOptions` object.
44+
45+
3. Update `BarcodeFormatIds` as shown below. You can get barcode format strings [here](https://www.dynamsoft.com/capture-vision/docs/core/enums/barcode-reader/barcode-format.html).
46+
47+
<img src="./assets/updateBarcodeFormat.png" alt="description" style="display: block; margin: 0 auto; width: 70%;"/>
48+
49+
Refer to [`Use customized template`](#use-customized-template) for more details.
50+
51+
> [!IMPORTANT]
52+
> Due to the powerful customization capabilities, the number of configurable parameters in the templates is extensive and relatively complex. feel free to [contact us](https://www.dynamsoft.com/contact/) if you need help creating a custom template.
53+
54+
## Use customized template
55+
56+
In more complex scenarios—such as blurred, damaged, curved, or unevenly lit barcodes—you might need a custom template to perform specific image processing steps. BarcodeScannerConfig provides a property to load a template file, allowing you to customize the algorithm’s processing workflow.
57+
58+
> [!WARNING]
59+
> This operation will overwrite the built-in templates.
60+
61+
```js
62+
const barcodeScannerConfig = {
63+
// The path to your custom JSON template that defines the scanning process.
64+
templateFilePath:'path/to/DBR-PresetTemplates.json'
65+
};
66+
// Initialize the BarcodeScanner with the above BarcodeScannerConfig object
67+
const barcodeScanner = new Dynamsoft.BarcodeScanner(barcodeScannerConfig);
68+
```
69+
70+
## Config the Pre-built UIs
71+
72+
The built-in UI of `BarcodeScanner` is composed of `BarcodeScannerView` and `BarcodeResultView`. By default, regardless of the scanning mode, `BarcodeScanner` only displays the `CameraView` to ensure the essential workflow can proceed. Other UI components can be shown or hidden manually through `barcodeScannerConfig`. Let's break down these two Views:
73+
74+
### BarcodeScannerView
75+
76+
The `BarcodeScannerView` is composed of the following UI elements:
77+
78+
<img src="./assets/scannerView.png" alt="description" style="display: block; margin: 0 auto; width: 35%;"/>
79+
80+
1. **Camera View**: The Camera View is the camera viewfinder UI component within the `BarcodeScannerView`. This viewfinder occupies the majority of the space within the `BarcodeScannerView` to give the user a clear view and precise control of the image being scanned.
81+
82+
2. **Load Image Button**: This button allows the user to scan a file of a barcode-containing image from the device's local storage. You can decide whether to show or hide the button by [showUploadImageButton]({{ site.js_api }}barcode-scanner.html#barcodescannerconfig) property.
83+
84+
3. **Close Scanner Button**: This button closes the Barcode Scanner, return a [`BarcodeScanResult`]({{ site.js_api }}barcode-scanner.html#barcodescanresult) object and destroys the **`BarcodeScanner`** instance. You can decide whether to show or hide the button by [showCloseButton]({{ site.js_api }}barcode-scanner.html#scannerviewconfig) property.
85+
86+
### BarcodeResultView (MULTI_UNIQUE mode only)
87+
88+
Here is a quick breakdown of the `MULTI_UNIQUE` UI elements of the `BarcodeResultView` view:
89+
90+
<img src="./assets/resultView.png" alt="description" style="display: block; margin: 0 auto; width: 35%;"/>
91+
92+
1. **Barcode Results List**: The list used to display the decoding results.The list is updated whenever a new barcode is successfully decoded, or the same code is detected again after a specific [duplicateForgetTime]({{ site.js_api }}barcode-scanner.html#barcodescannerconfig).
93+
94+
2. **Clear Button**: The button on the bottom left, which clears all elements of the current `Barcode Results List`. You can change the style of the Button with [BarcodeResultViewToolbarButtonsConfig]({{ site.js_api }}barcode-scanner.html#barcoderesultviewtoolbarbuttonsconfig).
95+
96+
3. **Done Button**: The button on the bottom right, which closes the Barcode Scanner, return a [`BarcodeScanResult`]({{ site.js_api }}barcode-scanner.html#barcodescanresult) object that includes all unique barcodes and destroys the **`BarcodeScanner`** instance. You can change the style of the Button with [BarcodeResultViewToolbarButtonsConfig]({{ site.js_api }}barcode-scanner.html#barcoderesultviewtoolbarbuttonsconfig).
97+
98+
### Manually modify the UI file
99+
100+
Another way to fully customize the UI is by directly editing the `.xml` file. In the `dist/` directory, you'll find the `barcode-scanner.ui.xml` file, which is the default UI for the `BarcodeScanner`. You can make a copy of it and apply your own modifications. For example, to double the size of the `UploadImage` icon, you can edit the file like this:
101+
102+
```xml
103+
<template>
104+
<!-- ... -->
105+
<!-- <svg id="upload-image" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="24" height="24" viewBox="0 0 26 26"> -->
106+
<svg id="upload-image" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="48" height="48" viewBox="0 0 26 26">
107+
<!-- ... -->
108+
</template>
109+
```
110+
111+
Once you've made your changes, just set the new `uiPath` in the configuration. If everything is configured correctly, the updated UI will appear the next time you refresh the page.
112+
113+
```js
114+
const barcodeScanner = new Dynamsoft.BarcodeScanner({
115+
//...
116+
uiPath: "path/to/new-barcode-scanner.ui.xml?v=<your-update-version>",
117+
//...
118+
});
119+
```
120+
121+
## Use BarcodeScanner in frameworks
122+
123+
Integrating `BarcodeScanner` into frameworks like `Angular`, `React`, and `Vue` is a little different compared to native usage. You can also refer to [the ready-made samples for popular frameworks](https://github.com/Dynamsoft/barcode-reader-javascript-samples/tree/main/barcode-scanner-api-samples/scan-single-barcode) directly without reading this guide.
124+
125+
### Installation
126+
127+
Open the terminal from your project root and install **Dynamsoft Barcode Reader SDK** with the following command:
128+
129+
```sh
130+
npm install dynamsoft-barcode-reader-bundle@11.0.3000 -E
131+
```
132+
133+
### Component for video decoding
134+
135+
Here’s how to quickly set up a video barcode scanner using the `BarcodeScanner` class:
136+
137+
```ts
138+
const config = {
139+
license: "YOUR-LICENSE-KEY", // Replace with your license key
140+
}
141+
const barcodeScanner = new BarcodeScanner(config);
142+
barcodeScanner.launch().then((result)=>{
143+
console.log(result); // Handle the decoding result here
144+
});
145+
```
146+
147+
#### Define the resource paths
148+
149+
To ensure stability, especially in environments with limited internet access, it’s a good idea to **host all required resources locally** (e.g., under the dist/ folder).
150+
Below is an example using the official CDN — feel free to replace it with your own path:
151+
152+
```ts
153+
const config = {
154+
license: "YOUR-LICENSE-KEY",
155+
// Configures the paths where the .wasm files and other necessary resources for modules are located.
156+
engineResourcePaths: {
157+
// Using jsDelivr CDN as an example
158+
rootDirectory: "https://cdn.jsdelivr.net/npm/dynamsoft-barcode-reader-bundle@11.0.3000/dist/",
159+
},
160+
// Path to the UI (.xml template file).
161+
uiPath: "https://cdn.jsdelivr.net/npm/dynamsoft-barcode-reader-bundle@11.0.3000/dist/barcode-scanner.ui.xml",
162+
};
163+
```
164+
165+
#### Set up the video container
166+
167+
Specify the container where the scanner UI should be rendered:
168+
169+
```ts
170+
const config = {
171+
container: ".barcode-scanner-view", // CSS selector for the scanner container
172+
};
173+
```
174+
175+
Make sure your HTML includes the corresponding element:
176+
177+
```html
178+
<div class="barcode-scanner-view"></div>
179+
```
180+
181+
The above steps cover the key considerations when using the `BarcodeScanner` component within a modern JavaScript framework. To recap:
182+
183+
- Install the SDK with an exact version to avoid compatibility issues.
184+
185+
- Define resource paths explicitly — either via CDN or local dist/ folder — to ensure consistent loading behavior.
186+
187+
- Configure and launch the scanner using the provided component API.
188+
189+
- Set up a container element to properly display the scanner UI.
190+
191+
By following these best practices, you'll ensure a stable and reliable integration of `BarcodeScanner` into your application.

‎programming/javascript/user-guide/barcode-scanner-customization.md

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -69,20 +69,24 @@ In more complex scenarios—such as blurred, damaged, curved, or unevenly lit ba
6969

7070
## Config the Pre-built UIs
7171

72-
The built-in UI of `BarcodeScanner` is composed of `BarcodeScannerView` and `BarcodeResultView`. By default, regardless of the scanning mode, `BarcodeScanner` only displays the `CameraView` to ensure the essential workflow can proceed. Other UI components can be shown or hidden manually through `barcodeScannerConfig`. Let's break down these two Views:
72+
The built-in UI of `BarcodeScanner` is composed of `BarcodeScannerView` and `BarcodeResultView`. In `MULTI_UNIQUE` mode, `BarcodeResultView` is shown by default to ensure the essential workflow can proceed. Other UI components can be shown or hidden manually through `barcodeScannerConfig`. Let's break down these two Views:
7373

7474
### BarcodeScannerView
7575

7676
The `BarcodeScannerView` is composed of the following UI elements:
7777

78-
<img src="./assets/scannerView.png" alt="description" style="display: block; margin: 0 auto; width: 35%;"/>
78+
<img src="./assets/scannerView1103000.png" alt="description" style="display: block; margin: 0 auto; width: 35%;"/>
7979

8080
1. **Camera View**: The Camera View is the camera viewfinder UI component within the `BarcodeScannerView`. This viewfinder occupies the majority of the space within the `BarcodeScannerView` to give the user a clear view and precise control of the image being scanned.
8181

8282
2. **Load Image Button**: This button allows the user to scan a file of a barcode-containing image from the device's local storage. You can decide whether to show or hide the button by [showUploadImageButton]({{ site.js_api }}barcode-scanner.html#barcodescannerconfig) property.
8383

8484
3. **Close Scanner Button**: This button closes the Barcode Scanner, return a [`BarcodeScanResult`]({{ site.js_api }}barcode-scanner.html#barcodescanresult) object and destroys the **`BarcodeScanner`** instance. You can decide whether to show or hide the button by [showCloseButton]({{ site.js_api }}barcode-scanner.html#scannerviewconfig) property.
8585

86+
4. **Flash Button**: This button allows the user to toggle the camera's torch. You can decide whether to show or hide the button by [showFlashButton]({{ site.js_api }}barcode-scanner.html#barcodescannerconfig) property.
87+
88+
5. **Camera Switch Button**: This button allows the users to change between cameras. You can specify the mode and visibility of the camera switch control by [cameraSwitchControl]({{ site.js_api }}barcode-scanner.html#scannerviewconfig) property.
89+
8690
### BarcodeResultView (MULTI_UNIQUE mode only)
8791

8892
Here is a quick breakdown of the `MULTI_UNIQUE` UI elements of the `BarcodeResultView` view:

0 commit comments

Comments
 (0)