QrCode.js 技术文档：二维码生成与导出工具类

news2025/1/19 9:23:32

概述

QrCode.js 是一个用于生成和导出二维码的 JavaScript 工具类，支持多种样式的二维码生成与导出功能。它依赖于以下主要外部库：

qrcode：用于生成基础二维码图像。
html-to-image：将 HTML 元素转换为图片。
jszip：用于创建压缩包。
file-saver：用于触发文件下载。

本文档详细说明了 QrCode.js 提供的主要功能和使用方法。

import { toCanvas as toQrCodeCanvas } from 'qrcode'
import { toCanvas } from 'html-to-image'
import JSZip from 'jszip'
import FileSaver from 'file-saver'

export class QrCode {
  // 二维码样式
  // 导出二维码压缩文件类型
  static picTypeName = ['简洁二维码', '详情二维码', '专业二维码']

  // 创建一个二维码简洁实例
  static createSimpleQrCodeCanvas(text, options) {
    return toQrCodeCanvas(text, { errorCorrectionLevel: 'H', width: 240, height: 240, margin: 2, ...options })
  }

  // 创建一个自定义二维码实例
  static async createdCustomQrCodeCanvas(text, selfEl, backgroundColor = '#28313f') {
    const pixelRatio = window.devicePixelRatio || 1
    const qr = await QrCode.createSimpleQrCodeCanvas(text)
    let createQrDiv = document.createElement('div')
    const containerWidth = Math.max(selfEl.clientWidth + 20, 260)
    createQrDiv.style.width = containerWidth + 'px'
    createQrDiv.style.padding = '260px 10px 10px'
    createQrDiv.style.textAlign = 'center'
    createQrDiv.appendChild(selfEl.cloneNode(true))
    document.body.appendChild(createQrDiv)
    const canvas = await toCanvas(createQrDiv, { backgroundColor, skipFonts: true, pixelRatio })
    const ctx = canvas.getContext('2d')
    ctx.drawImage(qr, ((containerWidth - 240) / 2) * pixelRatio, 10 * pixelRatio, 240 * pixelRatio, 240 * pixelRatio)
    createQrDiv.remove()
    return canvas
  }

  /**
   * 压缩包压缩文件导出
   * @param {*} pics {file: 压缩的文件图片,folder:"所属文件夹", fileName:'文件名称'}
   * @param {*} zipName
   */
  static downloadZip(pics, zipName = window.$t('compressedPackage')) {
    const zip = new JSZip()
    for (let index = 0; index < pics.length; index++) {
      const pic = pics[index]
      zip.file(`${pic.folder ? pic.folder + '/' : ''}${pic.fileName}.png`, pic.file) // 文件夹下文件的名字
    }
    zip.generateAsync({ type: 'blob' }).then(content => {
      FileSaver.saveAs(content, `${zipName}.zip`)
    })
  }

  // 生成图片Blob
  static async canvasToBlob(canvas) {
    return new Promise(resolve => {
      canvas.toBlob(resolve)
    })
  }

  // 导出图片
  static downloadImage(base64Url, fileName) {
    let imgUrl = base64Url
    if (window.navigator.msSaveOrOpenBlob) {
      // 兼容IE浏览器的写法
      let imageStr = atob(imgUrl.split(',')[1])
      let n = imageStr.length
      let u8arr = new Uint8Array(n)
      while (n--) {
        u8arr[n] = imageStr.charCodeAt(n)
      }
      let blob = new Blob([u8arr])
      window.navigator.msSaveOrOpenBlob(blob, `${fileName}.png`)
    } else {
      // 非IE浏览器
      let a = document.createElement('a')
      a.href = imgUrl
      a.setAttribute('download', fileName)
      a.click()
    }
  }

  static blobDownloadImage(blob, fileName = 'chart-download.png') {
    if (window.navigator && window.navigator.msSaveOrOpenBlob) {
      window.navigator.msSaveOrOpenBlob(blob, fileName)
    } else {
      const url = URL.createObjectURL(blob)
      const link = document.createElement('a')
      link.href = url
      link.download = fileName
      document.body.appendChild(link)
      link.click()
      document.body.removeChild(link)
      URL.revokeObjectURL(url)
    }
  }
}

类与方法

静态属性

picTypeName
- 描述：二维码样式的名称列表。
- 默认值：[window.$t('conciseQRCode'), window.$t('detailsQRCode'), window.$t('professionalQRCode')]。
- 用途：表示不同风格的二维码类型。

静态方法

1. `createSimpleQrCodeCanvas(text, options)`

描述：创建一个简洁的二维码实例。
参数：
- text (string)：需要编码的文本内容。
- options (object)：二维码配置选项（可选）。
  - 默认选项：{ errorCorrectionLevel: 'H', width: 240, height: 240, margin: 2 }。
返回值：Promise<HTMLCanvasElement>，包含二维码的 Canvas 实例。

示例：

const canvas = await QrCode.createSimpleQrCodeCanvas('Hello World!');
document.body.appendChild(canvas);

2. `createdCustomQrCodeCanvas(text, selfEl, backgroundColor = '#28313f')`

描述：创建一个自定义样式的二维码。
参数：
- text (string)：需要编码的文本内容。
- selfEl (HTMLElement)：需要嵌入的自定义 DOM 元素。
- backgroundColor (string)：背景颜色，默认为 #28313f。
返回值：Promise<HTMLCanvasElement>，包含自定义二维码的 Canvas 实例。

示例：

const customCanvas = await QrCode.createdCustomQrCodeCanvas('Hello World!', document.getElementById('customElement'));
document.body.appendChild(customCanvas);

3. `downloadZip(pics, zipName)`

描述：将图片文件打包成 ZIP 并下载。
参数：
- pics (Array)：图片文件数组。
  - 每个图片对象包含以下属性：
    - file (Blob)：图片文件内容。
    - folder (string)：图片所属文件夹名称（可选）。
    - fileName (string)：图片文件名称。
- zipName (string)：ZIP 文件名称，默认为 window.$t('compressedPackage')。

示例：

QrCode.downloadZip([
  { file: imageBlob1, folder: 'folder1', fileName: 'image1' },
  { file: imageBlob2, fileName: 'image2' }
], 'MyQRCodeImages');

4. `canvasToBlob(canvas)`

描述：将 Canvas 转换为 Blob 对象。
参数：
- canvas (HTMLCanvasElement)：需要转换的 Canvas 元素。
返回值：Promise<Blob>。

示例：

const blob = await QrCode.canvasToBlob(myCanvas);

5. `downloadImage(base64Url, fileName)`

描述：导出图片（支持 IE 浏览器）。
参数：
- base64Url (string)：图片的 Base64 编码地址。
- fileName (string)：下载的文件名。

示例：

QrCode.downloadImage(base64String, 'myImage');

6. `blobDownloadImage(blob, fileName)`

描述：通过 Blob 对象下载图片。
参数：
- blob (Blob)：图片的 Blob 对象。
- fileName (string)：下载的文件名，默认为 chart-download.png。

示例：

QrCode.blobDownloadImage(myBlob, 'downloadedImage.png');

依赖安装

在使用 QrCode.js 前，请确保已安装以下依赖：

npm install qrcode html-to-image jszip file-saver

使用示例

示例 1：生成简洁二维码

import { QrCode } from './QrCode';

(async () => {
  const canvas = await QrCode.createSimpleQrCodeCanvas('Hello World!');
  document.body.appendChild(canvas);
})();

示例 2：生成自定义二维码并导出

import { QrCode } from './QrCode';

(async () => {
  const customCanvas = await QrCode.createdCustomQrCodeCanvas(
    'Custom QR Code',
    document.getElementById('customElement')
  );
  document.body.appendChild(customCanvas);

  const blob = await QrCode.canvasToBlob(customCanvas);
  QrCode.blobDownloadImage(blob, 'customQRCode.png');
})();

示例 3：批量导出二维码为 ZIP 文件

import { QrCode } from './QrCode';

(async () => {
  const canvas1 = await QrCode.createSimpleQrCodeCanvas('QR1');
  const canvas2 = await QrCode.createSimpleQrCodeCanvas('QR2');

  const blob1 = await QrCode.canvasToBlob(canvas1);
  const blob2 = await QrCode.canvasToBlob(canvas2);

  QrCode.downloadZip([
    { file: blob1, fileName: 'QR1' },
    { file: blob2, fileName: 'QR2' }
  ], 'QRCodeCollection');
})();