Google ZXing 라이브러리의 Cosmo Wolfe 자바스크립트 포트를 기반으로 하는 자바스크립트 QR 코드 스캐너입니다.
이 라이브러리에서는 원래 포트에 비해 몇 가지 개선 사항이 적용되었습니다.
BarcodeDetector 사용할 수 있는 경우 ~15.3kB(~5.6kB gzipped)만 로드됩니다.벤치마킹에 따르면 이 프로젝트의 스캐너 엔진의 감지율은 가장 인기 있는 자바스크립트 QR 스캐너 라이브러리 LazarSoft/jsqrcode 중 하나보다 약 2-3배(최대 8배) 높습니다. 또한 다른 라이브러리에서는 종종 QR 코드의 내용을 잘못 읽는 반면, 이 프로젝트에서는 벤치마킹에서 잘못된 내용이 발생하지 않았습니다.
라이브러리는 웹캠의 연속 비디오 스트림 스캔은 물론 단일 이미지 스캔도 지원합니다.
이 라이브러리의 개발은 세계 최초의 브라우저 기반 블록체인인 nimiq의 후원을 받습니다.
https://nimiq.github.io/qr-scanner/demo/를 참조하세요.
npm을 통해 설치하려면:
npm install --save qr-scanner원사를 통해 설치하려면:
yarn add qr-scanner 또는 qr-scanner.min.js 및 qr-scanner-worker.min.js 프로젝트에 복사하면 됩니다.
QR 스캐너는 두 개의 주요 파일로 구성됩니다. qr-scanner.min.js 필요한 경우에만 동적 가져오기를 통해 작업자 스크립트 qr-scanner-worker.min.js 를 로드하는 기본 API 파일입니다. 동적 가져오기를 자동으로 처리하는 Rollup 또는 Webpack과 같은 번들러를 사용하지 않는 경우 qr-scanner-worker.min.js qr-scanner.min.js 옆 또는 스크립트 옆의 dist로 복사해야 할 수도 있습니다. qr-scanner.min.js 번들로 묶고 있습니다.
qr-scanner.min.js 는 es6 모듈이며 다음과 같이 가져올 수 있습니다.
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 rollup이를 위해서는 가져오기 스크립트가 es6 모듈 또는 모듈 스크립트 태그여야 합니다. 예:
< script type =" module " >
import QrScanner from 'path/to/qr-scanner.min.js' ;
// do something with QrScanner
</ script >프로젝트가 es6 모듈을 기반으로 하지 않는 경우 다음을 수행할 수 있습니다.
import ( 'path/to/qr-scanner.min.js' ) . then ( ( module ) => {
const QrScanner = module . default ;
// do something with QrScanner
} ) ;qr-scanner.umd.min.js 사용하세요. < script src =" path/to/qr-scanner.umd.min.js " > </ script >
< script >
// do something with QrScanner
</ script >qr-scanner.umd.min.js 직접 번들로 묶습니다.require 기반 번들러를 사용하여 lib를 번들로 묶습니다. 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 이 라이브러리는 async 함수와 같은 ECMAScript 2017 기능을 사용합니다. 이전 브라우저를 지원해야 하는 경우 ECMAScript 2015(ES6)와 호환되는 qr-scanner.legacy.min.js 사용할 수 있습니다. UMD 빌드이며 qr-scanner.umd.min.js 를 대체하여 사용할 수 있습니다(위 참조). 레거시 빌드는 일부 폴리필을 포함하고 동적 가져오기를 지원하지 않는 브라우저를 지원하기 위해 더 크지만 어쨌든 레거시 브라우저에 로드해야 하는 작업자 스크립트를 인라인합니다. 하지만 일반 브라우저 지원은 이미 일반 빌드에 매우 적합하므로 레거시 빌드를 사용할 필요는 없습니다. 특히 장치의 카메라에서 스캔하려는 경우 브라우저의 카메라 지원이 더 엄격한 제한 사항입니다.
웹캠 비디오 스트림이 렌더링되어야 하는 <video> 요소를 만듭니다.
< 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.
) ;선택적인 세 번째 매개변수로 옵션 객체를 제공할 수 있습니다. 지원되는 옵션은 다음과 같습니다.
| 옵션 | 설명 |
|---|---|
onDecodeError | 디코딩 오류 시 호출되는 핸들러입니다. 기본값은 QrScanner._onDecodeError 입니다. |
preferredCamera | 사용할 카메라에 대한 기본 설정입니다. 기본 설정은 listCameras 에서 반환된 장치 ID이거나 'environment' 또는 'user' 로 지정된 방향 모드일 수 있습니다. 기본값은 'environment' 입니다. 기본 설정이 실제로 충족될 수 있다는 보장은 없습니다. |
maxScansPerSecond | 이 옵션을 사용하면 배터리 소모를 줄이기 위해 스캔 속도를 조절할 수 있습니다. 기본값은 25입니다. 브라우저에서 지원하는 경우 동일한 프레임에서 불필요한 중복 스캔을 피하기 위해 스캔 속도는 카메라의 프레임 속도보다 높지 않습니다. |
calculateScanRegion | 성능 향상을 위해 스캔을 제한해야 하는 영역을 결정하는 방법입니다. 추가 성능 향상을 위해 스캔을 수행하기 전에 선택적으로 이 영역을 축소할 수도 있습니다. 영역은 x , y , width 및 height 로 지정됩니다. 축소된 영역의 크기는 downScaledWidth 및 downScaledHeight 입니다. width 와 height , downScaledWidth 와 downScaledHeight 간의 가로 세로 비율은 동일하게 유지되어야 합니다. 기본적으로 스캔 영역은 비디오 너비 또는 높이의 2/3 중 더 작은 정사각형의 중앙 정사각형으로 제한되며 400x400 정사각형으로 축소됩니다. |
highlightScanRegion | 비디오 스트림의 스캔 영역 주위에 윤곽선을 렌더링하려면 이 옵션을 true 로 설정하십시오. 이는 스캔 영역을 덮는 절대 위치의 div 사용합니다. 이 div 옵션 overlay 로 제공되거나(아래 참조) 자동으로 생성된 다음 qrScanner.$overlay 통해 액세스될 수 있습니다. 윤곽선, 테두리, 배경색 등을 설정하여 CSS를 통해 자유롭게 스타일을 지정할 수 있습니다. 예제는 데모를 참조하세요. |
highlightCodeOutline | 감지된 QR 코드 주변의 윤곽선을 렌더링하려면 이 옵션을 true 로 설정하세요. 이는 윤곽선 렌더링을 위한 SVG가 배치될 절대 위치 div 사용합니다. 이 div 옵션 overlay 로 제공되거나(아래 참조) qrScanner.$overlay 통해 액세스될 수 있습니다. SVG는 CSS를 통해 채우기 색상, 획 색상, 획 너비 등을 설정하여 자유롭게 스타일을 지정할 수 있습니다. 예제는 데모를 참조하세요. 더 특별한 요구 사항이 있는 경우에는 외곽선이나 점을 직접 렌더링하기 위해 cornerPoints 직접 사용할 수도 있습니다. 아래를 참조하세요. |
overlay | highlightScanRegion 및 highlightCodeOutline 에 사용하기 위해 제공할 수 있는 사용자 정의 div 입니다. div 는 DOM에서 videoElem 의 형제여야 합니다. 이 옵션이 제공되는 경우 요소에 이미 일부 사용자 정의 스타일이 적용되어 있을 것으로 예상되므로 highlightCodeOutline 의 기본 스타일은 적용되지 않습니다. |
returnDetailedScanResult | 자세한 검사 결과 보고를 시행합니다. 아래를 참조하세요. |
옵션의 기본값을 사용하려면 해당 값을 생략하거나 undefined 값을 제공하세요.
콜백에 전달된 결과는 옵션 객체가 제공되었는지 여부에 따라 달라집니다.
data 와 카메라 스트림에서 읽은 QR 코드 윤곽선의 모퉁이 지점인 cornerPoints 가 있는 개체입니다. 다른 옵션을 제공하지 않는 경우 더 이상 사용되지 않는 API의 사용을 방지하려면 { returnDetailedScanResult: true } 제공하여 새 API를 활성화하고 자세한 스캔 결과를 얻을 수 있습니다.
qrScanner . start ( ) ;예를 들어 버튼을 클릭하거나 페이지를 로드할 때 직접 스캔할 준비가 되면 호출하세요. 사용자에게 카메라 사용 권한을 묻는 메시지가 표시됩니다. 참고: 웹캠 스트림에서 읽으려면 페이지가 HTTPS를 통해 제공되어야 합니다.
qrScanner . stop ( ) ; 원한다면 언제든지 스캔을 중지하고 start() 다시 호출하여 스캔을 재개할 수 있습니다.
QrScanner . scanImage ( image )
. then ( result => console . log ( result ) )
. catch ( error => console . log ( error || 'No QR code found.' ) ) ;지원되는 이미지 소스는 다음과 같습니다: HTMLImageElement, SVGImageElement, HTMLVideoElement, HTMLCanvasElement, ImageBitmap, OffscreenCanvas, 파일/Blob, 데이터 URI, 이미지를 가리키는 URL(동일한 원본에 있거나 CORS가 활성화된 경우)
선택적 두 번째 매개변수로 옵션 객체를 제공할 수 있습니다. 지원되는 옵션은 다음과 같습니다.
| 옵션 | 설명 |
|---|---|
scanRegion | QR 코드 검색을 제한해야 하는 x , y , width 및 height 로 정의된 영역입니다. 성능 향상을 위해 downScaledWidth 및 downScaledHeight 제공하여 스캔을 수행하기 전에 이 영역을 축소할 수 있습니다. width 와 height , downScaledWidth 와 downScaledHeight 간의 가로 세로 비율은 동일하게 유지되어야 합니다. 기본적으로 영역은 전체 이미지에 걸쳐 있으며 축소되지 않습니다. |
qrEngine | 재사용할 수동으로 생성된 QR 스캐너 엔진 인스턴스입니다. 이렇게 하면 많은 이미지를 스캔하는 경우 성능이 향상됩니다. 엔진은 QrScanner.createQrEngine(QrScanner.WORKER_PATH) 통해 수동으로 생성할 수 있습니다. 기본적으로 단일 이미지 스캔에는 엔진이 재사용되지 않습니다. |
canvas | 재사용할 수 있도록 수동으로 생성된 캔버스입니다. 이렇게 하면 많은 이미지를 스캔하는 경우 성능이 향상됩니다. 캔버스는 마크업의 <canvas> 태그나 document.createElement('canvas') 를 통해 수동으로 생성할 수 있습니다. 기본적으로 단일 이미지 스캔에는 캔버스가 재사용되지 않습니다. |
disallowCanvasResizing | 소스 이미지 또는 소스 영역 크기에 관계없이 크기가 조정되지 않도록 재사용을 위해 제공된 캔버스를 요청합니다. 스캔할 이미지가 왜곡되어 QR 코드 감지가 불가능해지는 것을 방지하려면 캔버스와 소스 영역의 종횡비가 동일해야 합니다. 기본적으로 캔버스 크기는 단일 이미지 스캔을 위해 스캔 영역 크기 또는 축소된 스캔 영역에 맞게 조정됩니다. |
alsoTryWithoutScanRegion | scanRegion 이 제공되었고 해당 지역 내에서 QR 코드가 발견되지 않은 경우 전체 이미지에 대한 두 번째 스캔을 요청합니다. 기본적으로 두 번째 검색은 시도되지 않습니다. |
returnDetailedScanResult | 자세한 검사 결과 보고를 시행합니다. 아래를 참조하세요. |
옵션의 기본값을 사용하려면 해당 값을 생략하거나 undefined 값을 제공하세요.
반환되는 결과는 옵션 개체가 제공되었는지 여부에 따라 달라집니다.
data 와 카메라 스트림에서 읽은 QR 코드 윤곽선의 모퉁이 지점인 cornerPoints 가 있는 개체입니다. 다른 옵션을 제공하지 않는 경우 더 이상 사용되지 않는 API의 사용을 방지하려면 { returnDetailedScanResult: true } 제공하여 새 API를 활성화하고 자세한 스캔 결과를 얻을 수 있습니다.
QR 코드를 읽을 수 없으면 scanImage 발생합니다.
이 라이브러리는 장치에 카메라가 있는지 확인하는 유틸리티 방법을 제공합니다. 이는 사용자에게 QR 웹 캠 스캔 기능을 제공할지 여부를 결정하는 데 유용할 수 있습니다.
QrScanner . hasCamera ( ) ; // async 이 라이브러리는 id 및 label 통해 정의된 기기의 카메라 목록을 가져오는 유틸리티 방법을 제공합니다. 이는 사용자가 사용할 특정 카메라를 선택하도록 하는 데 유용할 수 있습니다.
선택적으로 카메라 라벨을 요청할 수 있습니다. 그러나 카메라에 액세스하려면 사용자의 허가가 필요하며, 아직 허가되지 않은 경우 이에 대한 요청을 받게 됩니다. 특별히 요청하지 않은 경우 장치 라벨은 최선을 다해 결정됩니다. 즉, 권한이 이미 부여된 경우 실제 라벨이 반환되고 그렇지 않은 경우 대체 라벨이 반환됩니다. 카메라 라벨을 요청하려면 QrScanner 인스턴스가 성공적으로 시작된 후 listCameras 호출하는 것이 좋습니다. 그때쯤이면 사용자가 이미 권한을 부여했을 것이기 때문입니다.
QrScanner . listCameras ( ) ; // async; without requesting camera labels
QrScanner . listCameras ( true ) ; // async; requesting camera labels, potentially asking the user for permission 사용할 기본 카메라를 변경할 수 있습니다. 기본 설정은 listCameras 에서 반환된 장치 ID이거나 'environment' 또는 'user' 로 지정된 방향 모드일 수 있습니다. 기본 설정이 실제로 충족될 수 있다는 보장은 없습니다.
qrScanner . setCamera ( facingModeOrDeviceId ) ; // async스캐너는 기본적으로 밝은 배경에서 어두운 QR 코드를 검색합니다. 어두운 배경에서 밝은 QR 코드를 스캔하거나 동시에 두 가지 모두를 스캔하도록 이 동작을 변경할 수 있습니다.
qrScanner . setInversionMode ( inversionMode ) ; inversionMode original , invert 또는 both 수 있습니다. 웹캠 스캔의 기본값은 original 이고 단일 이미지 스캔의 경우 both .
특정 색상의 QR 코드에 대한 대비를 향상시키기 위해 회색조 계산에서 빨간색, 녹색 및 파란색의 가중치를 변경합니다.
qrScanner . setGrayscaleWeights ( red , green , blue , useIntegerApproximation = true ) ; 여기서 red , green , blue 의 합은 useIntegerApproximation === true 인 경우 최대 256이고 그렇지 않은 경우 1 . 기본적으로 이러한 값이 사용됩니다.
지원되는 브라우저에서는 현재 사용하고 있는 카메라에 플래시가 있는지 확인하고 켜거나 끌 수 있습니다. 스캐너가 성공적으로 시작된 후 hasFlash를 호출해야 플래시 지원 여부를 쿼리하기 위해 임시 카메라 스트림을 열 필요가 없으며 잠재적으로 사용자에게 카메라 액세스를 요청할 수 있습니다.
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.더 이상 필요하지 않으면 QR 스캐너를 폐기할 수 있습니다.
qrScanner . destroy ( ) ;
qrScanner = null ;이렇게 하면 카메라 스트림과 웹 작업자가 중지되고 이벤트 리스너가 정리됩니다. QR 스캐너가 파괴된 후에는 제대로 작동하지 않습니다.
프로젝트는 qr-scanner-worker.min.js와 함께 qr-scanner.min.js에 사전 빌드되어 있습니다. 직접 빌드하는 것은 /src 폴더의 코드를 변경하려는 경우에만 필요합니다. 빌드하려면 NodeJ가 필요합니다.
필수 빌드 패키지를 설치합니다.
yarn건물:
yarn build
