qr-code-styling-node 1.9.0 → 1.11.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +76 -4
- package/lib/art/art.d.ts +12 -8
- package/lib/core/QRCanvas.d.ts +2 -0
- package/lib/core/QRCodeStyling.d.ts +23 -1
- package/lib/core/QRSVG.d.ts +5 -1
- package/lib/figures/shapes.d.ts +11 -0
- package/lib/index.d.ts +3 -1
- package/lib/qr-code-styling.common.js +1 -1
- package/lib/qr-code-styling.common.js.map +1 -1
- package/lib/qr-code-styling.js +1 -1
- package/lib/qr-code-styling.js.map +1 -1
- package/lib/qr-code-styling.mjs +454 -97
- package/lib/qr-code-styling.mjs.map +4 -4
- package/lib/tools/circle.d.ts +16 -0
- package/lib/tools/cornerTypes.d.ts +2 -0
- package/lib/tools/payloads.d.ts +72 -0
- package/lib/tools/qrArea.d.ts +14 -0
- package/lib/tools/utf8.d.ts +4 -0
- package/lib/types/index.d.ts +25 -3
- package/package.json +4 -2
package/README.md
CHANGED
|
@@ -122,10 +122,25 @@ fontWeight|string or number |`'bold'` |
|
|
|
122
122
|
|
|
123
123
|
<img src="https://raw.githubusercontent.com/ducminhquan/qr-code-styling/master/src/assets/art_examples.png" width="720" />
|
|
124
124
|
|
|
125
|
-
Blend a picture into the code with `art`.
|
|
125
|
+
Blend a picture into the code with `art`. Three modes:
|
|
126
126
|
|
|
127
127
|
- `halftone` (default): the picture is redrawn as fine pixels, with each QR module kept in the middle. Use `colored: true` to keep the picture's colors.
|
|
128
128
|
- `colorize`: dots keep their shape (any `dotsOptions.type`) and are painted with a darkened copy of the picture, over a light copy of it.
|
|
129
|
+
- `blend`: the picture fills the whole image, like an illustration. Dots are drawn only where the picture is not already
|
|
130
|
+
dark or light enough for the code; finders take a dark color from the picture and sit on a light plate.
|
|
131
|
+
Use `placement` to put the code in one part of a larger picture.
|
|
132
|
+
|
|
133
|
+
<img src="https://raw.githubusercontent.com/ducminhquan/qr-code-styling/master/src/assets/blend_examples.png" width="720" />
|
|
134
|
+
|
|
135
|
+
```js
|
|
136
|
+
const qrCode = new QRCodeStyling({
|
|
137
|
+
width: 760,
|
|
138
|
+
height: 300,
|
|
139
|
+
data: "https://example.com",
|
|
140
|
+
dotsOptions: { type: "dots" }, // round dots give round finders in blend mode
|
|
141
|
+
art: { image: "poster.jpg", mode: "blend", placement: { x: 510, y: 40, size: 220 } }
|
|
142
|
+
});
|
|
143
|
+
```
|
|
129
144
|
|
|
130
145
|
```js
|
|
131
146
|
const qrCode = new QRCodeStyling({
|
|
@@ -144,11 +159,58 @@ QR art reads the picture's pixels, so it needs a canvas: it works as is in the b
|
|
|
144
159
|
Property |Type |Default Value|Description
|
|
145
160
|
----------|----------------------------------|-------------|------------------------------------------------------------
|
|
146
161
|
image |string | |The picture (URL or data URL). Required
|
|
147
|
-
mode |string (`'halftone' 'colorize'`)
|
|
162
|
+
mode |string (`'halftone' 'colorize' 'blend'`)|`'halftone'` |How the picture is blended in
|
|
148
163
|
colored |boolean |`false` |halftone: use the picture's colors instead of dots/background colors
|
|
149
164
|
background|boolean |`true` |colorize: show a light copy of the picture behind the dots
|
|
150
|
-
contrast |number (`0 - 1`) |`0.5` halftone, `0.7` colorize|Higher is easier to scan but shows less of the picture
|
|
165
|
+
contrast |number (`0 - 1`) |`0.5` halftone, `0.7` colorize, `0.6` blend|Higher is easier to scan but shows less of the picture
|
|
151
166
|
crossOrigin|string | |Overrides `imageOptions.crossOrigin` for the picture
|
|
167
|
+
placement |object `{ x, y, size }` | |Put the code in this square (in pixels) instead of the middle; the margin is ignored. Mostly for `blend`
|
|
168
|
+
|
|
169
|
+
Always check art codes with `verify()` below: a picture with large mid-grey areas or very small modules
|
|
170
|
+
(under about 7 px) may need a higher `contrast`, a larger size or a higher error correction level.
|
|
171
|
+
|
|
172
|
+
### Round QR codes
|
|
173
|
+
|
|
174
|
+
<img src="https://raw.githubusercontent.com/ducminhquan/qr-code-styling/master/src/assets/circle_examples.png" width="720" />
|
|
175
|
+
|
|
176
|
+
`shape: "circle"` draws a round code. The real code stays square in the middle, with an empty ring around it so
|
|
177
|
+
scanners still find it, and the rest of the circle is filled with decorative dots in the same style. The background
|
|
178
|
+
becomes a circle too. The decoration is the same every time for the same data.
|
|
179
|
+
|
|
180
|
+
```js
|
|
181
|
+
new QRCodeStyling({ data: "https://example.com", shape: "circle", dotsOptions: { type: "rounded" } });
|
|
182
|
+
```
|
|
183
|
+
|
|
184
|
+
A round code uses smaller modules than a square one of the same size, so keep it at least ~240 px for short data and
|
|
185
|
+
check it with `verify()`.
|
|
186
|
+
|
|
187
|
+
### Wi-Fi, contacts, events and more
|
|
188
|
+
|
|
189
|
+
`QRCodeStyling.payload` (also exported as `payload`) builds the text that phones understand. Pass the result as `data`.
|
|
190
|
+
|
|
191
|
+
```js
|
|
192
|
+
const { payload } = QRCodeStyling;
|
|
193
|
+
|
|
194
|
+
payload.wifi({ ssid: "LongChau-Guest", password: "secret" }); // WIFI:T:WPA;S:LongChau-Guest;P:secret;;
|
|
195
|
+
payload.vCard({ firstName: "Quân", lastName: "Nguyễn", phone: "+84900000000", email: "a@example.com" });
|
|
196
|
+
payload.event({ title: "Khai trương", start: "2026-12-01T09:00:00+07:00", end: "2026-12-01T11:00:00+07:00" });
|
|
197
|
+
payload.email({ to: "cskh@example.com", subject: "Hỏi đáp" });
|
|
198
|
+
payload.phone("1800 6928");
|
|
199
|
+
payload.sms({ number: "+84900000000", message: "Xin chào" });
|
|
200
|
+
payload.geo({ latitude: 10.7769, longitude: 106.7009 });
|
|
201
|
+
```
|
|
202
|
+
|
|
203
|
+
Special characters are escaped for each format. Text outside Latin-1 (Vietnamese, emoji...) is encoded as UTF-8.
|
|
204
|
+
|
|
205
|
+
### Sharing on phones
|
|
206
|
+
|
|
207
|
+
`share()` opens the phone's share sheet with the code as an image (Web Share API), so people can send it to a chat
|
|
208
|
+
app or save it to Photos. Where sharing files is not supported, it downloads the file instead.
|
|
209
|
+
|
|
210
|
+
```js
|
|
211
|
+
const result = await qrCode.share({ name: "wifi", extension: "png", title: "Wi-Fi Long Châu" });
|
|
212
|
+
// "shared", "cancelled" or "downloaded"
|
|
213
|
+
```
|
|
152
214
|
|
|
153
215
|
### Checking that a code scans
|
|
154
216
|
|
|
@@ -185,6 +247,7 @@ Property |Type |Default Value|Description
|
|
|
185
247
|
width |number |`300` |Size of canvas
|
|
186
248
|
height |number |`300` |Size of canvas
|
|
187
249
|
type |string (`'canvas' 'svg'`)|`canvas` |The type of the element that will be rendered
|
|
250
|
+
shape |string (`'square' 'circle'`)|`'square'` |`'circle'` draws a round code with decorative dots around the real one
|
|
188
251
|
data |string | |The date will be encoded to the QR code
|
|
189
252
|
image |string | |The image will be copied to the center of the QR code
|
|
190
253
|
margin |number |`0` |Margin around canvas
|
|
@@ -229,7 +292,7 @@ Property|Type
|
|
|
229
292
|
--------|------------------------------------------------------------------------------|-------------|-------------------
|
|
230
293
|
color |string |`'#000'` |Color of QR dots
|
|
231
294
|
gradient|object | |Gradient of QR dots
|
|
232
|
-
type |string (`'rounded' 'dots' 'classy' 'classy-rounded' 'square' 'extra-rounded' 'diamond' 'small-square' 'vertical-lines' 'horizontal-lines'`)|`'square'` |Style of QR dots. With the
|
|
295
|
+
type |string (`'rounded' 'dots' 'classy' 'classy-rounded' 'square' 'extra-rounded' 'diamond' 'small-square' 'vertical-lines' 'horizontal-lines' 'fluid'`)|`'square'` |Style of QR dots. With `diamond`, `small-square` and the lines, corners and alignment patterns stay solid unless you set a corner type. `fluid` joins neighbouring dots into soft strokes, with solid rounded corners
|
|
233
296
|
|
|
234
297
|
`options.backgroundOptions` structure
|
|
235
298
|
|
|
@@ -305,6 +368,15 @@ Param |Type |Description
|
|
|
305
368
|
decoder|function|A QR decoder with the jsQR signature `(rgba, width, height) => { data } \| null`
|
|
306
369
|
adjust |boolean |For QR art: raise `art.contrast` until the code scans. Default `false`
|
|
307
370
|
|
|
371
|
+
`QRCodeStyling.share({ name, extension, title, text }) => Promise<'shared' | 'cancelled' | 'downloaded'>`
|
|
372
|
+
|
|
373
|
+
Param |Type |Default Value|Description
|
|
374
|
+
---------|------------------------------------|-------------|------------
|
|
375
|
+
name |string |`'qr'` |File name, without extension
|
|
376
|
+
extension|string (`'png' 'jpeg' 'webp' 'svg'`)|`'png'` |File type
|
|
377
|
+
title |string | |Title for the share sheet
|
|
378
|
+
text |string | |Text for the share sheet
|
|
379
|
+
|
|
308
380
|
`QRCodeStyling.update(options) => void`
|
|
309
381
|
|
|
310
382
|
Param |Type |Description
|
package/lib/art/art.d.ts
CHANGED
|
@@ -13,12 +13,7 @@ export interface ArtRect {
|
|
|
13
13
|
width: number;
|
|
14
14
|
height: number;
|
|
15
15
|
color: string;
|
|
16
|
-
|
|
17
|
-
export interface QRArea {
|
|
18
|
-
count: number;
|
|
19
|
-
dotSize: number;
|
|
20
|
-
x: number;
|
|
21
|
-
y: number;
|
|
16
|
+
shape?: "rect" | "circle";
|
|
22
17
|
}
|
|
23
18
|
export interface HalftoneArt {
|
|
24
19
|
mode: "halftone";
|
|
@@ -31,11 +26,21 @@ export interface ColorizeArt {
|
|
|
31
26
|
/** Full-size canvas holding a light copy of the picture, drawn behind the dots (when art.background). */
|
|
32
27
|
background?: Canvas;
|
|
33
28
|
}
|
|
34
|
-
export
|
|
29
|
+
export interface BlendArt {
|
|
30
|
+
mode: "blend";
|
|
31
|
+
/** Full-size canvas with the picture, drawn behind everything. */
|
|
32
|
+
picture: Canvas;
|
|
33
|
+
/** Light plates behind the finders, then the dots that correct the picture. */
|
|
34
|
+
rects: ArtRect[];
|
|
35
|
+
/** Dark color picked from the picture around each finder (top-left, top-right, bottom-left). */
|
|
36
|
+
finderColors: string[];
|
|
37
|
+
}
|
|
38
|
+
export type PreparedArt = HalftoneArt | ColorizeArt | BlendArt;
|
|
35
39
|
/** Default contrast per mode: colorize keeps the dot shapes, so it needs more contrast to scan reliably. */
|
|
36
40
|
export declare const DEFAULT_CONTRAST: {
|
|
37
41
|
halftone: number;
|
|
38
42
|
colorize: number;
|
|
43
|
+
blend: number;
|
|
39
44
|
};
|
|
40
45
|
export declare const getContrast: (art: ArtOptions) => number;
|
|
41
46
|
/** Luminance limits for "dark" and "light" pixels at a given contrast. */
|
|
@@ -46,6 +51,5 @@ export declare const getLimits: (contrast: number) => {
|
|
|
46
51
|
export declare const toDark: (color: RGB, limit: number) => RGB;
|
|
47
52
|
export declare const toLight: (color: RGB, limit: number) => RGB;
|
|
48
53
|
export declare function createCanvas(options: RequiredOptions, width: number, height: number): Canvas;
|
|
49
|
-
export declare function getQRArea(options: RequiredOptions, count: number): QRArea;
|
|
50
54
|
export declare function prepareArt(options: RequiredOptions, qr: QRCode, filter: FilterFunction): Promise<PreparedArt>;
|
|
51
55
|
export {};
|
package/lib/core/QRCanvas.d.ts
CHANGED
|
@@ -8,6 +8,8 @@ export default class QRCanvas {
|
|
|
8
8
|
_image?: HTMLImageElement;
|
|
9
9
|
/** Fill used for the dots instead of their color (QR art "colorize"). */
|
|
10
10
|
_dotsFill?: CanvasPattern;
|
|
11
|
+
/** Per-finder colors used when corners have no color of their own (QR art "blend"). */
|
|
12
|
+
_finderColors?: string[];
|
|
11
13
|
constructor(options: RequiredOptions);
|
|
12
14
|
get context(): CanvasRenderingContext2D | null;
|
|
13
15
|
get width(): number;
|
|
@@ -1,8 +1,24 @@
|
|
|
1
1
|
import QRCanvas from "./QRCanvas";
|
|
2
2
|
import QRSVG from "./QRSVG";
|
|
3
3
|
import { RequiredOptions } from "./QROptions";
|
|
4
|
-
import { Extension, QRCode, Options, DownloadOptions, VerifyOptions, VerifyResult } from "../types";
|
|
4
|
+
import { Extension, QRCode, Options, DownloadOptions, VerifyOptions, VerifyResult, ShareOptions } from "../types";
|
|
5
5
|
export default class QRCodeStyling {
|
|
6
|
+
/** Builders for Wi-Fi, contact, event, e-mail, phone, SMS and location codes: pass the result as `data`. */
|
|
7
|
+
static payload: {
|
|
8
|
+
wifi: typeof import("../tools/payloads").wifi;
|
|
9
|
+
vCard: typeof import("../tools/payloads").vCard;
|
|
10
|
+
event: typeof import("../tools/payloads").event;
|
|
11
|
+
email: typeof import("../tools/payloads").email;
|
|
12
|
+
phone: (number: string) => string;
|
|
13
|
+
sms: ({ number, message }: {
|
|
14
|
+
number: string;
|
|
15
|
+
message?: string;
|
|
16
|
+
}) => string;
|
|
17
|
+
geo: ({ latitude, longitude }: {
|
|
18
|
+
latitude: number;
|
|
19
|
+
longitude: number;
|
|
20
|
+
}) => string;
|
|
21
|
+
};
|
|
6
22
|
_options: RequiredOptions;
|
|
7
23
|
_container?: HTMLElement;
|
|
8
24
|
_canvas?: QRCanvas;
|
|
@@ -43,4 +59,10 @@ export default class QRCodeStyling {
|
|
|
43
59
|
verify({ decoder, adjust }: VerifyOptions): Promise<VerifyResult>;
|
|
44
60
|
getRawData(extension?: Extension): Promise<Blob | Buffer | null>;
|
|
45
61
|
download(downloadOptions?: Partial<DownloadOptions> | string): Promise<void>;
|
|
62
|
+
/**
|
|
63
|
+
* Opens the phone's share sheet with the QR code as a file (Web Share API). Where sharing files is not
|
|
64
|
+
* supported (most desktop browsers), downloads it instead. Resolves to "shared", "downloaded", or
|
|
65
|
+
* "cancelled" when the user closes the share sheet.
|
|
66
|
+
*/
|
|
67
|
+
share(shareOptions?: ShareOptions): Promise<"shared" | "downloaded" | "cancelled">;
|
|
46
68
|
}
|
package/lib/core/QRSVG.d.ts
CHANGED
|
@@ -17,6 +17,8 @@ export default class QRSVG {
|
|
|
17
17
|
_virtual: boolean;
|
|
18
18
|
/** Image used to paint the dots instead of their color (QR art "colorize"). */
|
|
19
19
|
_dotsImageHref?: string;
|
|
20
|
+
/** Per-finder colors used when corners have no color of their own (QR art "blend"). */
|
|
21
|
+
_finderColors?: string[];
|
|
20
22
|
constructor(options: RequiredOptions, sharedWindow?: Window);
|
|
21
23
|
get width(): number;
|
|
22
24
|
get height(): number;
|
|
@@ -39,8 +41,10 @@ export default class QRSVG {
|
|
|
39
41
|
count: number;
|
|
40
42
|
dotSize: number;
|
|
41
43
|
}): void;
|
|
42
|
-
_createColor({ options, color, additionalRotation, x, y, height, width, name, imageHref }: {
|
|
44
|
+
_createColor({ options, color, additionalRotation, x, y, height, width, name, imageHref, radius }: {
|
|
43
45
|
imageHref?: string;
|
|
46
|
+
/** Rounds the rect's corners (a circle when it is half the size). */
|
|
47
|
+
radius?: number;
|
|
44
48
|
options?: Gradient;
|
|
45
49
|
color?: string;
|
|
46
50
|
additionalRotation: number;
|
package/lib/figures/shapes.d.ts
CHANGED
|
@@ -37,3 +37,14 @@ export declare const roundedRect: (x: number, y: number, width: number, height:
|
|
|
37
37
|
/** Finder ring with rounded corners: outer square minus inner square (even-odd). */
|
|
38
38
|
export declare const roundedRing: (x: number, y: number, size: number) => Shape;
|
|
39
39
|
export declare const roundedSquare: (x: number, y: number, size: number) => Shape;
|
|
40
|
+
/**
|
|
41
|
+
* "fluid" dot: a rounded square that flows into its dark neighbours, so runs of modules read as
|
|
42
|
+
* soft connected strokes and a lone module is a circle. Arms stay inside the module's own cell,
|
|
43
|
+
* so neighbouring shapes touch but never overlap.
|
|
44
|
+
*/
|
|
45
|
+
export declare const fluid: (x: number, y: number, size: number, neighbors: {
|
|
46
|
+
left: boolean;
|
|
47
|
+
right: boolean;
|
|
48
|
+
top: boolean;
|
|
49
|
+
bottom: boolean;
|
|
50
|
+
}) => Shape;
|
package/lib/index.d.ts
CHANGED
|
@@ -7,6 +7,8 @@ import errorCorrectionPercents from "./constants/errorCorrectionPercents";
|
|
|
7
7
|
import modes from "./constants/modes";
|
|
8
8
|
import qrTypes from "./constants/qrTypes";
|
|
9
9
|
import drawTypes from "./constants/drawTypes";
|
|
10
|
+
import payload from "./tools/payloads";
|
|
10
11
|
export * from "./types";
|
|
11
|
-
export {
|
|
12
|
+
export type { WifiOptions, VCardOptions, EventOptions } from "./tools/payloads";
|
|
13
|
+
export { dotTypes, cornerDotTypes, cornerSquareTypes, errorCorrectionLevels, errorCorrectionPercents, modes, qrTypes, drawTypes, payload };
|
|
12
14
|
export default QRCodeStyling;
|