QrCode 二维码
把一段文本生成二维码,常用在扫码登录、分享链接、下载 App 这类场景。内容按 UTF-8 编码,中文、表情都能编;版本(1 到 40)按内容长度自动选最小的。可以在中间放图标,用 canvas 或 svg 渲染,还能导出成 PNG、SVG 下载。
编码器是组件自带的(按 ISO/IEC 18004 实现),不依赖第三方库。
引入
import { NsQrCode } from '@ns/ui'
import type { QrCodeExpose } from '@ns/ui'
基础用法
value 是二维码的内容。默认边长 100px,四周 12px 白色留白,带一圈外框。
<template>
<NsQrCode value="https://example.com" />
</template>
内容可以是任意文本,中文也行:
<script setup lang="ts">
import { ref } from 'vue'
import { NsInput, NsQrCode } from '@ns/ui'
const text = ref('你好,NsUI 二维码')
</script>
<template>
<div style="margin-bottom: 12px">
<NsQrCode :value="text" />
</div>
<NsInput v-model="text" />
</template>
添加图标
icon-src 是中间图标的地址。图标会盖住中间的码点,所以有图标、又没写 error-correction-level 时,纠错级别自动用最高的 H(约 30% 的码字损坏后还能识别);写了纠错级别就按写的来。
icon-size 是图标的边长(默认 40px),icon-background-color 是图标的底色(默认白色),icon-border-radius 是底色和图片的圆角(默认 4px)。图片按原比例缩放到图标框里居中,超出圆角的部分裁掉。
<template>
<NsSpace wrap>
<NsQrCode value="https://example.com" icon-src="/logo.png" />
<NsQrCode
value="https://example.com"
icon-src="/logo.png"
:size="160"
:icon-size="48"
icon-background-color="#f0f5ff"
:icon-border-radius="12"
/>
</NsSpace>
</template>
图标不要太大:边长建议不超过 size 的 40%(默认 100 配 40),再大就可能扫不出来。
尺寸和留白
size是二维码图案的边长(px),不含留白,默认 100。整个组件的边长是size + padding × 2,再加两边的外框(各 1px)。padding是四周的留白,用background-color填充,默认 12px。数字按 px,也可以写字符串(如'1em')。扫码软件靠留白找二维码的边界,放在深色或花哨的背景上时不要设成 0。bordered控制外框,默认显示。
<template>
<NsSpace wrap align="end">
<NsQrCode value="size 160" :size="160" />
<NsQrCode value="padding 24" :padding="24" />
<NsQrCode value="无外框" :bordered="false" />
</NsSpace>
</template>
下面第一行是不同的 size,第二行是不同的 padding(0、数字、字符串):
<template>
<NsSpace direction="vertical" align="start">
<NsSpace wrap align="end">
<NsQrCode value="https://example.com" :size="60" />
<NsQrCode value="https://example.com" :size="80" />
<NsQrCode value="https://example.com" />
<NsQrCode value="https://example.com" :size="140" />
</NsSpace>
<NsSpace wrap align="end">
<NsQrCode value="https://example.com" :padding="0" />
<NsQrCode value="https://example.com" :padding="6" />
<NsQrCode value="https://example.com" padding="1em" />
<NsQrCode value="https://example.com" :padding="32" :bordered="false" />
</NsSpace>
</NsSpace>
</template>
size 是像素边长,不是其他组件那种 large / default / small 三档尺寸,也不跟随 NsConfigProvider 的 size。
颜色
color 是码点颜色(默认 #000),background-color 是底色(默认 #FFF)。
<template>
<NsSpace wrap>
<NsQrCode value="主色码点" color="#1677ff" background-color="#f0f5ff" />
<NsQrCode value="绿色码点" color="#237804" background-color="#f6ffed" />
<NsQrCode value="紫色码点" color="#531dab" />
<NsQrCode value="暖色底" color="#873800" background-color="#fff7e6" />
</NsSpace>
</template>
颜色写死成 props 的默认值,不跟暗色主题变:二维码要深色码点、浅色底才能扫,很多扫码软件认不出浅色码点配深色底的“反色”二维码。所以暗色主题下二维码仍是黑码白底,看起来是一块白色卡片。自己改颜色时也要保证码点比底色深得多。外框、圆角和状态遮罩用的是主题变量,会跟着主题变。
纠错级别
error-correction-level 有 4 档:
| 级别 | 能恢复的码字 | 说明 |
|---|---|---|
| L | 约 7% | 码点最少,最容易扫 |
| M | 约 15% | 没有图标时的默认值 |
| Q | 约 25% | |
| H | 约 30% | 有图标时的默认值 |
级别越高越抗遮挡、抗污损,但同样的内容需要更多的码点,图案更密。下面 4 个二维码的内容相同,从左到右是 L、M、Q、H:
<template>
<NsSpace wrap size="large">
<NsSpace direction="vertical" align="center">
<NsQrCode value="https://example.com/docs/qrcode" error-correction-level="L" />
<span class="caption">L</span>
</NsSpace>
<NsSpace direction="vertical" align="center">
<NsQrCode value="https://example.com/docs/qrcode" error-correction-level="M" />
<span class="caption">M(默认)</span>
</NsSpace>
<NsSpace direction="vertical" align="center">
<NsQrCode value="https://example.com/docs/qrcode" error-correction-level="Q" />
<span class="caption">Q</span>
</NsSpace>
<NsSpace direction="vertical" align="center">
<NsQrCode value="https://example.com/docs/qrcode" error-correction-level="H" />
<span class="caption">H</span>
</NsSpace>
</NsSpace>
</template>
<style scoped>
.caption {
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
}
</style>
渲染方式
type 默认是 canvas,按设备像素比(devicePixelRatio)放大画布,高分屏上也清晰;浏览器缩放或窗口拖到另一块屏幕时会按新的比例重画。type="svg" 时渲染成 <svg>,所有码点是一条 path,缩放、打印不失真,也能被 CSS 选中。两种方式都能带图标。
<template>
<NsSpace wrap>
<NsQrCode value="canvas 渲染" />
<NsQrCode value="svg 渲染" type="svg" />
<NsQrCode value="canvas 带图标" icon-src="/logo.png" />
<NsQrCode value="svg 带图标" type="svg" icon-src="/logo.png" />
</NsSpace>
</template>
下载二维码
通过 ref 调用 toDataURL 拿到图片的 data URL,再用 <a download> 下载。两种渲染方式都能导出 PNG、JPEG、WebP 和 SVG;导出的图片含四周的留白和图标,不含外框和状态遮罩。
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsQrCode, NsSpace } from '@ns/ui'
import type { QrCodeExpose } from '@ns/ui'
const qrRef = ref<QrCodeExpose | null>(null)
const download = async (type: 'image/png' | 'image/svg+xml') => {
const url = await qrRef.value?.toDataURL(type, { scale: 4 })
if (!url) return
const a = document.createElement('a')
a.href = url
a.download = type === 'image/png' ? 'qrcode.png' : 'qrcode.svg'
a.click()
}
</script>
<template>
<NsSpace wrap>
<NsQrCode ref="qrRef" value="https://example.com" icon-src="/logo.png" />
<NsButton type="primary" icon="download" @click="download('image/png')">下载 PNG</NsButton>
<NsButton icon="download" @click="download('image/svg+xml')">下载 SVG</NsButton>
</NsSpace>
</template>
- PNG、JPEG、WebP 的边长是
(size + padding × 2) × scale,scale默认 2,打印用可以设大一些。 - 有图标时会等图标加载完再导出。图标和页面不同源时,要把
icon-cross-origin设成"anonymous",并让图标所在的服务器允许跨域(返回Access-Control-Allow-Origin),否则画布被污染,导出 PNG 会失败(Promise reject,控制台有提示)。 - 导出 SVG 不受跨域限制,但 SVG 里的图标是对原地址的引用,没有内嵌进去。要拿 SVG 源码(例如直接插进页面或发给后端)用
toSvgString()。
JPEG、WebP 可以用 quality 设质量(0 到 1)。下面导出后在右边显示导出的图片和大小,toSvgString() 拿到的是 SVG 源码字符串:
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsQrCode, NsSpace } from '@ns/ui'
import type { QrCodeExpose, QrCodeExportType } from '@ns/ui'
const qrRef = ref<QrCodeExpose | null>(null)
const preview = ref('')
const info = ref('')
const exportImage = async (type: QrCodeExportType) => {
const url = await qrRef.value?.toDataURL(type, { scale: 2, quality: 0.8 })
if (!url) return
preview.value = url
info.value = `${type},data URL 共 ${url.length} 个字符`
}
const exportSvgString = () => {
const svg = qrRef.value?.toSvgString() ?? ''
preview.value = ''
info.value = `toSvgString() 返回 ${svg.length} 个字符,开头是 ${svg.slice(0, 40)}…`
}
</script>
<template>
<NsSpace wrap align="start">
<NsQrCode ref="qrRef" value="https://example.com" color="#1677ff" />
<NsSpace direction="vertical" align="start">
<NsSpace wrap>
<NsButton size="small" @click="exportImage('image/png')">PNG</NsButton>
<NsButton size="small" @click="exportImage('image/jpeg')">JPEG</NsButton>
<NsButton size="small" @click="exportImage('image/webp')">WebP</NsButton>
<NsButton size="small" @click="exportImage('image/svg+xml')">SVG</NsButton>
<NsButton size="small" @click="exportSvgString">toSvgString</NsButton>
</NsSpace>
<span>{{ info || '点上面的按钮导出' }}</span>
<img v-if="preview" :src="preview" alt="导出的二维码" style="width: 124px" />
</NsSpace>
</NsSpace>
</template>
状态
status 有 active(默认)、loading、expired 三种:
loading:盖一层半透明遮罩和NsSpin加载动画,根元素带aria-busy="true"。expired:显示“二维码已过期”和“点击刷新”按钮,点按钮触发refresh事件,在事件里重新获取二维码内容。文字用expired-text、refresh-text改。
<template>
<NsSpace wrap size="large">
<NsSpace direction="vertical" align="center">
<NsQrCode value="https://example.com" />
<span class="caption">active</span>
</NsSpace>
<NsSpace direction="vertical" align="center">
<NsQrCode value="https://example.com" status="loading" />
<span class="caption">loading</span>
</NsSpace>
<NsSpace direction="vertical" align="center">
<NsQrCode value="https://example.com" status="expired" />
<span class="caption">expired</span>
</NsSpace>
<NsSpace direction="vertical" align="center">
<NsQrCode
value="https://example.com"
status="expired"
expired-text="登录码已失效"
refresh-text="重新获取"
/>
<span class="caption">改了提示文字</span>
</NsSpace>
</NsSpace>
</template>
<style scoped>
.caption {
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
}
</style>
点“点击刷新”后进入加载状态,1 秒后换成新的二维码:
<script setup lang="ts">
import { ref } from 'vue'
import { NsQrCode } from '@ns/ui'
import type { QrCodeStatus } from '@ns/ui'
const value = ref('https://example.com/login?t=1')
const status = ref<QrCodeStatus>('expired')
const refresh = async () => {
status.value = 'loading'
value.value = await fetchLoginUrl()
status.value = 'active'
}
// 换成你的接口
const fetchLoginUrl = () =>
new Promise<string>((resolve) =>
setTimeout(() => resolve(`https://example.com/login?t=${Date.now()}`), 1000)
)
</script>
<template>
<NsQrCode :value="value" :status="status" @refresh="refresh" />
</template>
遮罩里的内容可以用 status 插槽整个换掉,插槽参数有 status 和 refresh(调用它就触发 refresh 事件):
<script setup lang="ts">
import { ref } from 'vue'
import { NsQrCode } from '@ns/ui'
import type { QrCodeStatus } from '@ns/ui'
const value = ref('https://example.com/login?t=1')
const status = ref<QrCodeStatus>('expired')
const refresh = async () => {
status.value = 'loading'
value.value = await fetchLoginUrl()
status.value = 'active'
}
// 换成你的接口
const fetchLoginUrl = () =>
new Promise<string>((resolve) =>
setTimeout(() => resolve(`https://example.com/login?t=${Date.now()}`), 1000)
)
</script>
<template>
<NsQrCode :value="value" :status="status" @refresh="refresh">
<template #status="{ status, refresh }">
<span v-if="status === 'loading'">正在生成…</span>
<a v-else href="javascript:;" @click="refresh">已失效,点此刷新</a>
</template>
</NsQrCode>
</template>
内容过长
二维码的容量有上限(版本 40):L 级 2953 字节、M 级 2331、Q 级 1663、H 级 1273。中文按 UTF-8 每个字 3 字节,H 级最多约 424 个汉字。超出时组件不报错,在原位置显示“内容过长,无法生成二维码”(overflow-text 改文字),并在控制台警告 [NsUI] QrCode 生成失败……。
内容太长时可以降低纠错级别,或者改成放一个短链接。内容越长图案越密,手机扫起来越吃力,一般建议几百字节以内。
点按钮把内容换成 3000 个字符,超出 M 级的容量:
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsQrCode, NsSpace } from '@ns/ui'
const short = 'https://example.com'
const value = ref(short)
const toggle = () => {
value.value = value.value === short ? 'a'.repeat(3000) : short
}
</script>
<template>
<NsSpace wrap align="center">
<NsQrCode :value="value" overflow-text="内容太长啦" />
<NsButton @click="toggle">{{ value === short ? '换成 3000 个字符' : '换回短链接' }}</NsButton>
</NsSpace>
</template>
无障碍
- 二维码(
<canvas>或<svg>)带role="img",aria-label默认是“二维码:<value>”,value为空时是“二维码”。 - 用
alt或aria-label改成更有意义的说明,例如“扫码登录”;两个都写时aria-label优先。内容是很长的链接时建议写上,免得屏幕阅读器念一长串网址。 - 过期时的刷新按钮是原生
<button>,能用 Tab 聚焦,回车、空格触发;加载动画带role="status"。
Props
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| value | string | '' | 二维码的内容,按 UTF-8 编码 |
| size | number | 100 | 二维码图案的边长(px),不含留白;不是正数时按 100 并警告 |
| padding | number | string | 12 | 四周的留白,数字按 px,用 background-color 填充 |
| color | string | '#000' | 码点颜色,不跟暗色主题变 |
| background-color | string | '#FFF' | 底色(含留白),不跟暗色主题变 |
| icon-src | string | - | 中间图标的地址 |
| icon-size | number | 40 | 图标的边长(px),超过 size 时按 size |
| icon-background-color | string | '#FFF' | 图标的底色 |
| icon-border-radius | number | 4 | 图标底色和图片的圆角(px),最大为图标边长的一半 |
| icon-cross-origin | '' | 'anonymous' | 'use-credentials' | - | 图标的跨域设置,同 <img crossorigin>;跨域图标要导出 PNG 时设 'anonymous' |
| error-correction-level | 'L' | 'M' | 'Q' | 'H' | 'M'(有 icon-src 时 'H') | 纠错级别;写了就按写的,无效值警告并按默认值 |
| type | 'canvas' | 'svg' | 'canvas' | 渲染方式 |
| bordered | boolean | true | 是否显示外框 |
| status | 'active' | 'loading' | 'expired' | 'active' | 状态 |
| expired-text | string | '二维码已过期' | 过期时的提示文字 |
| refresh-text | string | '点击刷新' | 过期时刷新按钮的文字 |
| overflow-text | string | '内容过长,无法生成二维码' | 内容太长、生成不了时的提示文字 |
| alt | string | - | 替代文字,作为二维码的 aria-label |
| aria-label | string | - | 二维码的 aria-label,优先于 alt;都不写时是“二维码:<value>” |
Events
| 事件 | 回调参数 | 说明 |
|---|---|---|
| refresh | () | status 为 expired 时点了刷新按钮 |
Slots
| 插槽 | 作用域参数 | 说明 |
|---|---|---|
| status | { status: 'loading' | 'expired', refresh: () => void } | status 不是 active 时遮罩里的内容,默认是加载动画,或“已过期”加刷新按钮 |
方法
通过 NsQrCode 的 ref 调用。
| 方法 | 参数 | 返回值 | 说明 |
|---|---|---|---|
| toDataURL | (type?: QrCodeExportType, options?: QrCodeExportOptions) | Promise<string> | 导出图片的 data URL,默认 PNG。含留白和图标;有图标时等它加载完。内容过长时 reject;跨域图标污染画布时 reject 并警告 |
| toSvgString | - | string | 导出 SVG 源码,含底色、留白和图标;内容过长时返回空字符串 |
类型
import type {
QrCodeProps,
QrCodeEmits,
QrCodeExpose,
QrCodeErrorCorrectionLevel,
QrCodeType,
QrCodeStatus,
QrCodeExportType,
QrCodeExportOptions,
QrCodeIconCrossOrigin
} from '@ns/ui'
type QrCodeErrorCorrectionLevel = 'L' | 'M' | 'Q' | 'H'
type QrCodeType = 'canvas' | 'svg'
type QrCodeStatus = 'active' | 'loading' | 'expired'
type QrCodeExportType = 'image/png' | 'image/jpeg' | 'image/webp' | 'image/svg+xml'
type QrCodeIconCrossOrigin = '' | 'anonymous' | 'use-credentials'
interface QrCodeExportOptions {
/** 放大倍数,默认 2,只对 PNG、JPEG、WebP 有效 */
scale?: number
/** JPEG、WebP 的质量,0 到 1 */
quality?: number
}
interface QrCodeExpose {
toDataURL: (type?: QrCodeExportType, options?: QrCodeExportOptions) => Promise<string>
toSvgString: () => string
}
注意事项
- 只用字节模式编码(UTF-8),不用数字、字母数字、汉字模式,所以纯数字的内容会比其他实现稍密一点,但所有字符都能编。没有写 ECI 标识,微信、支付宝和常见的扫码库都会按 UTF-8 识别中文。
- 版本按内容长度自动选能放下的最小版本;纠错级别按设置的来,不会在同一版本里自动提高。
- 8 种掩码按规范的罚分规则选最优的,同样的内容、纠错级别,输出的图案每次都一样。
- 留白就是规范里的“静区”。规范建议 4 个模块宽,默认 12px 对小图案(版本 1、2)够用,内容很长、模块很密时可以把
padding加大一些,或者把size调大。 - 图标加载失败时只画二维码,并在控制台警告。canvas 模式下图标是异步加载的,第一次显示时会先出现没有图标的二维码,图标加载完再补上。
- 状态遮罩、外框、圆角用主题变量,暗色主题下遮罩是深色的;二维码本身的颜色不变(原因见“颜色”)。
- 导出的图片不含外框和状态遮罩。
loading、expired状态下也能导出,导出的是当前内容的二维码。