Translation in progress
This page hasn't been translated into English yet, so the content below is in Chinese. The code examples work the same way.
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状态下也能导出,导出的是当前内容的二维码。