@akamfoad/qrcode
v0.3.2
Published
The library is generating QR codes as SVG, HTML5 Canvas, PNG and JPG files, or text.
Downloads
872
Maintainers
Readme
@akamfoad/qrcode
The library is for generating QR codes like SVG, HTML5 Canvas, PNG and JPG files, or text.
Acknowledgment
This project initially has been forked from @cheprasov/js-qrcode.
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
)- 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
- Allows to specify relative/abcolute position/size of image on QR code.
Canvas (see 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
)- 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.
TypeDocs
https://akamfoad.github.io/qrcode/
1. How to install
> npm install @akamfoad/qrcode
import {
QRCodeRaw,
QRCodeSVG,
QRCodeCanvas,
QRCodeText,
} from '@akamfoad/qrcode';
2. Quick examples
2.1. Create SVG QR Code
import { QRCodeSVG } from '@akamfoad/qrcode';
const qrSVG = new QRCodeSVG('some value for QR code');
const dataUrlWithSVGQRCode = qrSVG.toDataUrl();
const xmlWithQRCode = qrSVG.toString();
2.2. Create Image QR Code
import { QRCodeCanvas } from '@akamfoad/qrcode';
const qrCanvas = new QRCodeCanvas('some value for QR code');
const dataUrlWithQRCode = qrCanvas.toDataUrl();
const canvasWithQRCode = qrCanvas.getCanvas();
2.3. QR Code with Image
import { QRCodeSVG } from '@akamfoad/qrcode';
const divElement = document.getElementById('some-id');
const qrSVG = new QRCodeSVG('JohnDoe', {
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.
import { QRCodeRaw } from '@akamfoad/qrcode';
Public methods:
constructor(value: string, config: object)
Create new instance of QRCodeRaw
Params:
value
(string) - new value for encoding to QR codeconfig
(object, optional) - parameters of configurationlevel
(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 lossM
- Allows recovery of up to 15% data lossQ
- Allows recovery of up to 25% data lossH
- Allows recovery of up to 30% data loss
typeNumber
(number, optional, default =0
) - data capacity type, see details in appendix 4.1. Type number (1
~40
), or0
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 returnnull
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:
import { QRCodeRaw } from '@akamfoad/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
, therefore please see there description about public method and configuration params.
import { QRCodeCanvas } from '@akamfoad/qrcode';
Public methods:
constructor(value: string, config: object)
Create new instance of QRCodeCanvas. Please see config description of QRCodeRaw.constructor
.
Config has additional parameters:
config
(object, optional) - parameters of configuration- see config of
QRCodeRaw.constructor
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 offgColor
.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 schemeimage
(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:<number>
- defines the width of image, example:width: 30
<number>%
- defines the width in percent of QR code without padding, example:width: '20%'
height
(number|string) - height of the image in QR code dots, seewidth
x
(number|string, optional, default =0
) - position of image on QR code by horizontal in QR code dots (not a pixel), allowed formats:<number>
- sets the left edge position from left to right, example:x: 10
<number>%
- 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 <number>
- the same as<number>
left <number>%
- the same as<number>%
right <number>
- sets the right edge position from right to left, example:x: 'right 5'
right <number>%
- 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:<number>
- sets the top edge position from top to bottom, example:y: 10
<number>%
- 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 <number>
- the same as<number>
top <number>%
- the same as<number>%
bottom <number>
- sets the bottom edge position from bottom to top, example:y: 'bottom 5'
bottom <number>%
- 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
- use
- see config of
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
import { QRCodeCanvas } from '@akamfoad/qrcode';
const qrCanvas = new QRCodeCanvas('some value');
const dataUrl = qrCanvas.toDataUrl();
console.log(dataUrl); // data:image/png;base64,iVBORw0KGgoAAAA...g==
Example with promise
import { QRCodeCanvas } from '@akamfoad/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
, therefore please see there description about public method and configuration params.
import { QRCodeSVG } from '@akamfoad/qrcode';
Public methods:
constructor(value: string, config: object)
Create new instance of QRCodeSVG. Please see config description of QRCodeRaw.constructor
.
Config has additional parameters:
config
(object, optional) - parameters of configuration- see config of
QRCodeRaw.constructor
fgColor
(string, optional, default =#000
) - foreground color of the QR code in CSS formatbgColor
(string, optional, default =#FFF
) - background color of the QR code in CSS formatimage
(object, optional, default =null
) - parameters on an image, that should be added to QR code, like logo. See image schemesource
(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:<number>
- defines the width of image, example:width: 30
<number>%
- defines the width in percent of QR code without padding, example:width: '20%'
height
(number|string) - height of the image in QR code dots, seewidth
x
(number|string, optional, default =0
) - position of image on QR code by horizontal in QR code dots (not a pixel), allowed formats:<number>
- sets the left edge position from left to right, example:x: 10
<number>%
- 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 <number>
- the same as<number>
left <number>%
- the same as<number>%
right <number>
- sets the right edge position from right to left, example:x: 'right 5'
right <number>%
- 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:<number>
- sets the top edge position from top to bottom, example:y: 10
<number>%
- 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 <number>
- the same as<number>
top <number>%
- the same as<number>%
bottom <number>
- sets the bottom edge position from bottom to top, example:y: 'bottom 5'
bottom <number>%
- 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
- use
- see config of
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
import { QRCodeSVG } from '@akamfoad/qrcode';
const qrSVG = new QRCodeSVG('some value');
const dataUrl = qrSVG.toDataUrl();
console.log(dataUrl); // data:image/png;base64,iVBORw0KGgoAAAA...g==
Example with image
import { QRCodeSVG } from '@akamfoad/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:
// <svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" version="1.1" shape-rendering="crispEdges" viewBox="0 0 21 21">
// <rect x="0" y="0" height="21" width="21" fill="#FFF"/>
// <rect x="0" y="0" height="1" width="7" fill="#000"/>
// <rect x="9" y="0" height="1" width="2" fill="#000"/>
// ...
// <image xlink:href="https://some-url.com/foo.png" x="10" y="10" width="2" height="2"/>
// </svg>
3.4. class QRCodeText
The class creates QR code as text. It is possible to show QR code in terminal.
The class extends QRCodeRaw
, therefore please see there description about public method and configuration params.
import { QRCodeSVG } from '@akamfoad/qrcode';
Public methods:
constructor(value: string, config: object)
Create new instance of QRCodeSVG. Please see config description of QRCodeRaw.constructor
.
Config has additional parameters:
config
(object, optional) - parameters of configuration- see config of
QRCodeRaw.constructor
blackSymbol
(string, optional, default =▓▓
) - symbol(s) for black QR code dot.whiteSymbol
(string, optional, default =▓▓
) - symbol(s) for white QR code dot.
- see config of
toString(): null | string
Returns QR code as string. If QR code can not be generated then null
will be returned.
Example
import { QRCodeText } from '@akamfoad/qrcode';
const qrText = new QRCodeText('some value', {
blackSymbol: '@@',
whiteSymbol: '..',
});
const qrCode = qrText.toString();
console.log(qrCode);
// ..............................................
// ..@@@@@@@@@@@@@@..@@@@@@@@@@..@@@@@@@@@@@@@@..
// ..@@..........@@..@@@@..@@@@..@@..........@@..
// ..@@..@@@@@@..@@....@@@@@@....@@..@@@@@@..@@..
// ..@@..@@@@@@..@@....@@..@@@@..@@..@@@@@@..@@..
// ..@@..@@@@@@..@@..@@......@@..@@..@@@@@@..@@..
// ..@@..........@@..@@..@@......@@..........@@..
// ..@@@@@@@@@@@@@@..@@..@@..@@..@@@@@@@@@@@@@@..
// ..................@@@@@@@@....................
// ..@@@@@@....@@@@..@@@@@@@@@@@@@@@@@@....@@@@..
// ..@@@@@@@@..@@..@@..........@@@@..@@@@@@..@@..
// ..@@......@@..@@@@..@@@@....@@@@..@@......@@..
// ......@@..@@@@..@@........@@@@..@@..@@..@@@@..
// ....@@..@@@@@@@@..@@............@@@@@@..@@@@..
// ..................@@@@@@@@..@@....@@@@@@@@@@..
// ..@@@@@@@@@@@@@@........@@@@..@@..@@..@@..@@..
// ..@@..........@@..@@@@@@@@..@@....@@@@....@@..
// ..@@..@@@@@@..@@....@@..@@@@@@....@@@@..@@....
// ..@@..@@@@@@..@@......@@....@@..@@@@@@........
// ..@@..@@@@@@..@@..@@..........@@..@@..@@@@@@..
// ..@@..........@@..@@......@@..................
// ..@@@@@@@@@@@@@@..@@@@......@@@@@@@@@@....@@..
// ..............................................
4. Appendix
4.1. Data capacity in bytes
Something does not work
Feel free to fork project, fix bugs, write tests and finally request for pull