QRCode

qrcode

二维码 · qrcode-generator 内核 + 自渲 SVG(暗块合 path·crispEdges) + currentColor 吃主题(区别 qrcode.react 写死黑白) + UTF-8 中文 + minVersion 钉密度/boostLevel 不升版本白拿纠错 + 中心 logo(excavate 抠空开关·opacity 水印) + qrCodeSvgString/qrCodeToPngDataUrl 导出(按 DPR 放大·默认白底·可 RSC)

用法

基础用法

传入 value 即可，暗块默认继承 currentColor 吃主题。

tsx

<QRCode value="https://hulian.dev" size={160} />

纠错级别

level L/M/Q/H 逐级提高冗余（带 logo 建议 H）。

tsx

<>
  <QRCode value="https://hulian.dev" size={120} level="L" />
  <QRCode value="https://hulian.dev" size={120} level="H" />
</>

中文内容

内核已覆写为 UTF-8 编码，可直接编码中文。

tsx

<QRCode value="瑚琏组件库 · 移动端二维码" size={140} level="H" />

自定义配色

color/background 显式指定，或用 text-* 工具类换暗块色。

tsx

<QRCode
  value="https://hulian.dev"
  size={140}
  color="#0f172a"
  background="#f1f5f9"
/>

中心 Logo

传 logo 在二维码中心嵌图，务必配 level="H" 留足冗余。

tsx

<QRCode
  value="https://hulian.dev"
  size={160}
  level="H"
  logo={{ src: "/logo.png", size: 36 }}
/>

水印式 Logo

excavate={false} 不抠空、配 opacity 做水印；不透明的 logo 不抠空会盖掉模块扫不出来。

tsx

<QRCode
  value="https://hulian.dev"
  level="H"
  logo={{ src: "/logo.png", size: 60, excavate: false, opacity: 0.25 }}
/>

密度稳定 · 自动提级

minVersion 钉住版本下限，让一组码密度一致（内容变长也不跳）；boostLevel 默认开，在不升版本的前提下白拿更高纠错。

tsx

<>
  <QRCode value="A" minVersion={4} />
  <QRCode value="https://hulian.dev/components/qrcode" minVersion={4} />
</>

导出 SVG / PNG

qrCodeSvgString 出独立 SVG 串（服务端也能用），qrCodeToPngDataUrl 出 PNG data URL（自动按 DPR 放大、默认白底）。

SVG 串 6263 字符

tsx

import { qrCodeSvgString, qrCodeToPngDataUrl } from "@hulianui/ui"

// 下载 SVG
const svg = qrCodeSvgString({ value: url, size: 512 })
download(new Blob([svg], { type: "image/svg+xml" }), "qr.svg")

// 下载 PNG
const png = await qrCodeToPngDataUrl({ value: url, pixelSize: 512 })
Object.assign(document.createElement("a"), { href: png, download: "qr.png" }).click()

何时用

把 URL/文本编码为可扫二维码（自渲 SVG，吃主题色，支持中文与中心 logo）。展示静态信息码用本组件；本批其余组件不涉及编码生成。

导入

import { QRCode } from "@hulianui/ui"

Props

名称	类型	默认	说明
value*	`string`	—	编码内容（URL/文本，UTF-8）。
size	`number`	`160`	边长 px。
level	`"L" \| "M" \| "Q" \| "H"`	`"M"`	纠错级别（带 logo 建议 H）。
margin	`number`	`2`	静默区模块数。
color	`string`	`currentColor`	暗块颜色（默认继承 text-foreground）。
background	`string`	透明	背景色。
logo	`QRCodeLogo`	—	中心 logo，`{ src: string; size?: number }`；务必配 `level="H"` 留足纠错冗余。
aria-label	`string`	取 value	无障碍标签。
className	`string`	—	—

新增能力（对标 qrcode.react 的缺口，2026-08-01）

名称	类型	默认	说明
minVersion	`number`	—	版本下限 1–40：内容变长会自动升版本→模块变密、观感尺寸跳变；钉住下限让一组码密度一致。内容装不下时自动用更大版本，不截断
boostLevel	`boolean`	`true`	在不升版本的前提下自动提升纠错级别（有余量就白拿鲁棒性）
logo.excavate	`boolean`	`true`	是否垫底色块把 logo 底下的模块抠空；`false` 用于半透明水印式 logo
logo.opacity	`number`	`1`	logo 不透明度（做水印时配 `excavate={false}`）

导出用的两个函数（与组件同一个编码内核，出的码一定一致）：

qrCodeSvgString({ value, size, color, background, ... }) → 独立 SVG 字符串。可直接下载 .svg、贴进邮件/海报，服务端也能用。导出场景默认给具体色（#000/#fff）——currentColor 脱离页面就没有可继承的颜色了。
qrCodeToPngDataUrl({ value, pixelSize, ... }) → Promise<string> PNG data URL（浏览器端）。自动按 devicePixelRatio 放大一档（打印/高分屏不糊），默认白底。
buildQRCode(options) → { count, total, path, level, version } 纯矩阵，想自己画（canvas/海报合成/异形码）时用。

禁忌 / 坑

导出 PNG 别用透明底：PNG 没有「继承页面底色」这回事，透明底打印或贴进白底文档会糊成黑块。qrCodeToPngDataUrl 默认给白底就是为此。
不抠空的 logo 必须半透明：excavate={false} 配不透明 logo 会盖掉模块直接扫不出来；水印式用法记得配 opacity。
为什么不引 qrcode.react：它把前景/背景写死成 #000000/#FFFFFF，暗色主题下要消费方自己传两个色；我们默认 currentColor + 透明底，跟着主题走。它的 Canvas 变体的价值（导出）我们用 qrCodeToPngDataUrl 覆盖，不必为此多一个组件与一份依赖。

暗块默认 currentColor，靠外层文字色控制；要染色用 className="text-primary" 或显式 color，背景默认透明需自备底色保证扫码对比度。
加 logo 必须同时 level="H"，否则 logo 遮挡导致纠错冗余不足、扫不出。
中文/长文本会抬高二维码版本（更密），扫描距离与 size 要相应放大。

用法

基础用法

传入 value 即可，暗块默认继承 currentColor 吃主题。

tsx

<QRCode value="https://hulian.dev" size={160} />

纠错级别

level L/M/Q/H 逐级提高冗余（带 logo 建议 H）。

tsx

<>
  <QRCode value="https://hulian.dev" size={120} level="L" />
  <QRCode value="https://hulian.dev" size={120} level="H" />
</>

中文内容

内核已覆写为 UTF-8 编码，可直接编码中文。

tsx

<QRCode value="瑚琏组件库 · 移动端二维码" size={140} level="H" />

自定义配色

color/background 显式指定，或用 text-* 工具类换暗块色。

tsx

<QRCode
  value="https://hulian.dev"
  size={140}
  color="#0f172a"
  background="#f1f5f9"
/>

中心 Logo

传 logo 在二维码中心嵌图，务必配 level="H" 留足冗余。

tsx

<QRCode
  value="https://hulian.dev"
  size={160}
  level="H"
  logo={{ src: "/logo.png", size: 36 }}
/>

水印式 Logo

excavate={false} 不抠空、配 opacity 做水印；不透明的 logo 不抠空会盖掉模块扫不出来。

tsx

<QRCode
  value="https://hulian.dev"
  level="H"
  logo={{ src: "/logo.png", size: 60, excavate: false, opacity: 0.25 }}
/>

密度稳定 · 自动提级

minVersion 钉住版本下限，让一组码密度一致（内容变长也不跳）；boostLevel 默认开，在不升版本的前提下白拿更高纠错。

tsx

<>
  <QRCode value="A" minVersion={4} />
  <QRCode value="https://hulian.dev/components/qrcode" minVersion={4} />
</>

导出 SVG / PNG

qrCodeSvgString 出独立 SVG 串（服务端也能用），qrCodeToPngDataUrl 出 PNG data URL（自动按 DPR 放大、默认白底）。

SVG 串 6263 字符

tsx

import { qrCodeSvgString, qrCodeToPngDataUrl } from "@hulianui/ui"

// 下载 SVG
const svg = qrCodeSvgString({ value: url, size: 512 })
download(new Blob([svg], { type: "image/svg+xml" }), "qr.svg")

// 下载 PNG
const png = await qrCodeToPngDataUrl({ value: url, pixelSize: 512 })
Object.assign(document.createElement("a"), { href: png, download: "qr.png" }).click()

Props

名称	类型	默认	说明
value*	`string`	—	编码内容（URL/文本，UTF-8）。
size	`number`	`160`	边长 px。
level	`"L" \| "M" \| "Q" \| "H"`	`"M"`	纠错级别（带 logo 建议 H）。
margin	`number`	`2`	静默区模块数。
color	`string`	`currentColor`	暗块颜色（默认继承 text-foreground）。
background	`string`	透明	背景色。
logo	`QRCodeLogo`	—	中心 logo，`{ src: string; size?: number }`；务必配 `level="H"` 留足纠错冗余。
aria-label	`string`	取 value	无障碍标签。
className	`string`	—	—

新增能力（对标 qrcode.react 的缺口，2026-08-01）

名称	类型	默认	说明
minVersion	`number`	—	版本下限 1–40：内容变长会自动升版本→模块变密、观感尺寸跳变；钉住下限让一组码密度一致。内容装不下时自动用更大版本，不截断
boostLevel	`boolean`	`true`	在不升版本的前提下自动提升纠错级别（有余量就白拿鲁棒性）
logo.excavate	`boolean`	`true`	是否垫底色块把 logo 底下的模块抠空；`false` 用于半透明水印式 logo
logo.opacity	`number`	`1`	logo 不透明度（做水印时配 `excavate={false}`）

导出用的两个函数（与组件同一个编码内核，出的码一定一致）：

qrCodeSvgString({ value, size, color, background, ... }) → 独立 SVG 字符串。可直接下载 .svg、贴进邮件/海报，服务端也能用。导出场景默认给具体色（#000/#fff）——currentColor 脱离页面就没有可继承的颜色了。

qrCodeToPngDataUrl({ value, pixelSize, ... }) → Promise<string> PNG data URL（浏览器端）。自动按 devicePixelRatio 放大一档（打印/高分屏不糊），默认白底。

buildQRCode(options) → { count, total, path, level, version } 纯矩阵，想自己画（canvas/海报合成/异形码）时用。

禁忌 / 坑

导出 PNG 别用透明底：PNG 没有「继承页面底色」这回事，透明底打印或贴进白底文档会糊成黑块。qrCodeToPngDataUrl 默认给白底就是为此。

不抠空的 logo 必须半透明：excavate={false} 配不透明 logo 会盖掉模块直接扫不出来；水印式用法记得配 opacity。

为什么不引 qrcode.react：它把前景/背景写死成 #000000/#FFFFFF，暗色主题下要消费方自己传两个色；我们默认 currentColor + 透明底，跟着主题走。它的 Canvas 变体的价值（导出）我们用 qrCodeToPngDataUrl 覆盖，不必为此多一个组件与一份依赖。

暗块默认 currentColor，靠外层文字色控制；要染色用 className="text-primary" 或显式 color，背景默认透明需自备底色保证扫码对比度。

加 logo 必须同时 level="H"，否则 logo 遮挡导致纠错冗余不足、扫不出。

中文/长文本会抬高二维码版本（更密），扫描距离与 size 要相应放大。

QRCode

用法

基础用法

纠错级别

中文内容

自定义配色

中心 Logo

水印式 Logo

密度稳定 · 自动提级

导出 SVG / PNG

何时用

导入

Props

新增能力（对标 qrcode.react 的缺口，2026-08-01）

禁忌 / 坑

相关

QRCode

用法

基础用法

纠错级别

中文内容

自定义配色

中心 Logo

水印式 Logo

密度稳定 · 自动提级

导出 SVG / PNG

何时用

导入

Props

新增能力（对标 qrcode.react 的缺口，2026-08-01）

禁忌 / 坑

相关