Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/cheprasov/js-qrcode
The library is for generating QR codes like SVG, HTML5 Canvas, PNG and JPG files, or text.
https://github.com/cheprasov/js-qrcode
canvas javascript qr qrcode qrcode-generator svg
Last synced: about 1 month ago
JSON representation
The library is for generating QR codes like SVG, HTML5 Canvas, PNG and JPG files, or text.
- Host: GitHub
- URL: https://github.com/cheprasov/js-qrcode
- Owner: cheprasov
- License: mit
- Created: 2019-01-29T22:55:54.000Z (almost 6 years ago)
- Default Branch: master
- Last Pushed: 2023-01-03T16:14:14.000Z (almost 2 years ago)
- Last Synced: 2024-11-06T16:09:47.836Z (about 2 months ago)
- Topics: canvas, javascript, qr, qrcode, qrcode-generator, svg
- Language: JavaScript
- Homepage:
- Size: 1.26 MB
- Stars: 56
- Watchers: 5
- Forks: 9
- Open Issues: 12
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
[](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.
### 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