From c936cd3fcaec94a160e88955c620320d6ce4e7ab Mon Sep 17 00:00:00 2001 From: Keillion-Dynamsoft Date: Mon, 27 Jul 2026 14:21:14 +0800 Subject: [PATCH 1/5] feat: customize dce5 UI definition --- programming/features/ui-customization-js.md | 380 +++++++++++++++++++- 1 file changed, 376 insertions(+), 4 deletions(-) diff --git a/programming/features/ui-customization-js.md b/programming/features/ui-customization-js.md index 7e4ae9f1..768fe1e1 100644 --- a/programming/features/ui-customization-js.md +++ b/programming/features/ui-customization-js.md @@ -10,21 +10,30 @@ noTitleIndex: true # Customize the UI -## Use the built-in UI +The official UI is defined in files that use the `.xml` extension but actually contain HTML; the `.xml` extension is used to prevent hot-reloading mechanisms—such as those in Live Server, Five Server, or UI frameworks—from overwriting the file. +In reality, you can use any file extension, provided the browser can correctly retrieve the file's text content. + +You can choose from [legacy UI definition format](#legacy-ui-definition-format) or [new UI definition format](#new-ui-definition-format). + +## Legacy UI Definition Format + +All versions of Dynamsoft Barcode Reader JS SDK 11 and Dynamsoft Capture Vision JS SDK 3 support the legacy UI definition format. However, the details of the default UI definition files vary slightly between minor versions and may not be fully compatible; please base any modifications on the UI definition file specific to the version you are using. The legacy definition format supports HTML and CSS. + +### Use the built-in UI The pre-defined UI provided by Dynamsoft Barcode Reader can be found at [`dce.ui.xml`](https://cdn.jsdelivr.net/npm/dynamsoft-barcode-reader-bundle@latest/dist/ui/dce.ui.xml). The main UI elements in this file are prefixed with `dce-` and they are dynamically bound to functions when the application initiates. -## Modify the UI dynamically +### Modify the UI dynamically To customize the UI, call `cameraView.getUIElement()` to access the `HTMLElement` that contains all UI components. Before calling `cameraEnhancer.open()`, you can modify the UI by editing CSS, adding or removing elements, or restructuring the HTML. After `cameraEnhancer.open()`, UI adjustments are still possible via JavaScript. However, handle elements with class names prefixed with `dce-` carefully, as they may be tied to specific internal logic. -## Define the UI in a separate HTML +### Define the UI in a separate HTML For less dynamic but more structured customization, create a copy of `dce.ui.xml`, modify it as needed, and store it in your project. Use this customized UI with `Dynamsoft.DCE.CameraView.createInstance('PATH-TO/xxxx.ui.xml')`. -## Integrate HTML into Your Project +### Integrate HTML into Your Project Alternatively, `CameraView.createInstance()` accepts an `HTMLElement` directly. This allows you to build and manage the UI within your webpage. For example, set the UI using `CameraView.createInstance(document.getElementById('my-custom-ui'))`. @@ -87,3 +96,366 @@ Next, add the camera and resolution list. If the classes match the default ones ``` > Ensure the selected resolution is supported by the camera. If not, the closest supported resolution will be used. The `dce-opt-gotResolution` class shows the **actual resolution**. + +## New UI Definition Format + +Starting with Dynamsoft Barcode Reader JS SDK 11.4.2000 and Dynamsoft Capture Vision JS SDK 3.4.2000, we have introduced support for a new UI definition format. This format allows for the inclusion of ` +``` + +The first line, `const camera = document.currentScript.currentDMCamera;`, allows you to access the `camera` object (an instance of `CameraEnhancer`). If you wish to access other objects—such as an instance of `CaptureVisionRouter`—you can assign `camera.exportToUI.cvRouter` within your business logic, then get it back in UI definition. + +```diff + // in business logic + + import { CaptureVisionRouter, CameraEnhancer } from 'dynamsoft-barcode-reader-bundle'; + /* other logic */ + const cvRouter = await CaptureVisionRouter.createInstance(); + const camera = await CameraEnhancer.createInstance('url/to/my/dce.ui.v5.xml'); ++ camera.exportToUI = { cvRouter }; + cameraContainer.append(camera.getUIElement()); + cvRouter.setInput(camera); +``` + +```diff + // in ui.xml + + (()=>{ + const camera = document.currentScript.currentDMCamera; ++ const cvRouter = camera.exportToUI.cvRouter; + /* other logic */ + })(); +``` + +Next, let's select a few of these optional elements and customize their interaction effects: + +### Enable Beep and Vibrate + +When a barcode is successfully decoded, you may want to trigger a beep or vibration as a notification. + +Buttons for "beep" and "vibrate" are already built into the UI definition; make them visible. + +```diff + // in ui.xml + + ... +-