Javascript-QR-Code-Scanner basierend auf Cosmo Wolfes Javascript-Port der ZXing-Bibliothek von Google.
In dieser Bibliothek wurden gegenüber dem ursprünglichen Port mehrere Verbesserungen vorgenommen:
BarcodeDetector verfügbar ist, werden nur ~15,3 kB (~5,6 kB gzipped) geladen.Laut unserem Benchmarking ist die Erkennungsrate der Scanner-Engine dieses Projekts etwa zwei- bis dreimal (und bis zu achtmal) so hoch wie die der beliebtesten Javascript-QR-Scannerbibliothek LazarSoft/jsqrcode. Auch die andere Bibliothek liest den Inhalt von QR-Codes häufig falsch, während bei diesem Projekt im Benchmarking keine Fehlinterpretationen auftraten.
Die Bibliothek unterstützt das Scannen eines kontinuierlichen Videostreams von einer Webcam sowie das Scannen einzelner Bilder.
Die Entwicklung dieser Bibliothek wird von Nimiq gesponsert, der weltweit ersten browserbasierten Blockchain.
Siehe https://nimiq.github.io/qr-scanner/demo/
Zur Installation über npm:
npm install --save qr-scannerZur Installation über Garn:
yarn add qr-scanner Oder kopieren Sie einfach qr-scanner.min.js und qr-scanner-worker.min.js in Ihr Projekt.
Der QR-Scanner besteht aus zwei Hauptdateien. qr-scanner.min.js ist die Haupt-API-Datei, die das Worker-Skript qr-scanner-worker.min.js nur bei Bedarf über einen dynamischen Import lädt. Wenn Sie keinen Bundler wie Rollup oder Webpack verwenden, der dynamische Importe automatisch verarbeitet, müssen Sie möglicherweise qr-scanner-worker.min.js in Ihren Dist neben qr-scanner.min.js oder neben das Skript kopieren in dem Sie qr-scanner.min.js bündeln.
qr-scanner.min.js ist ein es6-Modul und kann wie folgt importiert werden:
import QrScanner from 'path/to/qr-scanner.min.js' ; // if using plain es6 import
import QrScanner from 'qr-scanner' ; // if installed via package and bundling with a module bundler like webpack or rollupDies erfordert, dass das importierende Skript auch ein es6-Modul oder ein Modulskript-Tag ist, z. B.:
< script type =" module " >
import QrScanner from 'path/to/qr-scanner.min.js' ;
// do something with QrScanner
</ script >Wenn Ihr Projekt nicht auf es6-Modulen basiert, können Sie dies tun
import ( 'path/to/qr-scanner.min.js' ) . then ( ( module ) => {
const QrScanner = module . default ;
// do something with QrScanner
} ) ;qr-scanner.umd.min.js für die direkte Verwendung als Nicht-Modul-Skript < script src =" path/to/qr-scanner.umd.min.js " > </ script >
< script >
// do something with QrScanner
</ script >qr-scanner.umd.min.js direkt mit Ihrem Nicht-Modulcode mit Tools wie gulp oder grunt.require Bundlern wie browserify: const QrScanner = require ( 'qr-scanner' ) ; // if installed via package
const QrScanner = require ( 'path/to/qr-scanner.umd.min.js' ) ; // if not installed via package
// do something with QrScanner Diese Bibliothek nutzt ECMAScript 2017-Funktionen wie async Funktionen. Wenn Sie alte Browser unterstützen müssen, können Sie qr-scanner.legacy.min.js verwenden, das mit ECMAScript 2015 (ES6) kompatibel ist. Es ist ein UMD-Build und kann als Ersatz für qr-scanner.umd.min.js verwendet werden, siehe oben. Beachten Sie, dass der Legacy-Build größer ist, da er einige Polyfills enthält und zur Unterstützung von Browsern, die keine dynamischen Importe unterstützen, das Worker-Skript inline einfügt, das jedoch ohnehin zum Laden in Legacy-Browsern erforderlich wäre. Sie müssen den Legacy-Build jedoch wahrscheinlich nicht verwenden, da die allgemeine Browserunterstützung für den regulären Build bereits sehr gut ist. Insbesondere wenn Sie von der Kamera des Geräts aus scannen möchten, ist die Kameraunterstützung durch den Browser die strengere Einschränkung.
Erstellen Sie ein <video> -Element, in dem der Webcam-Videostream gerendert werden soll:
< video > </ video > // To enforce the use of the new api with detailed scan results, call the constructor with an options object, see below.
const qrScanner = new QrScanner (
videoElem ,
result => console . log ( 'decoded qr code:' , result ) ,
{ /* your options or returnDetailedScanResult: true if you're not specifying any other options */ } ,
) ;
// For backwards compatibility, omitting the options object will currently use the old api, returning scan results as
// simple strings. This old api will be removed in the next major release, by which point the options object is then
// also not required anymore to enable the new api.
const qrScanner = new QrScanner (
videoElem ,
result => console . log ( 'decoded qr code:' , result ) ,
// No options provided. This will use the old api and is deprecated in the current version until next major version.
) ;Als optionaler dritter Parameter kann ein Optionsobjekt bereitgestellt werden. Unterstützte Optionen sind:
| Option | Beschreibung |
|---|---|
onDecodeError | Handler, der bei Decodierungsfehlern aufgerufen werden soll. Der Standardwert ist QrScanner._onDecodeError . |
preferredCamera | Präferenz für die zu verwendende Kamera. Die Präferenz kann entweder eine von listCameras zurückgegebene Geräte-ID oder ein als 'environment' oder 'user' angegebener Ausrichtungsmodus sein. Der Standardwert ist 'environment' . Beachten Sie, dass es keine Garantie dafür gibt, dass die Präferenz tatsächlich erfüllt werden kann. |
maxScansPerSecond | Mit dieser Option können die Scans gedrosselt werden, um den Batterieverbrauch zu senken. Der Standardwert ist 25. Sofern vom Browser unterstützt, ist die Scanrate niemals höher als die Bildrate der Kamera, um unnötige doppelte Scans im selben Bild zu vermeiden. |
calculateScanRegion | Eine Methode, die einen Bereich bestimmt, auf den das Scannen zur Leistungsverbesserung beschränkt werden soll. Optional kann dieser Bereich vor der Durchführung des Scans als zusätzliche Leistungsverbesserung auch verkleinert werden. Der Bereich wird als x , y , width und height angegeben; die Abmessungen für den verkleinerten Bereich als downScaledWidth und downScaledHeight . Beachten Sie, dass das Seitenverhältnis zwischen width und height sowie downScaledWidth und downScaledHeight gleich bleiben sollte. Standardmäßig ist der Scanbereich auf ein zentriertes Quadrat von zwei Dritteln der Videobreite oder -höhe (je nachdem, welcher Wert kleiner ist) beschränkt und auf ein Quadrat von 400 x 400 verkleinert. |
highlightScanRegion | Setzen Sie diese Option auf true um einen Umriss um den Scanbereich im Videostream darzustellen. Dabei wird ein absolut positioniertes div verwendet, das den Scanbereich abdeckt. Dieses div kann entweder als Option overlay bereitgestellt werden, siehe unten, oder automatisch erstellt und dann über qrScanner.$overlay aufgerufen werden. Es kann über CSS frei gestaltet werden, z. B. durch Festlegen einer Kontur, eines Rahmens, einer Hintergrundfarbe usw. Beispiele finden Sie in der Demo. |
highlightCodeOutline | Setzen Sie diese Option auf true um einen Umriss um erkannte QR-Codes herum darzustellen. Dabei wird ein absolut positioniertes div verwendet, auf dem ein SVG zum Rendern der Kontur platziert wird. Dieses div kann entweder als Option overlay bereitgestellt werden (siehe unten) oder über qrScanner.$overlay aufgerufen werden. Das SVG kann über CSS frei gestaltet werden, z. B. durch Festlegen der Füllfarbe, Strichfarbe, Strichstärke usw. Beispiele finden Sie in der Demo. Für speziellere Anforderungen können Sie die cornerPoints auch direkt verwenden (siehe unten), um einen Umriss oder die Punkte selbst zu rendern. |
overlay | Ein benutzerdefiniertes div , das zur Verwendung für highlightScanRegion und highlightCodeOutline bereitgestellt werden kann. Das div sollte ein Geschwister von videoElem im DOM sein. Wenn diese Option angegeben wird, werden die Standardstile für highlightCodeOutline nicht angewendet, da davon ausgegangen wird, dass auf das Element bereits ein benutzerdefinierter Stil angewendet wurde. |
returnDetailedScanResult | Erzwingen Sie die Meldung detaillierter Scan-Ergebnisse, siehe unten. |
Um den Standardwert für eine Option zu verwenden, lassen Sie ihn weg oder geben Sie undefined ein.
Die an den Rückruf übergebenen Ergebnisse hängen davon ab, ob ein Optionsobjekt bereitgestellt wurde:
data , bei denen es sich um den String-Inhalt des gelesenen QR-Codes handelt, und cornerPoints , bei denen es sich um die Eckpunkte des Umrisses des gelesenen QR-Codes im Kamerastream handelt. Um die Verwendung der veralteten API zu vermeiden, wenn Sie keine anderen Optionen angeben, können Sie { returnDetailedScanResult: true } angeben, um die neue API zu aktivieren und das detaillierte Scanergebnis zu erhalten.
qrScanner . start ( ) ;Rufen Sie es auf, wenn Sie zum Scannen bereit sind, beispielsweise per Knopfdruck oder direkt beim Laden der Seite. Der Benutzer wird aufgefordert, die Erlaubnis zur Verwendung einer Kamera einzuholen. Hinweis: Um aus einem Webcam-Stream zu lesen, muss Ihre Seite über HTTPS bereitgestellt werden.
qrScanner . stop ( ) ; Wenn Sie möchten, können Sie den Scanvorgang jederzeit stoppen und durch einen erneuten Aufruf start() fortsetzen.
QrScanner . scanImage ( image )
. then ( result => console . log ( result ) )
. catch ( error => console . log ( error || 'No QR code found.' ) ) ;Unterstützte Bildquellen sind: HTMLImageElement, SVGImageElement, HTMLVideoElement, HTMLCanvasElement, ImageBitmap, OffscreenCanvas, Datei/Blob, Daten-URIs, URLs, die auf ein Bild verweisen (sofern sie sich auf demselben Ursprung befinden oder CORS aktiviert sind).
Als optionaler zweiter Parameter kann ein Optionsobjekt bereitgestellt werden. Unterstützte Optionen sind:
| Option | Beschreibung |
|---|---|
scanRegion | Ein durch x , y , width und height definierter Bereich, auf den die Suche nach einem QR-Code beschränkt werden soll. Zur Leistungsverbesserung kann dieser Bereich vor der Durchführung des Scans verkleinert werden, indem ein downScaledWidth und downScaledHeight bereitgestellt werden. Beachten Sie, dass das Seitenverhältnis zwischen width und height sowie downScaledWidth und downScaledHeight gleich bleiben sollte. Standardmäßig erstreckt sich der Bereich über das gesamte Bild und wird nicht verkleinert. |
qrEngine | Eine manuell erstellte QR-Scanner-Engine-Instanz zur Wiederverwendung. Dies verbessert die Leistung, wenn Sie viele Bilder scannen. Eine Engine kann manuell über QrScanner.createQrEngine(QrScanner.WORKER_PATH) erstellt werden. Standardmäßig wird für das Scannen einzelner Bilder keine Engine wiederverwendet. |
canvas | Eine manuell erstellte Leinwand zur Wiederverwendung. Dies verbessert die Leistung, wenn Sie viele Bilder scannen. Eine Leinwand kann manuell über ein <canvas> -Tag in Ihrem Markup oder document.createElement('canvas') erstellt werden. Standardmäßig wird für das Scannen einzelner Bilder keine Leinwand wiederverwendet. |
disallowCanvasResizing | Fordern Sie an, dass die Größe einer bereitgestellten Leinwand zur Wiederverwendung nicht geändert wird, unabhängig von den Abmessungen des Quellbilds oder der Quellregion. Beachten Sie, dass die Leinwand und der Quellbereich das gleiche Seitenverhältnis haben sollten, um zu vermeiden, dass das zu scannende Bild verzerrt wird, was die Erkennung von QR-Codes unmöglich machen könnte. Standardmäßig wird die Leinwandgröße an die Abmessungen des Scanbereichs angepasst oder an den verkleinerten Scanbereich für das Scannen einzelner Bilder angepasst. |
alsoTryWithoutScanRegion | Fordern Sie einen zweiten Scan des gesamten Bildes an, wenn eine scanRegion angegeben wurde und in dieser Region kein QR-Code gefunden wurde. Standardmäßig wird kein zweiter Scan versucht. |
returnDetailedScanResult | Erzwingen Sie die Meldung detaillierter Scan-Ergebnisse, siehe unten. |
Um den Standardwert für eine Option zu verwenden, lassen Sie ihn weg oder geben Sie undefined an.
Die zurückgegebenen Ergebnisse hängen davon ab, ob ein Optionsobjekt bereitgestellt wurde:
data , bei denen es sich um den String-Inhalt des gelesenen QR-Codes handelt, und cornerPoints , bei denen es sich um die Eckpunkte des Umrisses des gelesenen QR-Codes im Kamerastream handelt. Um die Verwendung der veralteten API zu vermeiden, wenn Sie keine anderen Optionen angeben, können Sie { returnDetailedScanResult: true } angeben, um die neue API zu aktivieren und das detaillierte Scanergebnis zu erhalten.
Wenn kein QR-Code gelesen werden konnte, wirft scanImage .
Diese Bibliothek bietet eine Hilfsmethode zum Überprüfen, ob das Gerät über eine Kamera verfügt. Dies kann hilfreich sein, um zu bestimmen, ob einem Benutzer die QR-Webcam-Scanfunktion angeboten werden soll.
QrScanner . hasCamera ( ) ; // async Diese Bibliothek bietet eine Dienstprogrammmethode zum Abrufen einer Liste der Kameras des Geräts, definiert über ihre id und label . Dies kann nützlich sein, um einem Benutzer die Auswahl einer bestimmten Kamera zu ermöglichen.
Optional können Sie die Etiketten der Kamera anfordern. Beachten Sie, dass dies jedoch die Erlaubnis des Benutzers zum Zugriff auf die Kameras erfordert, die er einholen wird, sofern sie nicht bereits erteilt wurde. Sofern nicht ausdrücklich angefordert, werden Gerätebezeichnungen nach bestem Wissen und Gewissen ermittelt, d. h. tatsächliche Bezeichnungen werden zurückgegeben, wenn bereits Berechtigungen erteilt wurden, andernfalls Ersatzbezeichnungen. Wenn Sie Kamerabezeichnungen anfordern möchten, empfiehlt es sich, listCameras nach dem erfolgreichen Start einer QrScanner-Instanz aufzurufen, da der Benutzer zu diesem Zeitpunkt bereits seine Erlaubnis erteilt hat.
QrScanner . listCameras ( ) ; // async; without requesting camera labels
QrScanner . listCameras ( true ) ; // async; requesting camera labels, potentially asking the user for permission Sie können die bevorzugte zu verwendende Kamera ändern. Die Präferenz kann entweder eine von listCameras zurückgegebene Geräte-ID oder ein als 'environment' oder 'user' angegebener Ausrichtungsmodus sein. Beachten Sie, dass es keine Garantie dafür gibt, dass die Präferenz tatsächlich erfüllt werden kann.
qrScanner . setCamera ( facingModeOrDeviceId ) ; // asyncDer Scanner scannt standardmäßig nach dunklen QR-Codes auf hellem Hintergrund. Sie können dieses Verhalten ändern, um nach hellen QR-Codes auf dunklem Hintergrund oder nach beiden gleichzeitig zu suchen:
qrScanner . setInversionMode ( inversionMode ) ; Wobei inversionMode original , invert oder both sein kann. Die Standardeinstellung für das Webcam-Scannen ist original und für das Einzelbild-Scannen both .
Ändern Sie die Gewichtungen für Rot, Grün und Blau in der Graustufenberechnung, um den Kontrast für QR-Codes einer bestimmten Farbe zu verbessern:
qrScanner . setGrayscaleWeights ( red , green , blue , useIntegerApproximation = true ) ; Wobei red , green und blue zusammen 256 ergeben sollten, wenn useIntegerApproximation === true , andernfalls 1 . Standardmäßig werden diese Werte verwendet.
In unterstützten Browsern können Sie prüfen, ob die aktuell verwendete Kamera über einen Blitz verfügt und diesen ein- oder ausschalten. Beachten Sie, dass hasFlash aufgerufen werden sollte, nachdem der Scanner erfolgreich gestartet wurde, um zu vermeiden, dass ein temporärer Kamerastream geöffnet werden muss, nur um abzufragen, ob Flash-Unterstützung vorhanden ist, und möglicherweise den Benutzer um Kamerazugriff zu bitten.
qrScanner . hasFlash ( ) ; // check whether the browser and used camera support turning the flash on; async.
qrScanner . isFlashOn ( ) ; // check whether the flash is on
qrScanner . turnFlashOn ( ) ; // turn the flash on if supported; async
qrScanner . turnFlashOff ( ) ; // turn the flash off if supported; async
qrScanner . toggleFlash ( ) ; // toggle the flash if supported; async.Sie können den QR-Scanner zerstören, wenn Sie ihn nicht mehr benötigen:
qrScanner . destroy ( ) ;
qrScanner = null ;Dadurch werden der Kamerastream und der Web-Worker gestoppt und Ereignis-Listener bereinigt. Der QR-Scanner ist nach seiner Zerstörung nicht mehr funktionsfähig.
Das Projekt ist in qr-scanner.min.js in Kombination mit qr-scanner-worker.min.js vorgefertigt. Ein Selbstbau ist nur erforderlich, wenn Sie den Code im Ordner /src ändern möchten. Für die Erstellung ist NodeJs erforderlich.
Installieren Sie die erforderlichen Build-Pakete:
yarnGebäude:
yarn build
