[![MIT license](http://img.shields.io/badge/license-MIT-brightgreen.svg)](http://opensource.org/licenses/MIT) @cheprasov/qrcode ========= The library is for generating QR codes like SVG, HTML5 Canvas, PNG and JPG files, or text. #### Features: - The library has classes for generation SVG, Canvas, PNG / JPG or text with QR code. - it is easy to use and configure (error correction level, type number, padding and so on). - Supports inverting of data. - The library is covered by tests. - Easy to extend the classes or create own class for generation QR code. - SVG (see [class `QRCodeSVG`](#33-class-qrcodesvg)) - Returns generated QR code as SVG (xml) or DataURL. - Optimized SVG structure for xml and for DataURL. - Supports adding an image (logo) to QR code (allows to use url, dataUrl, Image, Canvas). See [example](#23-qr-code-with-image) - Allows to specify relative/abcolute position/size of image on QR code. - Canvas (see [class `QRCodeCanvas`](#32-class-qrcodecanvas)) - Draws QR code on provided canvas or returns new canvas element with QR code. - Allows to get PNG / JPG files with QR code like dataUrl. - Supports adding a image (logo) to QR code (allows to use url, dataUrl, Image, Canvas). - Has image loader for images for QR code via Promise. - It is possible to specify scale or canvas size. - Allows to specify relative/abcolute position/size of image on QR code. - Text (see [class `QRCodeText`](34-class-qrcodetext)) - It is possible to create QR code for consoles or text output. #### Plans to do: - To add possibility to use patterns, themes and flexible customisation of QR code. - to add support of rgb & rgba format for canvas colors. ### 1. How to install ```bash > npm install @cheprasov/qrcode ``` ```javascript import { QRCodeRaw, QRCodeSVG, QRCodeCanvas, QRCodeText } from '@cheprasov/qrcode'; ``` ### 2. Quick examples #### 2.1. Create SVG QR Code ```javascript import { QRCodeSVG } from '@cheprasov/qrcode'; const qrSVG = new QRCodeSVG('some value for QR code'); const dataUrlWithSVGQRCode = qrSVG.toDataUrl(); const xmlWithQRCode = qrSVG.toString(); ``` #### 2.2. Create Image QR Code ```javascript import { QRCodeCanvas } from '@cheprasov/qrcode'; const qrCanvas = new QRCodeCanvas('some value for QR code'); const dataUrlWithQRCode = qrCanvas.toDataUrl(); const canvasWithQRCode = qrCanvas.getCanvas(); ``` #### 2.3. QR Code with Image ```javascript import { QRCodeSVG } from '@cheprasov/qrcode'; const divElement = document.getElementById('some-id'); const qrSVG = new QRCodeSVG('https://github.com/cheprasov/js-qrcode/', { level: 'Q', image: { source: 'GitHub-Mark-120px-plus.png', width: '20%', height: '20%', x: 'center', y: 'center', }, }); divElement.innerHTML = qrSVG.toString(); ``` Result: Note, padding & image.border = 1 by default. ![test](qrcode_scheme.png) ### 3. Documentation #### 3.1. class `QRCodeRaw` The class base class for all QR code generators, returns raw data with information about QR dots and padding. ```javascript import { QRCodeRaw } from '@cheprasov/qrcode'; ``` Public methods: #### `constructor(value: string, config: object)` Create new instance of QRCodeRaw Params: - `value` (string) - new value for encoding to QR code - `config` (object, optional) - parameters of configuration - `level` (string, optional, default = `L`) - error correction level. Note, the level affects QR Code data size. Allowed values: - `L` - Allows recovery of up to 7% data loss - `M` - Allows recovery of up to 15% data loss - `Q` - Allows recovery of up to 25% data loss - `H` - Allows recovery of up to 30% data loss - `typeNumber` (number, optional, default = `0`) - data capacity type, see details in [appendix 4.1](#41-data-capacity-in-bytes). Type number (`1` ~ `40`), or `0` for auto detection. - `invert` (boolean, optional, default = `false`) - inverting data of QR code. - `padding` (number, optional, default = `1`) - count of white spaces on sides QR code. 1 unit has size like 1 information dot. - `errorsEnabled`: (boolean, optional, default = `false`) - if it is enabled and QR code generator can not create a QR Code then an error will thrown. If it is disabled then methods will return `null` of fail. #### `setValue(value: string): void` Set new value for encoding to QR code Params: - `value` (string) - new value for encoding to QR code #### `getDataSize(): number` Get size of QR code width / height (width and height are equal) Method will return `0` if QR code can not be generated by some reasons. #### `getData(): boolean[][]` Get raw data of QR code. Method will return `null` if QR code can not be generated by some reasons. Example: ```javascript import { QRCodeRaw } from '@cheprasov/qrcode'; const config = { level: 'H', // use high error correction level padding: 0, // do not use padding around qr code data }; const qrRaw = new QRCodeRaw('some value', config); const qrCodeRaw = qrRaw.getData(); if (qrCodeRaw) { console.log(qrCodeRaw); // [ // 0: [true, true, true, true, ... true], // 1: [true, false, false, false, ... true], // ... // 24: [true, true, true, ... true], // ] } ``` #### 3.2. class `QRCodeCanvas` The QR code generator based on HTML5 Canvas. It can create a canvas with QR code, or PNG/JPG data url. The class extends [`QRCodeRaw`](31-class-qrcoderaw), therefore please see there description about public method and configuration params. ```javascript import { QRCodeCanvas } from '@cheprasov/qrcode'; ``` Public methods: #### `constructor(value: string, config: object)` Create new instance of QRCodeCanvas. Please see config description of [`QRCodeRaw.constructor`](#constructorvalue-string-config-object). Config has additional parameters: - `config` (object, optional) - parameters of configuration - see config of [`QRCodeRaw.constructor`](#constructorvalue-string-config-object) - `fgColor` (string, optional, default = `#000`) - foreground color of the QR code, is it allowed to use the next formats: - `RGB` or `#RGB`, example: `#ABC`, will be converted to `#AABBCC` - `RGBA` or `#RGBA`, example: `#ABCD`, will be converted to `#AABBCCDD` - `RRGGBB` or `#RRGGBB`, example: `#AABBCC` - `RRGGBBAA` or `#RRGGBBAA`, example: `#AABBCCDD` - Other formats (like `red`, `rgb(...)`, `rgba(...)`) are not supported and will be converted to `#0000` - `bgColor` (string, optional, default = `#FFF`) - background color of the QR code, see description of `fgColor`. - `scale` (number, optional, default = `10`) - scale size of QR code. For example, when scale is 5 then QR generator will use 5 pixel for draw 1 data dot. - `size` (number, optional, default = `null`) - size (width & height) of canvas in pixels. If size is specified then scale param will be ignored. Note, that the original canvas with QR code will be stretched to the specified size. See [image scheme](#23-qr-code-with-image) - `image` (object, optional, default = `null`) - parameters on an image, that should be added to QR code, like logo. - `source` (string|Image|Canvas) - source of image for QR Code, allowed to use the next types: - `string` - url to resource or dataUrl of image. - `Image` - it is allowed to use Image. The image's src should be loaded before use it. - `Canvas` - allowed to use HTML5 canvas element. - `width` (number|string) - width of the image in QR code dots (not a pixel), allowed formats: - `` - defines the width of image, example: `width: 30` - `%` - defines the width in percent of QR code without padding, example: `width: '20%'` - `height` (number|string) - height of the image in QR code dots, see `width` - `x` (number|string, optional, default = `0`) - position of image on QR code by horizontal in QR code dots (not a pixel), allowed formats: - `` - sets the left edge position from left to right, example: `x: 10` - `%` - sets the left edge position in % of QR code without padding. Negative values are allowed. Example: `x: '50%'` - `left` - aligns the image to the left, example: `x: 'left'` - `right` - aligns the image to the right, example: `x: 'right'` - `center` - Centers the image in center of QR code, example: `x: 'center'` - `left ` - the same as `` - `left %` - the same as `%` - `right ` - sets the right edge position from right to left, example: `x: 'right 5'` - `right %` - sets the tight edge position in % of QR code without padding, example: `x: 'right 10%'` - `y` (number|string, optional, default = `0`) - position of image on QR code by vertical in QR code dots (not a pixel), allowed formats: - `` - sets the top edge position from top to bottom, example: `y: 10` - `%` - sets the top edge position in % of QR code without padding. Negative values are allowed. Example: `y: '50%'` - `top` - aligns the image to the top, example: `y: 'top'` - `bottom` - aligns the image to the bottom, example: `y: 'bottom'` - `center` - Centers the image in center of QR code, example: `y: 'center'` - `top ` - the same as `` - `top %` - the same as `%` - `bottom ` - sets the bottom edge position from bottom to top, example: `y: 'bottom 5'` - `bottom %` - sets the bottom edge position in % of QR code without padding, example: `y: 'bottom 10%'` - `border` (number|null, optional, default = 1) - white space length around the images in dots. Negative values are allowed. - use `0` - for white space only under the image - use `null` to remove any white spaces under image and leave QR data dots #### `draw(canvas: HTMLCanvasElement = null): null | HTMLCanvasElement| Promise` Draws QR code on a canvas element and return the canvas if the canvas is provided, or returns a new canvas element if canvas is not provided (see `getCanvas()`). If QR code can not be generated then `null` will be returned. If `config.image` is provided AND `config.image.source` is `string` (url or dataUrl) then a promise will be returned with a canvas as result. #### `getCanvas(): null | HTMLCanvasElement | Promise` Returns new canvas element with QR code. If QR code can not be generated then `null` will be returned. If `config.image` is provided AND `config.image.source` is `string` (url or dataUrl) then a promise will be returned with a canvas as result. #### `toDataUrl(type: string = 'image/png', encoderOptions: number = 0.92): null | string | Promise` Allowed alias: `toDataURL(...)` Returns dataUrl with QR code. If QR code can not be generated then `null` will be returned. If `config.image` is provided AND `config.image.source` is `string` (url or dataUrl) then a promise will be returned with a dataUrl as result. See params descriptions here: https://developer.mozilla.org/en-US/docs/Web/API/HTMLCanvasElement/toDataURL Example ```javascript import { QRCodeCanvas } from '@cheprasov/qrcode'; const qrCanvas = new QRCodeCanvas('some value'); const dataUrl = qrCanvas.toDataUrl(); console.log(dataUrl); // data:image/png;base64,iVBORw0KGgoAAAA...g== ``` Example with promise ```javascript import { QRCodeCanvas } from '@cheprasov/qrcode'; // Example with promise const config = { level: 'H', // use high error correction level padding: 0, // do not use padding around qr code data, image: { source: 'https://some-url.com/foo.png', // or data:image/jpeg;base64,... width: '10%', height: '10%', x: 'center', y: 'center', } }; const qrCanvas = new QRCodeCanvas('some value', config); const promise = qrCanvas.toDataUrl(); // promise is returned because image.source is a string promise.then((dataUrl) => { console.log(dataUrl); // data:image/png;base64,iVBORw0KGgoAAAAN... }); ``` #### 3.3. class `QRCodeSVG` The class creates QR code as SVG in string or data url formats. The class extends [`QRCodeRaw`](31-class-qrcoderaw), therefore please see there description about public method and configuration params. ```javascript import { QRCodeSVG } from '@cheprasov/qrcode'; ``` Public methods: #### `constructor(value: string, config: object)` Create new instance of QRCodeSVG. Please see config description of [`QRCodeRaw.constructor`](#constructorvalue-string-config-object). Config has additional parameters: - `config` (object, optional) - parameters of configuration - see config of [`QRCodeRaw.constructor`](#constructorvalue-string-config-object) - `fgColor` (string, optional, default = `#000`) - foreground color of the QR code in CSS format - `bgColor` (string, optional, default = `#FFF`) - background color of the QR code in CSS format - `image` (object, optional, default = `null`) - parameters on an image, that should be added to QR code, like logo. See [image scheme](#23-qr-code-with-image) - `source` (string|Image|Canvas) - source of image for QR Code, allowed to use the next types: - `string` - url to resource or dataUrl of image. - `Image` - it is allowed to use Image. It is not necessary to have loaded image. - `Canvas` - allowed to use HTML5 canvas element. - `width` (number|string) - width of the image in QR code dots (not a pixel), allowed formats: - `` - defines the width of image, example: `width: 30` - `%` - defines the width in percent of QR code without padding, example: `width: '20%'` - `height` (number|string) - height of the image in QR code dots, see `width` - `x` (number|string, optional, default = `0`) - position of image on QR code by horizontal in QR code dots (not a pixel), allowed formats: - `` - sets the left edge position from left to right, example: `x: 10` - `%` - sets the left edge position in % of QR code without padding. Negative values are allowed. Example: `x: '50%'` - `left` - aligns the image to the left, example: `x: 'left'` - `right` - aligns the image to the right, example: `x: 'right'` - `center` - Centers the image in center of QR code, example: `x: 'center'` - `left ` - the same as `` - `left %` - the same as `%` - `right ` - sets the right edge position from right to left, example: `x: 'right 5'` - `right %` - sets the tight edge position in % of QR code without padding, example: `x: 'right 10%'` - `y` (number|string, optional, default = `0`) - position of image on QR code by vertical in QR code dots (not a pixel), allowed formats: - `` - sets the top edge position from top to bottom, example: `y: 10` - `%` - sets the top edge position in % of QR code without padding. Negative values are allowed. Example: `y: '50%'` - `top` - aligns the image to the top, example: `y: 'top'` - `bottom` - aligns the image to the bottom, example: `y: 'bottom'` - `center` - Centers the image in center of QR code, example: `y: 'center'` - `top ` - the same as `` - `top %` - the same as `%` - `bottom ` - sets the bottom edge position from bottom to top, example: `y: 'bottom 5'` - `bottom %` - sets the bottom edge position in % of QR code without padding, example: `y: 'bottom 10%'` - `border` (number|null, optional, default = 1) - white space length around the images in dots. Negative values are allowed. - use `0` - for white space only under the image - use `null` to remove any white spaces under image and leave QR data dots #### `toString(): null | string` Returns SVG with QR code as string. If QR code can not be generated then `null` will be returned. #### `toDataUrl(): null | string` Allowed alias: `toDataURL(...)` Returns SVG with QR code as dataUrl (string). If QR code can not be generated then `null` will be returned. Example ```javascript import { QRCodeSVG } from '@cheprasov/qrcode'; const qrSVG = new QRCodeSVG('some value'); const dataUrl = qrSVG.toDataUrl(); console.log(dataUrl); // data:image/png;base64,iVBORw0KGgoAAAA...g== ``` Example with image ```javascript import { QRCodeSVG } from '@cheprasov/qrcode'; const config = { level: 'M', // use high error correction level padding: 0, // do not use padding around qr code data, image: { source: 'https://some-url.com/foo.png', // or data:image/jpeg;base64,... width: '10%', height: '10%', x: 'center', y: 'center', } }; const qrSVG = new QRCodeSVG('some value', config); const svg = qrSVG.toString(); console.log(svg); // output: // // // // // ... // // ``` #### 3.4. class `QRCodeText` The class creates QR code as text. It is possible to show QR code in terminal. The class extends [`QRCodeRaw`](31-class-qrcoderaw), therefore please see there description about public method and configuration params. ```javascript import { QRCodeSVG } from '@cheprasov/qrcode'; ``` Public methods: #### `constructor(value: string, config: object)` Create new instance of QRCodeSVG. Please see config description of [`QRCodeRaw.constructor`](#constructorvalue-string-config-object). Config has additional parameters: - `config` (object, optional) - parameters of configuration - see config of [`QRCodeRaw.constructor`](#constructorvalue-string-config-object) - `blackSymbol` (string, optional, default = `▓▓`) - symbol(s) for black QR code dot. - `whiteSymbol` (string, optional, default = ` `) - symbol(s) for white QR code dot. #### `toString(): null | string ` Returns QR code as string. If QR code can not be generated then `null` will be returned. Example ```javascript import { QRCodeText } from '@cheprasov/qrcode'; const qrText = new QRCodeText('some value', { blackSymbol: '@@', whiteSymbol: '..', }); const qrCode = qrText.toString(); console.log(qrCode); // .............................................. // ..@@@@@@@@@@@@@@..@@@@@@@@@@..@@@@@@@@@@@@@@.. // ..@@..........@@..@@@@..@@@@..@@..........@@.. // ..@@..@@@@@@..@@....@@@@@@....@@..@@@@@@..@@.. // ..@@..@@@@@@..@@....@@..@@@@..@@..@@@@@@..@@.. // ..@@..@@@@@@..@@..@@......@@..@@..@@@@@@..@@.. // ..@@..........@@..@@..@@......@@..........@@.. // ..@@@@@@@@@@@@@@..@@..@@..@@..@@@@@@@@@@@@@@.. // ..................@@@@@@@@.................... // ..@@@@@@....@@@@..@@@@@@@@@@@@@@@@@@....@@@@.. // ..@@@@@@@@..@@..@@..........@@@@..@@@@@@..@@.. // ..@@......@@..@@@@..@@@@....@@@@..@@......@@.. // ......@@..@@@@..@@........@@@@..@@..@@..@@@@.. // ....@@..@@@@@@@@..@@............@@@@@@..@@@@.. // ..................@@@@@@@@..@@....@@@@@@@@@@.. // ..@@@@@@@@@@@@@@........@@@@..@@..@@..@@..@@.. // ..@@..........@@..@@@@@@@@..@@....@@@@....@@.. // ..@@..@@@@@@..@@....@@..@@@@@@....@@@@..@@.... // ..@@..@@@@@@..@@......@@....@@..@@@@@@........ // ..@@..@@@@@@..@@..@@..........@@..@@..@@@@@@.. // ..@@..........@@..@@......@@.................. // ..@@@@@@@@@@@@@@..@@@@......@@@@@@@@@@....@@.. // .............................................. ``` ### 4. Appendix #### 4.1. Data capacity in bytes
TypeNumber Numeric Alphanumeric Byte Kanji
LMQHLMQHLMQHLMQH
14134271725201610171411710874
27763483447382920322620142016128
31271017758776147355342322432262015
4187149111821149067507862463448382821
5255202144106154122876410684604465523727
632225517813919515410884134106745882654536
737029320715422417812593154122866495755339
846136525920227922115712219215210884118936652
9552432312235335262189143230180130981411118060
106525133642883953112211742712131511191671319374
1177260442733146836625920032125117713719815510985
1288369148937453541929622736728720315522617712596
131022796580427619483352259425331241177262204149109
141101871621468667528376283458362258194282223159120
151250991703530758600426321520412292220320254180136
1614081082775602854656470365586450322250361277198154
1715481212876674938734531408644504364280397310224173
18172513469487461046816574452718560394310442345243191
191903150010638131153909644493792624442338488384272208
202061160011599191249970702557858666482382528410297235
2122321708122496913521035742587929711509403572438314248
222409187213581056146011348236401003779565439618480348270
232620205914681108158812488906721091857611461672528376284
242812218815881228170413269637441171911661511721561407315
2530572395171812861853145110417791273997715535784614440330
26328325441804142519901542109486413671059751593842652462365
27351727011933150121321637117291014651125805625902692496385
28366928572085158122231732126395815281190868658940732534405
2939093035218116772369183913221016162812649086981002778559430
3041583289235817822520199414291080173213709827421066843604457
31441734862473189726772113149911501840145210307901132894634486
32468636932670202228402238161812261952153811128421201947684518
334965390928052157300923691700130720681628116889812731002719553
345253413429492301318325061787139421881722122895813471060756590
355529434330812361335126321867143123031809128398314171113790605
3658364588324425243537278019661530243119111351105114961176832647
3761534775341726253729289420711591256319891423109315771224876673
3864795039359927353927305421811658269920991499113916611292923701
3967435313379129274087322022981774280922131579121917291362972750
40708955963993305742963391242018522953233116631273181714351024784
## Something does not work Feel free to fork project, fix bugs, write tests and finally request for pull