@ikenxuan/qrcode

基于 Rust qr-code-styling + rxing 的高性能 QR 码生成与扫描工具。通过 WebAssembly 提供高性能核心，Node.js import 即用。

安装

pnpm add @ikenxuan/qrcode

快速开始

import { generate, generateSvg, scan } from '@ikenxuan/qrcode'

// 生成 PNG 二进制
const png = await generate({ data: 'https://example.com' }, 'png')

// 生成 base64 字符串
const b64 = await generate({ data: 'https://example.com' }, 'png', 'base64')

// 生成 SVG 字符串
const svg = await generateSvg({ data: 'https://example.com' })

// 扫描图片中的 QR 码
const result = await scan(png) // 'https://example.com'

WASM 已内联，import 即用，无需初始化，无需关心 .wasm 文件路径。

异步 API 会通过 Node.js 的 worker_threads 执行，避免阻塞主线程。浏览器端请使用 @ikenxuan/qrcode/browser 子路径入口，它不依赖 Node.js 内置模块，并通过浏览器 Web Worker 执行 WASM 计算。

API

generate(options, format, encoding?)

异步生成 QR 码。

| 参数 | 类型 | 说明 | |------|------|------| | options | QRCodeOptions | QR 码配置 | | format | OutputFormat | 输出格式 | | encoding | 'binary' \| 'base64' | 编码方式，默认 'binary' |

返回值为 Promise，resolve 后根据 encoding 自动推导类型：

• 'binary'（默认）→ Uint8Array
• 'base64' → string

generateSvg(options)

异步生成 SVG 字符串，返回 Promise<string>。

scan(imageData)

异步扫描图片中的 QR 码。

| 参数 | 类型 | 说明 | |------|------|------| | imageData | Uint8Array | 图片文件的二进制数据（PNG/JPEG/WebP） |

返回值：Promise<string | null>，解码成功返回 QR 码文本内容，未识别到返回 null。

同步 API

需要同步调用时使用：

• generateSync(options, format, encoding?)
• generateSvgSync(options)
• scanSync(imageData)

浏览器入口

浏览器、React Client Component、Vue SFC 等客户端环境使用：

import { generate, generateSvg, scan } from '@ikenxuan/qrcode/browser'

const png = await generate({ data: location.href }, 'png')
const svg = await generateSvg({ data: location.href })
const text = await scan(png)

QRCodeOptions

interface QRCodeOptions {
  data: string                // 编码内容
  size?: number               // 尺寸（像素），默认 300
  margin?: number             // 外边距（像素）
  shape?: ShapeType           // 整体形状
  dotsOptions?: DotsOptions   // 点阵样式
  cornersSquareOptions?: CornersSquareOptions
  cornersDotOptions?: CornersDotOptions
  backgroundOptions?: BackgroundOptions
  image?: Uint8Array          // Logo 图片数据
  imageOptions?: ImageOptions // Logo 尺寸、留白、圆角与点阵挖空配置
}

可选值

| 类型 | 可选值 | |------|--------| | OutputFormat | 'svg', 'png', 'jpeg', 'webp' | | DotType | 'square', 'dots', 'rounded', 'classy', 'classy-rounded', 'extra-rounded' | | CornerSquareType | 'square', 'dot', 'extra-rounded' | | CornerDotType | 'square', 'dot' | | ShapeType | 'square', 'circle' |

也可以使用常量对象：DotType.Rounded、OutputFormat.Png 等。

ImageOptions

interface ImageOptions {
  imageSize?: number          // Logo 占二维码的比例，默认 0.4，建议不超过 0.25
  margin?: number             // Logo 周围留白像素，默认 0
  round?: number              // Logo 圆角比例 0.0 ~ 0.5，默认 0
  hideBackgroundDots?: boolean // 是否挖空 Logo 下方点阵，默认 true
}

BackgroundOptions

interface BackgroundOptions {
  color?: string        // 背景色，十六进制
  transparent?: boolean // 透明背景
  gradient?: Gradient   // 渐变背景
  round?: number        // 圆角比例 0.0 ~ 0.5
}

示例

import { generate, scan } from '@ikenxuan/qrcode'

// 圆形二维码 + 渐变色 + 透明背景
const png = await generate({
  data: 'https://github.com/ikenxuan',
  size: 400,
  shape: 'circle',
  dotsOptions: {
    dotType: 'dots',
    gradient: { colorFrom: '#667eea', colorTo: '#764ba2' },
  },
  backgroundOptions: { transparent: true },
}, 'png')

// base64 输出，可直接用于 <img src>
const b64 = await generate({
  data: 'https://example.com',
  dotsOptions: { dotType: 'rounded', color: '#1a1a2e' },
}, 'png', 'base64')

// 扫描 QR 码
import { readFileSync } from 'fs'
const img = readFileSync('qrcode.png')
const content = await scan(img) // 'https://example.com'

License

MIT