qrcode.vue

Star {{ stargazersCount }}

用于生成二维码的 Vue 组件。同时支持 Vue 2 和 Vue 3。提供 canvas 和 svg 两种二维码格式。可自定义尺寸、边距、纠错级别、前景色和背景色、Logo 图片以及渐变效果。

安装

npm install --save qrcode.vue
# or
pnpm add qrcode.vue
yarn add qrcode.vue

该组件提供三种构建格式：

文件 格式
qrcode.vue.cjs.js CommonJS
qrcode.vue.esm.js ES module
qrcode.vue.browser.min.js UMD (browser)

快速开始

import { createApp } from 'vue'
import QrcodeVue from 'qrcode.vue'

createApp({
  data: { value: 'https://example.com' },
  template: '<qrcode-vue :value="value"></qrcode-vue>',
  components: { QrcodeVue },
}).mount('#root')

组件 Props

属性 类型 默认值 说明
value string '' 二维码编码的内容。
size number 100 二维码元素的尺寸（宽和高），单位为像素。
render-as 'canvas' | 'svg' 'canvas' 渲染格式。使用 svg 以支持 SSR。
margin number 0 二维码静默区（留白）宽度。
level 'L' | 'M' | 'Q' | 'H' 'L' 纠错级别。级别越高，可恢复的损坏越多。
background string '#ffffff' 二维码背景色。
foreground string '#000000' 二维码模块的前景色。
radius number 0 模块圆角比例（0 到 0.5）。0.5 时模块变为圆形。
gradient boolean false 启用二维码模块的渐变填充。
gradient-type 'linear' | 'radial' 'linear' 启用 gradient 时使用的渐变类型。
gradient-start-color string '#000000' 渐变起始颜色。
gradient-end-color string '#ffffff' 渐变结束颜色。
image-settings ImageSettings {} Logo 图片设置，详见下方说明。
id string undefined SVG 内部元素的自定义 ID。传入 useId() 以确保 SSR 水合一致性。
class string '' 二维码元素的 CSS 类名。

图片设置

type ImageSettings = {
  src: string            // URL of the logo image
  x?: number             // Horizontal offset (centers by default)
  y?: number             // Vertical offset (centers by default)
  height: number         // Height of the image in pixels
  width: number          // Width of the image in pixels
  excavate?: boolean     // Remove modules behind the image
  borderRadius?: number  // Border radius of the image
  crossOrigin?: 'anonymous' | 'use-credentials' | ''  // CORS attribute for the image
}

TypeScript 示例

<script setup lang="ts">
import { ref } from 'vue'
import QrcodeVue from 'qrcode.vue'
import type { Level, RenderAs, GradientType, ImageSettings } from 'qrcode.vue'

const value = ref('https://example.com')
const level = ref<Level>('M')
const renderAs = ref<RenderAs>('svg')
const background = ref('#ffffff')
const foreground = ref('#000000')
const margin = ref(0)

const imageSettings = ref<ImageSettings>({
  src: 'https://github.com/scopewu.png',
  width: 30,
  height: 30,
  excavate: true,
  // crossOrigin: 'anonymous', // Set this when exporting canvas to image
})

const gradient = ref(false)
const gradientType = ref<GradientType>('linear')
const gradientStartColor = ref('#000000')
const gradientEndColor = ref('#38bdf8')
const radius = ref(0)
</script>

模板 Ref 方法

QrcodeCanvas 和 QrcodeSvg 都通过模板 ref 暴露以下方法。可以直接通过浏览器下载生成的二维码。QrcodeVue 会根据当前的 render-as 转发这些方法：

组件 方法 签名 说明
QrcodeCanvas toDataURL (type?: string, quality?: number) => string | undefined 将二维码转换为 Data URL。
download (filename?: string) => void 触发下载二维码图片。
QrcodeSvg toDataURL () => string | undefined 将 SVG 元素转换为 Data URL。
download (filename?: string) => void 触发下载二维码 SVG 图片。

QrcodeCanvas

<script setup lang="ts">
import { ref } from 'vue'
import { QrcodeCanvas } from 'qrcode.vue'

const qrRef = ref()

const handleDownload = () => {
  qrRef.value?.download('my-qrcode.png')
}
</script>

<qrcode-canvas ref="qrRef" value="https://example.com" />

CORS 注意：当二维码包含跨域 Logo 图片时，请确保设置 imageSettings.crossOrigin: 'anonymous'，且图片服务器返回 Access-Control-Allow-Origin 响应头。否则 canvas 会被"污染"，导致 toDataURL / download 抛出 SecurityError。

QrcodeSvg

<script setup lang="ts">
import { ref } from 'vue'
import { QrcodeSvg } from 'qrcode.vue'

const qrRef = ref()

const handleDownload = () => {
  qrRef.value?.download('my-qrcode.svg')
}
</script>

<qrcode-svg ref="qrRef" value="https://example.com" />

命名导出 (v3.5+)

从 v3.5 开始，单独导出了 QrcodeCanvas 和 QrcodeSvg 组件：

import { QrcodeCanvas, QrcodeSvg } from 'qrcode.vue'

// CommonJS / CDN usage
const { default: QrcodeVue, QrcodeCanvas, QrcodeSvg } = require('qrcode.vue')

预览

生成的代码

{{ usageExample }}

设置

图片设置