Migrate from 1.x

MDS 2.0 completely breaks the API from v1.x. It replaces the three views of 1.x with three screens (capture, rectify, and edit), the configuration with one set of settings, and launch() with scan(). Below are various comparisons and migrations guides.

The Package

1.x	2.0
The package dynamsoft-document-scanner	The package @dynamsoft/document-scanner
dist/dds.bundle.js, for a <script> tag	dist/document-scanner.iife.js, which includes both engines. The class is still Dynamsoft.DocumentScanner.
dist/dds.bundle.esm.js	dist/document-scanner.mjs, the main entry point of the package
require() of the package, through its CommonJS export	None. 2.0 is an ES module only. Use import, or the script build.
document-scanner.ui.xml, fetched when the scan starts	Built into the package. To change the capture screen, copy the <template> of an area from dist/defaults/capture-layout.xml into your page, and pass it as phases.capture.layout.header or .footer. The rectify and edit screens have layouts too, which 1.x did not have.

The Dependencies

Package	1.x	2.0
dynamsoft-capture-vision-bundle	~3.2.5000	~3.6.5000, a peer dependency
dynamsoft-document-viewer	None	~5.0.0, a peer dependency
dynamsoft-capture-vision-data	1.1.0	None
image-filter-js	^1.0.1	None

The Methods

1.x	2.0
initialize()	preload(). It is optional, because scan() loads the engines too, and it resolves with nothing.
launch()	scan(). It resolves when the session ends.
launch(file)	scan(file)
stopContinuousScanning()	finish(), which ends the session and keeps the pages. 1.x stopped only after the current page.
dispose()	dispose(). 1.x released everything after each launch(). 2.0 keeps the engines loaded between scans, and dispose() is final: to scan again, construct a new document scanner.
None	New: cancel(), reset(), on(), getSettings(), and getDdvViewer()

The Result

launch() resolved with one page. scan() resolves with a ScanResult, which holds every page:

1.x	2.0
result.status.code, with EnumResultStatus.RS_SUCCESS, RS_CANCELLED, or RS_FAILED	result.status, with "success", "cancelled", or "failed"
result.status.message	result.error.message, with result.error.kind for the cause
result.correctedImageResult	processed of each page in result.pages
result.originalImageResult	original of each page
result.detectedQuadrilateral	boundary of each page
None	result.output, the PDF, TIFF, or images that output asks for

The images of a page work differently. In 1.x, correctedImageResult.toCanvas() was synchronous, and in 2.0, toCanvas() and toBlob() return promises. processed stops working after cancel(), reset(), or dispose(), so read it before then.

The Settings

1.x	2.0
scannerViewConfig	phases.capture
correctionViewConfig	phases.rectify
resultViewConfig	phases.edit
container and scannerViewConfig.container	container. The capture screen has no container of its own.
correctionViewConfig.container	phases.rectify.container
resultViewConfig.container	phases.edit.container
themeColor	theme
stringConfig	strings
showCorrectionView: false	phases.rectify: false. To skip the rectify screen only after a capture, and keep it from the edit screen, set phases.rectify.modes.afterCapture: false. 1.x had no such setting.
showResultView: false	phases.edit: false
enableSmartCaptureMode and enableAutoCropMode	phases.capture.autoCapture. The auto-crop mode of 1.x also skipped the correction view for its own captures. The nearest match adds phases.rectify.modes.afterCapture: false, which skips the rectify screen for every new page, from the shutter and from imports too.
enableBoundsDetectionMode	None. 2.0 always outlines the document.
minVerifiedFramesForAutoCapture	phases.capture.minStableFrames
showSubfooter: false	phases.capture.buttons.autoCapture.hidden, which hides the one auto-capture toggle
enableContinuousScanning	maxPages. false becomes 1, and true becomes "unlimited".
engineResourcePaths	resources.captureVision, with the same shape. Document Viewer's files have their own setting, resources.documentViewer.
cameraEnhancerUIPath	phases.capture.layout, one template for each area
onDocumentScanned	on("documentChange"), with the change type "pagesAdded". 1.x waited for the callback before the next scan, but 2.0 does not wait for the listener. "pagesAdded" also fires when undo or redo brings pages back.
onThumbnailClicked	phases.capture.buttons.thumbnail.onClick. Its event carries no page, and the thumbnail then opens the edit screen, or finishes the scan. To keep the 1.x behavior, call event.preventDefault().
resultViewConfig.onDone	on("done"). The document scanner waits for the listener before scan() resolves.
resultViewConfig.onUpload	on("done"), with your own upload.
correctionViewConfig.onFinish	on("documentChange"). After a capture, the page arrives as "pagesAdded". From the edit screen, a new boundary arrives as "pageEdited". To act on the press itself, use phases.rectify.modes.afterCapture.buttons.apply.onClick.
toolbarButtonsConfig, a button's label	strings, by screen and button
toolbarButtonsConfig, a button's isHidden	hidden in the buttons of each screen. 2.0 also adds onClick, which runs before the default action. To replace that action, call event.preventDefault(). See Buttons.
toolbarButtonsConfig, a button's icon and className	Your own <img>, <svg>, and classes inside the button of a screen layout. A data-mds-icon attribute places only a built-in icon.
templateFilePath, utilizedTemplateNames, enableFrameVerification, scanRegion, and showPoweredByDynamsoft	None. 2.0 has no such settings.

The Buttons

1.x	2.0
Correction view: retake, fullImage, detectBorders, apply	Rectify screen: retake, fullImage, detectBoundary, apply, and also cancel and undo (RectifyScreenButton)
Result view: correct	Edit screen: rectify (EditScreenButton)
Result view: retake	Edit screen: addPage, which opens the capture screen for more pages
Result view: rotate, filter, done	Edit screen: rotate, filter, done
Result view: share and upload	None. Ask for a file with output, and share or upload it in your on("done") listener.

Behavior That Changed

• Unknown settings throw. The constructor throws a TypeError that names any unknown key or wrong value. Thus a 1.x settings object passed unchanged fails at once, which shows each setting to move.
• Auto-capture is on by default. In 1.x, smart capture and auto-crop were off by default. For the 1.x behavior, set phases.capture.autoCapture: false.
• Continuous scanning is the default. 1.x scanned one page unless enableContinuousScanning was true. 2.0 scans until the user finishes. For one page, set maxPages: 1, and call reset() before each scan.
• Pages stay between scans. 1.x started each launch() empty. In 2.0, the pages of a successful or failed scan stay for the next scan(), and count toward maxPages. To start each scan empty, call reset() before it.
• The capture screen's markup is no longer fetched. It comes with the package, so cameraEnhancerUIPath has no place to point.

As in 1.x, scan() resolves with status: "failed" and the error when the scan fails. It rejects only when it cannot start a session, or when the file you pass is not a Blob.