yx-qrcode

v1.0.1

Published

3 months ago

一个功能强大的二维码生成器，支持多种样式、渐变、码眼自定义等特性

0High
0Medium
0Low

zongxy

qrcode qr-code generator svg 二维码二维码生成器

@impression/qrcode-generator

一个功能强大的二维码生成器库，支持多种样式、渐变、码眼自定义、Logo嵌入、背景图片等特性。

特性

🎨 支持多种码眼样式（20+种）
🌈 支持线性渐变和径向渐变
🎯 支持码眼外圈和中心独立颜色设置
📐 支持自定义模块大小、边距、缩放
🖼️ 支持背景图片和二维码镂空背景图片
🏷️ 支持Logo嵌入（自动添加圆角和白边）
🔧 TypeScript 支持
📦 零依赖（除核心编码库）

安装

npm install qrcode-generator

快速开始

import { createQrcode } from '@impression/qrcode-generator';

// 基础用法
const svg = await createQrcode('Hello World', {
  moduleSize: 10,
  color: '#1976d2',
  background: '#ffffff'
});

// 使用渐变
const svg = await createQrcode('Hello World', {
  colorGradient: 'to right #ff6600 #ff0066',
  background: '#ffffff'
});

// 自定义码眼样式
const svg = await createQrcode('Hello World', {
  finderShape: 'circle',
  eyeShape: 'star',
  color: '#000000',
  background: '#ffffff'
});

// 添加Logo
const svg = await createQrcode('Hello World', {
  logo: {
    href: 'https://example.com/logo.png',
    width: 100,
    height: 100
  },
  level: 'H' // 使用Logo时建议使用高纠错级别
});

API 文档

createQrcode(text, config)

生成二维码并返回 SVG 字符串。

参数

text (string): 要编码的文本内容
config (Partial): 配置对象

完整配置参数说明

基础参数

`level`

类型: 'L' | 'M' | 'Q' | 'H'
默认值: 'L'
说明: 二维码纠错等级
- 'L': 低纠错能力（~7%），适用于小数据量、无遮挡场景
- 'M': 中纠错能力（~15%），适用于一般场景
- 'Q': 较高纠错能力（~25%），适用于中等遮挡场景
- 'H': 高纠错能力（~30%），适用于强遮挡场景（如添加Logo时）
注意: 使用Logo时会自动设置为 'Q' 或 'H'

`moduleSize`

类型: number
默认值: 10
说明: 每个模块（单元格）在输出 SVG 中的像素大小（px）
取值范围: 任意正数，建议 5-20
示例: 设置为 20 会使二维码尺寸翻倍

`margin`

类型: number
默认值: 0
说明: 二维码四周留白（模块数计），不是像素
取值范围: 0-10，建议 0-4
计算: 实际像素边距 = margin × moduleSize
注意: 扫码器通常要求有一定空白，建议最小值为 1

`scale`

类型: number
默认值: 1.0
说明: 二维码整体放大倍数
取值范围: 任意正数，建议 0.5-5.0
示例:
- 2.0: 放大 2 倍
- 0.5: 缩小一半
注意: 会同时影响 moduleSize 和 margin

`dotScale`

类型: number
默认值: 1.0
说明: 数据点内部缩放因子
取值范围: 0.1-1.0，建议 0.6-1.0
示例: 0.8 表示圆点和连接部分缩小到 80%
适用场景: 主要用于 special-circle-orizontal 等需要保持连接的样式

颜色参数

`color`

类型: string
默认值: '#000000'
说明: 模块（前景/主色）颜色
支持格式:
- 十六进制: '#ff0000'
- RGB: 'rgb(255, 0, 0)'
- 颜色名: 'red'
注意: 如果使用 colorGradient，此参数会被覆盖

`colorGradient`

类型: string
默认值: ''（空字符串，不使用渐变）
说明: 前景渐变（线性或径向）
支持格式:
1. 线性渐变：'to <direction> <color1> <color2> [color3...]'
  - 方向可选值：right | left | top | bottom
  - 示例：
    - 'to right #ff0000 #00ff00' - 从左到右，红色到绿色
    - 'to bottom #ff0000 #00ff00 #0000ff' - 从上到下，三色渐变
2. 径向渐变：'radial <color1> <color2> [color3...]'
  - 示例：'radial #ff0000 #0000ff' - 从中心到边缘，红色到蓝色

完整示例:

// 线性渐变（从左到右）
colorGradient: 'to right #ff6600 #ff0066';

// 线性渐变（从上到下）
colorGradient: 'to bottom #ff0000 #00ff00';

// 径向渐变（从中心到边缘）
colorGradient: 'radial #ff0000 #0000ff';

// 三色渐变
colorGradient: 'to right #ff0000 #ffff00 #00ff00';

`background`

类型: string
默认值: ''（空字符串，无背景）
说明: 背景颜色
支持格式: 同 color 参数
特殊值: 'transparent' - 透明背景

`backgroundGradient`

类型: string
默认值: ''（空字符串，不使用渐变）
说明: 背景渐变（线性或径向）
支持格式: 同 colorGradient
示例: 'to bottom #ffffff #f0f0f0'

`outerEyeColor`

类型: string
默认值: ''（跟随前景色）
说明: 码眼外圈颜色（码眼=二维码三个角的方框）
支持格式: 同 color 参数
注意: 未设置时跟随 colorGradient 或 color

`innerEyeColor`

类型: string
默认值: ''（跟随前景色）
说明: 码眼中心点颜色
支持格式: 同 color 参数
注意: 未设置时跟随 colorGradient 或 color

样式参数

`dotShape`

类型: keyof typeof qrcodeDotConfig
默认值: 'default'
说明: 模块绘制形状，影响非 Finder 的模块（不含 3 个码眼）
可选值:
- 'default' / 'square': 方块（默认 QR 风格）
- 'circle': 完整圆形（r=3，基于6x6 viewBox）
- 'circle-small': 小圆形（r=2）
- 'dot': 点状（r=1.5）
- 'star': 星形
- 'star-small': 小星形（正方形旋转45度）
- 'sparkle': 闪烁点
- 'danger': 危险标志
- 'cross': 十字
- 'plus': 加号
- 'x': X形
- 'heart': 心形
- 'vortex': 漩涡
- 'sparkle_dot': 闪烁点
- 'shake': 抖动（随机旋转-10到10度）
- 'special-circle-orizontal': 特殊圆形水平（智能连接）
- 'special-circle-vertical': 特殊圆形垂直（智能连接）
- 'rounded': 圆角矩形（需配合 roundRadius 使用）

示例:

// 使用圆形点
dotShape: 'circle';

// 使用星形点
dotShape: 'star';

`roundRadius`

类型: number
默认值: 0
说明: 当 dotShape === 'rounded' 时生效
取值范围: 0-0.5（模块宽度的比例）
示例: 0.2 表示圆角半径为 moduleSize × 0.2

`finderShape`

类型: keyof typeof qrcodeTemplateConfig
默认值: 'default'
说明: 三个 Finder（码眼）整体外形类型
可选值:
- 'default': 默认方形
- 'flurry': 毛边
- 'sdoz': 斜角
- 'drop_in': 内水滴
- 'drop': 水滴
- 'dropeye': 眼型水滴
- 'dropeyeleft': 左眼型水滴
- 'dropeyeleaf': 叶子型水滴
- 'dropeyeright': 右眼型水滴
- 'squarecircle': 方形圆
- 'circle': 圆形
- 'rounded': 圆角
- 'flower': 花朵
- 'flower_in': 内花朵
- 'leaf': 叶子
- '3-corners': 三角
- 'vortex': 漩涡
- 'dots': 点状
- 'bruised': 淤青
- 'canvas': 画布
- 'square': 方形
示例:
```
finderShape: 'circle';
```

`eyeShape`

类型: keyof typeof qrcodeEyeConfig
默认值: 'default'
说明: 码眼中心样式模板
可选值:
- 'default': 默认方形
- 'flurry': 毛边
- 'sdoz': 斜角
- 'drop_in': 内水滴
- 'drop': 水滴
- 'dropeye': 眼型水滴
- 'circle': 圆形
- 'rounded': 圆角
- 'sun': 太阳
- 'star': 星形
- 'diamond': 菱形
- 'danger': 危险标志
- 'cross': 十字
- 'plus': 加号
- 'x': X形
- 'heart': 心形
- 'vortex': 漩涡
- 'sparkle_dot': 闪烁点
- '9-dots': 九点
- '9-dots-fat': 九点粗
- 'flower': 花朵
- 'elastic': 弹性
- 'diagonal': 对角线
- 'ropes': 绳索
- 'ropes-vert': 绳索垂直
- 'bruised': 淤青
示例:
```
eyeShape: 'star';
```

图片参数

`backgroundImageHref`

类型: string
默认值: ''（空字符串，无背景图片）
说明: 背景图片 URL 或 base64 dataURL
支持格式:
- HTTP/HTTPS URL: 'https://example.com/bg.png'
- Data URL: 'data:image/png;base64,...'
- 本地路径（需配合 imgDownload: true）
优先级: 背景图片 > 背景渐变 > 背景色
注意: 若影响可扫性，请保证二维码模块与图片之间有对比

`backgroundImageOpacity`

类型: number
默认值: 1.0
说明: 背景图片透明度
取值范围: 0-1
- 0: 完全透明（不可见）
- 1: 完全不透明（默认值）
使用场景: 通过调整透明度确保二维码的可扫描性

`backgroundImageLocalHref`

类型: string
默认值: ''
说明: 背景图片本地地址（模板专用，不走网络下载）
使用场景: 服务端环境，避免网络下载提高效率

`qrcodeImageHref`

类型: string
默认值: ''（空字符串，无镂空图片）
说明: 二维码镂空背景图片 URL 或 base64 dataURL
效果: 实现类似 CSS background-clip: text 的效果，二维码的所有黑色模块会变成镂空，让背景图片透过这些镂空部分显示出来
实现原理: 使用 SVG mask 技术
支持格式: 同 backgroundImageHref
优先级: qrcodeImageHref > colorGradient > color

`qrcodeImageLocalHref`

类型: string
默认值: ''
说明: 二维码镂空背景图片本地地址（模板专用，不走网络下载）

`logo`

类型: { href: string; width?: number; height?: number; marginModules?: number }
默认值: { href: '', width: 0, height: 0, marginModules: 0 }
说明: Logo 配置对象
子参数:
- href: 图片 URL 或 base64 dataURL（必填）
- width: Logo 宽度（像素），默认为二维码宽度的 25%
- height: Logo 高度（像素），默认为二维码宽度的 25%
- marginModules: Logo 与二维码模块的留白（模块单位），暂未使用
特性:
- 自动添加圆角（Logo 宽度的 10%）
- 自动添加白色描边（Logo 宽度的 8%，最小 2px）
- 居中放置
注意: 使用 Logo 时强烈建议把纠错等级设为 'H'，并限制 Logo 大小（≤ 25% 宽度）

示例:

logo: {
  href: 'https://example.com/logo.png',
  width: 100,
  height: 100
}

`imgDownload`

类型: boolean
默认值: false
说明: 是否下载图片（将网络图片转换为 base64 内联）
使用场景: 当需要将 SVG 导出为 PNG 或需要离线使用时
注意: 开启后会自动下载 backgroundImageHref、qrcodeImageHref 和 logo.href 中的网络图片

完整示例

基础二维码

const svg = await createQrcode('https://example.com', {
  moduleSize: 10,
  margin: 4,
  color: '#000000',
  background: '#ffffff'
});

渐变二维码

// 线性渐变（从左到右）
const svg1 = await createQrcode('Hello World', {
  colorGradient: 'to right #ff6600 #ff0066',
  background: '#ffffff'
});

// 径向渐变（从中心到边缘）
const svg2 = await createQrcode('Hello World', {
  colorGradient: 'radial #ff0000 #0000ff',
  background: '#ffffff'
});

// 三色渐变
const svg3 = await createQrcode('Hello World', {
  colorGradient: 'to right #ff0000 #ffff00 #00ff00',
  background: '#ffffff'
});

自定义码眼样式

const svg = await createQrcode('Hello World', {
  finderShape: 'circle', // 圆形码眼外框
  eyeShape: 'star', // 星形码眼中心
  color: '#000000',
  background: '#ffffff'
});

独立码眼颜色

const svg = await createQrcode('Hello World', {
  colorGradient: 'to right #ff0000 #00ff00', // 前景渐变
  outerEyeColor: '#000000', // 码眼外圈纯黑色
  innerEyeColor: '#ff0000', // 码眼中心红色
  background: '#ffffff'
});

自定义数据点样式

// 圆形点
const svg1 = await createQrcode('Hello World', {
  dotShape: 'circle',
  color: '#1976d2',
  background: '#ffffff'
});

// 星形点
const svg2 = await createQrcode('Hello World', {
  dotShape: 'star',
  color: '#ff6600',
  background: '#ffffff'
});

// 圆角矩形
const svg3 = await createQrcode('Hello World', {
  dotShape: 'rounded',
  roundRadius: 0.3,
  color: '#00bcd4',
  background: '#ffffff'
});

添加Logo

const svg = await createQrcode('https://example.com', {
  logo: {
    href: 'https://example.com/logo.png',
    width: 100,
    height: 100
  },
  level: 'H', // 高纠错级别
  color: '#000000',
  background: '#ffffff'
});

背景图片

const svg = await createQrcode('Hello World', {
  backgroundImageHref: 'https://example.com/bg.jpg',
  backgroundImageOpacity: 0.3, // 30% 透明度
  color: '#000000'
});

镂空背景图片

const svg = await createQrcode('Hello World', {
  qrcodeImageHref: 'https://example.com/texture.jpg', // 二维码模块显示此图片
  background: '#ffffff'
});

整体缩放

const svg = await createQrcode('Hello World', {
  moduleSize: 10,
  margin: 4,
  scale: 2.0, // 整体放大 2 倍
  color: '#000000',
  background: '#ffffff'
});

完整配置示例

const svg = await createQrcode('https://example.com', {
  // 基础参数
  level: 'H',
  moduleSize: 10,
  margin: 4,
  scale: 1.0,

  // 颜色参数
  colorGradient: 'to right #ff6600 #ff0066',
  background: '#ffffff',
  outerEyeColor: '#000000',
  innerEyeColor: '#ff0000',

  // 样式参数
  dotShape: 'circle',
  finderShape: 'circle',
  eyeShape: 'star',

  // Logo
  logo: {
    href: 'https://example.com/logo.png',
    width: 120,
    height: 120
  },

  // 图片下载
  imgDownload: true
});

支持的样式列表

Finder 样式（码圈外框）- finderShape

| 值 | 描述 | | -------------- | ---------- | | default | 默认方形 | | flurry | 毛边 | | sdoz | 斜角 | | drop_in | 内水滴 | | drop | 水滴 | | dropeye | 眼型水滴 | | dropeyeleft | 左眼型水滴 | | dropeyeleaf | 叶子型水滴 | | dropeyeright | 右眼型水滴 | | squarecircle | 方形圆 | | circle | 圆形 | | rounded | 圆角 | | flower | 花朵 | | flower_in | 内花朵 | | leaf | 叶子 | | 3-corners | 三角 | | vortex | 漩涡 | | dots | 点状 | | bruised | 淤青 | | canvas | 画布 | | square | 方形 |

Eye 样式（码眼中心）- eyeShape

| 值 | 描述 | | ------------- | -------- | | default | 默认方形 | | flurry | 毛边 | | sdoz | 斜角 | | drop_in | 内水滴 | | drop | 水滴 | | dropeye | 眼型水滴 | | circle | 圆形 | | rounded | 圆角 | | sun | 太阳 | | star | 星形 | | diamond | 菱形 | | danger | 危险标志 | | cross | 十字 | | plus | 加号 | | x | X形 | | heart | 心形 | | vortex | 漩涡 | | sparkle_dot | 闪烁点 | | 9-dots | 九点 | | 9-dots-fat | 九点粗 | | flower | 花朵 | | elastic | 弹性 | | diagonal | 对角线 | | ropes | 绳索 | | ropes-vert | 绳索垂直 | | bruised | 淤青 |

Dot 样式（数据点）- dotShape

| 值 | 描述 | | -------------------------- | ------------------------------ | | default / square | 方块（默认） | | circle | 完整圆形（r=3） | | circle-small | 小圆形（r=2） | | dot | 点状（r=1.5） | | star | 星形 | | star-small | 小星形 | | sparkle | 闪烁点 | | danger | 危险标志 | | cross | 十字 | | plus | 加号 | | x | X形 | | heart | 心形 | | vortex | 漩涡 | | sparkle_dot | 闪烁点 | | shake | 抖动 | | special-circle-orizontal | 特殊圆形水平 | | special-circle-vertical | 特殊圆形垂直 | | rounded | 圆角矩形（需配合 roundRadius） |

技术细节

渐变支持

线性渐变格式

'to <direction> <color1> <color2> [color3...]'

方向: right | left | top | bottom
颜色: 支持任意数量的颜色值（至少2个）

径向渐变格式

'radial <color1> <color2> [color3...]'

从中心向外扩散
颜色: 支持任意数量的颜色值（至少2个）

SVG Mask 技术

库使用 SVG mask 技术实现以下功能：

统一渐变: 确保渐变在整个二维码上平滑过渡
镂空效果: qrcodeImageHref 参数通过 mask 实现镂空背景图片

图片处理

支持网络图片（HTTP/HTTPS）
支持本地图片路径（服务端环境）
支持 base64 Data URL
开启 imgDownload: true 后自动将网络图片转为内联 base64

Logo 处理

Logo 自动添加以下效果：

圆角: Logo 宽度的 10%
白色描边: Logo 宽度的 8%（最小 2px）
居中放置
使用 clipPath 裁剪为圆角矩形

注意事项

纠错级别: 使用 Logo 或遮挡物时，建议设置 level: 'H' 以确保可扫描性
Logo 大小: Logo 不应超过二维码宽度的 25%
背景图片透明度: 使用背景图片时，建议调整 backgroundImageOpacity 确保二维码可扫描
颜色对比度: 前景色和背景色应有足够对比度，确保扫码器可以识别
边距: 建议 margin 最小值为 1，确保扫码器可以识别二维码边界

许可证

MIT

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme