@lilregie/svelte-scanner
v0.5.2
Published
Svelte compoonent for Barcode & QR code scanning
Downloads
884
Readme
Modern Svelte QR Scanner
This is a work-in-progress component library to enable QR-code scanning.
Origin
This is based on instascan
, and is designed as a more batteries included version of QRScanner. It has the source of instascan
and fsm-as-promised
bundled inside, as they both have modifications to work with Svelte.
Barcode Scanning Engine
This library tries to use the Barcode Detection API for native performance, but the support is lack-luster to say the least (only really stabilized on android phones). So we also load a backup library, Zxing
, which is a WASM implementation of the QR-code scanning algorithm. ZXing is also a bit slower than the native API, but it's a lot more likely to be supported.
Install
Just open your project and use the command line to install:
yarn add -D @lilregie/svelte-scanner # if you are using yarn
npm install --save-dev @lilregie/svelte-scanner # if you are using npm
Usage
Assuming you have a SvelteKit app up and running, just paste in the following example
<script lang="ts">
import QR from "@lilregie/svelte-scanner";
let previewWidth;
let mediaErrorMessage = "";
function onQRScan(event: CustomEvent) {
alert(event.detail.qrContent);
}
</script>
<div class="qr-container">
<div class="qr-wrapper" bind:clientWidth={w}>
<QR
on:scan={onQRScan}
bind:mediaErrorMessage
>
<div slot="loading" class="loading">
<span>Loading Animation, but text</span>
</div>
<p slot="failedToInitialize" class="failed-to-initialize">
Failed to initialize camera.<br>
Error: {mediaErrorMessage}
</p>
</QR>
</div>
</div>
API Reference
Slots
| Slot Name | Description | |--------------------|---------------------------------------------------| | loading | Displayed while the cameras are initializing. | | failedToInitialize | Displayed when the current camera fails to start. |
Props (Options)
| Prop | Type | Default | Read-only | Description | |----------------------|---------|---------|-----------|--------------------------------------------------------------------------------------------------------------------------------------------------------------| | scannerInitialized | boolean | false | x | Whether the QR code scanner has loaded yet. | | backgroundScan | boolean | false | | Whether to actively scan when the tab is not active. When false, this reduces CPU usage when the tab is not active. | | refractoryPeriod | number | 5000 | | The period, in milliseconds, before the same QR code will be recognized in succession. Default 5000 (5 seconds). | | scanPeriod | number | 1 | | The period, in rendered frames, between scans. A lower scan period increases CPU usage but makes scan response faster. Default 1 (i.e. analyze every frame). | | mediaErrorMessage | string | "" | x | Human readable error message, updates when there is a new error. Useful displayed in the failedToInitialize slot. | | smallModalXThreshold | number | 400 | | The width threshold to move the camera selection from a traditional center of screen modal, to being pined to the top. |
Events
| Event ID | Description | Data Structure | |----------|------------------------------------|--------------------| | scan | Emitted when a QR code is scanned. | {"qrContent": "x"} |
Developing Library
Once you've created a project and installed dependencies with yarn
, start a development server:
yarn dev
# or start the server and open the app in a new browser tab
yarn dev -- --open
Building
To create a production version of the library, simply run the package
script:
yarn package
Known Errors
- svelte-select not being included
For some reason, sometimes you might have to install
svelte-select
manually with a fresh project.
Fix:
yarn add -D svelte-select # if you are using yarn
npm install --save-dev svelte-select # if you are using npm
- Library's requiring bundling When using SvelteKit, you must include some of the older library's in the optimizeDeps option.
Fix: Add them to your svelte.config.js
.
const config = {
…,
kit: {
…,
vite: {
…,
optimizeDeps: {
include: [
"events",
"uuid",
"visibilityjs",
"stampit",
"lodash",
]
},
}
},
};