node-qrcode

2025年10月17日 04:30:19
10796
Nodejs 二维码 qrcode

项目结构

📌 node-qrcode soldair/node-qrcode

qr code generator

项目大小 405.44 KB
涉及语言 JavaScript 100.00%
许可协议 MIT License
Gitee Github

node-qrcode

QR code/2d barcode generator.

Travis
npm
npm
npm

Highlights

  • Works on server 并且 client (and react native with svg)
  • 命令行界面 utility
  • 将二维码另存为图像
  • Support for 数值的, 字母, 汉字 and 字节 mode
  • 支持混合模式
  • 支持中文、西里尔文、希腊文和日文字符
  • 支持多字节字符（如表情符号：smile：）
  • 自动生成优化的片段，以实现最佳数据压缩和最小的二维码大小
  • 与应用程序无关的可读性，根据定义，QR 码与应用程序无关

Installation

在项目文件夹中执行以下作：

1
npm install --save qrcode

或者，全局安装以使用 qrcode from the command line to save qrcode images 或者 generate ones you can view in your terminal.

1
npm install -g qrcode

Usage

CLI

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
Usage: qrcode [options] 
 
二维码选项:
  -v, --qversion  QR Code symbol version (1 - 40)                       [number]
  -e, --error     Error correction level           [choices: "L", "M", "Q", "H"]
  -m, --mask      Mask pattern (0 - 7)                                  [number]
 
Renderer options:
  -t, --type        Output type                  [choices: "png", "svg", "utf8"]
  -w, --width       Image width (px)                                    [number]
  -s, --scale       Scale factor                                        [number]
  -q, --qzone       Quiet zone size                                     [number]
  -l, --lightcolor  Light RGBA hex color
  -d, --darkcolor   Dark RGBA hex color
  --small  Output smaller QR code to terminal                          [boolean]
 
选项:
  -o, --output  Output file
  -h, --help    Show help                                              [boolean]
  --version     Show version number                                    [boolean]
 
例s:
  qrcode "some text"                    Draw in terminal window
  qrcode -o out.png "some text"         Save as png image
  qrcode -d F00 -o out.png "some text"  Use red as foreground color

如果 not specified, output type is guessed from file extension.

认可的扩展名是 png, svg and txt.

浏览器

node-qrcode 可以通过模块捆绑器在浏览器中使用，例如Browserify and Webpack 或者通过包含build/ 文件夹。

模块捆绑器

1
2
3
4
5
6
<html>
  <body>
    <canvas id="canvas">canvas>
    <script src="bundle.js">script>
  body>
html>
1
2
3
4
5
6
7
8
// index.js -> bundle.js
var QRCode = require('qrcode')
var canvas = document.getElementById('canvas')
 
QRCode.toCanvas(canvas, 'sample text', function (error) {
  if (error) console.error(error)
  console.log('success!');
})

预编译捆绑包

1
2
3
4
5
6
7
8
9
<canvas id="canvas">canvas>
 
<script src="/build/qrcode.js">script>
<script>
  QRCode.toCanvas(document.getElementById('canvas'), 'sample text', function (error) {
    if (error) console.error(error)
    console.log('success!');
  })
script>

如果您通过 npm，预编译文件将在 node_modules/qrcode/build/ folder.

预编译的捆绑包支持 Internet Explorer 10+, Safari 5.1+，和 all evergreen browsers.

节点JS

需要模块 qrcode

1
2
3
4
5
var QRCode = require('qrcode')
 
QRCode.toDataURL('I am a pony!', function (err, url) {
  console.log(url)
})

为终端渲染 QR 码

1
2
3
4
5
var QRCode = require('qrcode')
 
QRCode.toString('I am a pony!',{type:'terminal'}, function (err, url) {
  console.log(url)
})

ES6/ES7

Promise 和 Async/Await 可用于代替回调函数。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
import QRCode from 'qrcode'
 
// With promises
QRCode.toDataURL('I am a pony!')
  .then(url => {
    console.log(url)
  })
  .catch(err => {
    console.error(err)
  })
 
// With async/await
const generateQR = async text => {
  try {
    console.log(await QRCode.toDataURL(text))
  } catch (err) {
    console.error(err)
  }
}

Error correction level

纠错功能允许成功扫描 QR 码，即使符号脏污或损坏。
根据作环境有四个级别可供选择。

较高的级别提供更好的抗错性，但会降低符号的容量。

如果二维码符号损坏的可能性很低（例如ample，如果它通过显示器显示）
可以安全地使用低误差级别，例如 Low or Medium.

可能的级别如下所示：

水平 抗错性
L （低） ~7%
M （中） ~15%
Q （四分位数） ~25%
H （高） ~30%

百分比表示符号变得不可读的最大损坏表面量。

错误级别可以通过 options.errorCorrectionLevel 财产。

如果未指定，则默认值为 M.

1
2
3
QRCode.toDataURL('some text', { errorCorrectionLevel: 'H' }, function (err, url) {
  console.log(url)
})

QR Code capacity

容量取决于符号版本和纠错级别。此外，编码模式可能会影响可存储数据量。

QR 码版本范围从 1 到版本40.

每个版本都有不同数量的模块（黑点和白点），用于定义符号的大小。
对于版本 1，它们是 21x21，适用于版本 2 25x25 以此类推。
版本越高，可存储数据越多，当然二维码符号也会越大。

下表显示了每种编码模式和每个纠错级别的最大可存储字符数。

Mode L M Q H
Numeric 7089 5596 3993 3057
Alphanumeric 4296 3391 2420 1852
Byte 2953 2331 1663 1273
Kanji 1817 1435 1024 784

注意: 使用时最大字符数可以不同混合模式.

二维码版本可通过 options.version property.

如果未指定版本，则将使用更合适的值。除非需要特定版本，否则不需要此选项。

1
2
3
QRCode.toDataURL('some text', { version: 2 }, function (err, url) {
  console.log(url)
})

编码模式

模式可用于以更有效的方式对字符串进行编码。

根据字符串内容，一种模式可能比其他模式更合适。
支持的模式列表如下表所示：

Mode 字符 压缩
Numeric 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 3 个字符由 10 位表示
Alphanumeric 0–9、A–Z（仅限大写）、空格、$、%、*、+、-, ., /、： 2 个字符由 11 位表示
Kanji 基于 JIS X 0208 的 Shift JIS 系统中的字符 2 个汉字由 13 位表示
Byte ISO/IEC 8859-1 字符集中的字符 每个字符由 8 位表示

如果输入文本未知，选择正确的模式可能会很棘手。

在这些情况下 Byte mode is the best choice since all characters can be encoded with it. (看见 Multibyte characters)

但是，如果二维码阅读器支持混合模式，则使用 自动模式 可能会产生更好的结果。

Mixed modes

混合模式也是可能的。可以从具有不同编码模式的一系列段生成二维码，以优化数据压缩。

但是，从一种模式切换到另一种模式是有代价的，如果不考虑这一点，可能会导致最糟糕的结果。
看 手动模式 有关如何指定具有不同编码模式的段的示例。

Auto mode

由 default，则使用自动模式选择。

输入字符串自动拆分为经过优化的各个段，以使用混合模式生成尽可能短的比特流。

这是生成二维码的首选方式。

例如，字符串 ABCDE12345678?答1A 将分为 3 个部分，具有以下模式：

段 Mode
ABCDE Alphanumeric
12345678 Numeric
?A1A Byte

段和模式的任何其他组合都会导致更长的比特流。

如果您需要保持较小的 QR 码尺寸，此模式将产生最佳结果。

Manual mode

如果自动模式不适合您或您有特定需求，也可以使用相对模式手动指定每个段。
这样，不会在幕后应用任何细分优化。

Segments 列表可以作为对象数组传递：

1
2
3
4
5
6
7
8
9
10
var QRCode = require('qrcode')
 
var segs = [
  { data: 'ABCDEFG', mode: 'alphanumeric' },
  { data: '0123456', mode: 'numeric' }
]
 
QRCode.toDataURL(segs, function (err, url) {
  console.log(url)
})

汉字模式

使用汉字模式，可以以优化的方式对 Shift JIS 系统中的字符进行编码。

不幸的是，没有办法从以 UTF-8 编码的字符计算移位 JIS 值，因此需要一个从输入字符到 SJIS 值的转换表。

默认情况下，此表不包含在捆绑包中，以保持尽可能小的大小。

如果您的应用程序需要汉字支持，您将需要传递一个函数，该函数将负责将输入字符转换为适当的值。

lib 通过一个可选文件提供了一个帮助程序方法，您可以包含该文件，如下面的示例所示。

Note: 仅当您想要从数据压缩中受益时才需要支持汉字模式，否则仍然可以使用字节模式对汉字进行编码（请参阅Multibyte characters).

1
2
3
4
5
6
var QRCode = require('qrcode')
var toSJIS = require('qrcode/helper/to-sjis')
 
QRCode.toDataURL(kanjiString, { toSJISFunc: toSJIS }, function (err, url) {
  console.log(url)
})

使用预编译的捆绑包：

1
2
3
4
5
6
7
8
9
10
11
<canvas id="canvas">canvas>
 
<script src="/build/qrcode.min.js">script>
<script src="/build/qrcode.tosjis.min.js">script>
<script>
  QRCode.toCanvas(document.getElementById('canvas'),
    'sample text', { toSJISFunc: QRCode.toSJIS }, function (error) {
    if (error) console.error(error)
    console.log('success!')
  })
script>

Binary data

QR 码可以保存任意基于字节的二进制数据。如果您尝试通过首先将数据转换为 JavaScript 字符串来创建二进制 QR 码，它将无法对 propery 进行编码，因为字符串编**添加额外的字节。相反，您必须将 Uint8ClampedArray 或兼容数组，或节点Buffer如下：

1
2
3
4
5
6
7
8
9
// Regular array example
// WARNING: Element values will be clamped to 0-255 even if your data contains higher values.
const QRCode = require('qrcode')
QRCode.toFile(
  'foo.png',
  [{ data: [253,254,255], mode: 'byte' }],
  ...options...,
  ...callback...
)
1
2
3
4
5
6
7
8
9
// Uint8ClampedArray example
const QRCode = require('qrcode')
 
QRCode.toFile(
  'foo.png',
  [{ data: new Uint8ClampedArray([253,254,255]), mode: 'byte' }],
  ...options...,
  ...callback...
)
1
2
3
4
5
6
7
8
9
10
// Node Buffer example
// WARNING: Element values will be clamped to 0-255 even if your data contains higher values.
const QRCode = require('qrcode')
 
QRCode.toFile(
  'foo.png',
  [{ data: Buffer.from([253,254,255]), mode: 'byte' }],
  ...options...,
  ...callback...
)

TypeScript 用户：如果您正在使用 @types/qrcode，您需要添加一个 // @ts-ignore 高于数据段，因为它期望data: string.

Multibyte characters

初始 QR 码标准中不支持多字节字符，但可以在字节模式下对 UTF-8 字符进行编码。

QR 码提供了一种通过 ECI（扩展通道解释）指定不同类型字符集的方法，但尚未在此库中完全实现。

然而，即使没有 ECI，大多数 QR 码阅读器也能够识别多字节字符。

请注意，单个汉字/假名或表情符号最多可以占用 4 个字节。

API

浏览器：

服务器：

浏览器 API

create(text, [options])

创建 QR 码符号并返回 qrcode 对象。

text

类型： String|Array

要编码的文本或描述段的对象列表。

options

See QR Code options.

returns

Type: Object

1
2
3
4
5
6
7
8
// QRCode object
{
  modules,              // Bitmatrix class with modules data
  version,              // Calculated QR Code version
  errorCorrectionLevel, // Error Correction Level
  maskPattern,          // Calculated Mask pattern
  segments              // Generated segments
}

toCanvas(canvasElement, text, [options], [cb(error)])

toCanvas(text, [options], [cb(error, canvas)])

绘制二维码符号 canvas.

If canvasElement 省略返回新画布。

canvasElement

Type: DOMElement

画布在哪里绘制二维码。

text

Type: String|Array

Text to encode or a list of objects describing segments.

options

See Options.

cb

Type: Function

完成时调用的回调函数。

Example
1
2
3
4
5
6
QRCode.toCanvas('text', { errorCorrectionLevel: 'H' }, function (err, canvas) {
  if (err) throw err
 
  var container = document.getElementById('container')
  container.appendChild(canvas)
})

toDataURL(text, [options], [cb(error, url)])

toDataURL(canvasElement, text, [options], [cb(error, url)])

返回包含 QR 码图像表示形式的数据 URI。

如果提供， canvasElement 将用作画布来生成数据 URI。

canvasElement

Type: DOMElement

Canvas where to draw QR Code.

text

Type: String|Array

Text to encode or a list of objects describing segments.

options
  • type

    Type: String

    Default: image/png

    数据 URI 格式。

    Possible values are: image/png, image/jpeg, image/webp.

  • rendererOpts.quality

    Type: Number

    Default: 0.92

    之间的数字 0 and 1 如果请求的类型为image/jpeg or image/webp.

See Options 用于其他设置。

cb

Type: Function

Callback function called on finish.

Example
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
var opts = {
  errorCorrectionLevel: 'H',
  type: 'image/jpeg',
  quality: 0.3,
  margin: 1,
  color: {
    dark:"#010599FF",
    light:"#FFBF60FF"
  }
}
 
QRCode.toDataURL('text', opts, function (err, url) {
  if (err) throw err
 
  var img = document.getElementById('image')
  img.src = url
})

toString(text, [options], [cb(error, string)])

返回 QR 码的字符串表示形式。

text

Type: String|Array

Text to encode or a list of objects describing segments.

options
  • type

    Type: String

    Default: utf8

    输出格式。

    Possible values are: terminal,utf8, and svg.

See Options for other settings.

cb

Type: Function

Callback function called on finish.

Example
1
2
3
4
QRCode.toString('http://www.google.com', function (err, string) {
  if (err) throw err
  console.log(string)
})

服务器 API

create(text, [options])

See create.


toCanvas(canvas, text, [options], [cb(error)])

Draws qr code symbol to node canvas.

text

Type: String|Array

Text to encode or a list of objects describing segments.

options

See Options.

cb

Type: Function

Callback function called on finish.


toDataURL(text, [options], [cb(error, url)])

Returns a Data URI containing a representation of the QR Code image.

仅适用于 image/png 键入。

text

Type: String|Array

Text to encode or a list of objects describing segments.

options

See Options for other settings.

cb

Type: Function

Callback function called on finish.


toString(text, [options], [cb(error, string)])

Returns a string representation of the QR Code.

如果选择的输出格式为 svg 它将返回一个包含 XML 代码的字符串。

text

Type: String|Array

Text to encode or a list of objects describing segments.

options
  • type

    Type: String

    Default: utf8

    Output format.

    Possible values are: utf8, svg, terminal.

See Options for other settings.

cb

Type: Function

Callback function called on finish.

Example
1
2
3
4
QRCode.toString('http://www.google.com', function (err, string) {
  if (err) throw err
  console.log(string)
})

toFile(path, text, [options], [cb(error)])

将 QR 码保存到图像文件。

If options.type 未指定，则格式将从文件扩展名中猜测。

Recognized extensions are png, svg, txt.

path

Type: String

保存文件的路径。

text

Type: String|Array

Text to encode or a list of objects describing segments.

options
  • type

    Type: String

    Default: png

    Output format.

    Possible values are: png, svg, utf8.

  • rendererOpts.deflateLevel （仅限 png）

    Type: Number

    Default: 9

    放气的压缩水平。

  • rendererOpts.deflateStrategy (png only)

    Type: Number

    Default: 3

    放气的压缩策略。

See Options for other settings.

cb

Type: Function

Callback function called on finish.

Example
1
2
3
4
5
6
7
8
9
QRCode.toFile('path/to/filename.png', 'Some text', {
  color: {
    dark: '#00F',  // Blue dots
    light: '#0000' // Transparent background
  }
}, function (err) {
  if (err) throw err
  console.log('done')
})

toFileStream(stream, text, [options])

将 QR 码图像写入流媒体。仅适用于 png 格式。

stream

Type: stream.Writable

节点流。

text

Type: String|Array

Text to encode or a list of objects describing segments.

options

See Options.


Options

QR Code options

version

Type: Number

二维码版本。如果未指定，将计算更合适的值。

errorCorrectionLevel

Type: String

Default: M

纠错级别。

Possible values are low, medium, quartile, high or L, M, Q, H.

maskPattern

Type: Number

用于遮罩符号的遮罩图案。

Possible values are 0, 1, 2, 3, 4, 5, 6, 7.

If not specified the more suitable value will be calculated.

toSJISFunc

Type: Function

内部用于将汉字转换为其 Shift JIS 值的辅助函数。

Provide this function if you need support for Kanji mode.

渲染器选项

margin

Type: Number

Default: 4

定义安静区应该有多宽。

scale

Type: Number

Default: 4

比例因子。值 1 表示每个模块 1px（黑点）。

small

Type: Boolean

Default: false

仅与终端渲染器相关。输出较小的二维码。

width

Type: Number

强制输出图像的特定宽度。

If width is too small to contain the qr symbol, this option will be ignored.

Takes precedence over scale.

color.dark

Type: String

违约： #000000ff

深色模块的颜色。值必须为十六进制格式 （RGBA）。

注意：深色应始终深于 color.light.

color.light

Type: String

Default: #ffffffff

灯模块的颜色。值必须为十六进制格式 （RGBA）。


GS1 QR Codes

这里有关于它们的非常好的讨论。但简而言之，任何 QR 码生成器都会制作与 GS1 兼容的 QRCODE，但定义 GS1 QRCode 的是一个带有描述 GS1 信息的元数据的标头。

https://github.com/soldair/node-qrcode/issues/45

Credits

该库基于“QRCode for JavaScript”，幸运的是 Kazuhiko Arase 获得了麻省理工学院的许可。

License

MIT

“QR Code”一词是以下公司的注册商标：

电装波浪公司

免责声明 © 2025 - 虚宝阁

本站部分源码来源于网络，版权归属原开发者，用户仅获得使用权。依据《计算机软件保护条例》第十六条，禁止：

  • 逆向工程破解技术保护措施
  • 未经许可的分发行为
  • 去除源码中的原始版权标识

※ 本站源码仅用于学习和研究，禁止用于商业用途。如有侵权, 请及时联系我们进行处理。

侵权举报请提供： 侵权页面URL | 权属证明模板

响应时效：收到完整材料后48小时内处理

相关推荐

热 榜

scira： AI 驱动搜索引擎

51018

image-compressor： 前端图片压缩库

21018

squish： 基于浏览器的图像压缩工具

9908

AirBattery： 隔空查看苹果设备电量的 Mac 工具

36031

Seelen-UI： 高度可定制的 Windows 桌面美化工具

17024

pyscript： 直接在浏览器中用 Python 创建应用程序

22267

pydoll： 无需 WebDriver 的浏览器自动化 Python 库

14772

pdfplumber： 轻松提取 PDF 文本和表格的 Python 库

24967

暂无数据

友情链接

Github-最大的开源仓库
Github
Gitee-国内开源仓库, github国内镜像仓库
Gitee