QrCode 二维码

基于 qrcode 库封装的 Vue 3 二维码组件，支持 SVG / Canvas 两种渲染模式，可配置前景/背景色、纠错等级、Logo 等。

安装

依赖

pnpm add qrcode @types/qrcode

基础用法

通过 `value` 属性指定二维码内容。

<template>
  <div>
    <hx-qr-code value="https://hxui.example.com" :size="200" />
  </div>
</template>

<script setup lang="ts">
import { HxQrCode } from "@whhx/ui"
</script>

自定义配置

调整尺寸、背景色、前景色等参数。

通过 props 自定义二维码外观与下载行为。

<template>
  <div>
    <hx-qr-code
      value="https://hxui.example.com"
      renderMode="canvas"
      :size="200"
      :show-download="true"
      download-file-name="custom-qrcode"
    />
  </div>
</template>

<script setup lang="ts">
import { HxQrCode } from "@whhx/ui"
</script>

动态内容

实时响应输入内容变化，支持防抖处理。

输入框内容变化后，300ms 防抖延迟更新二维码。

SVG 模式

Canvas 模式

<template>
  <div class="qrcode-dynamic-demo">
    <el-input
      v-model="qrValue"
      placeholder="请输入二维码内容"
      class="qrcode-input"
      clearable
    />
    <div class="qrcode-row">
      <div class="qrcode-item">
        <h4>SVG 模式</h4>
        <hx-qr-code
          :value="debouncedValue"
          renderMode="svg"
          :size="180"
          :show-download="true"
          download-file-name="qrcode-svg"
        />
      </div>
      <div class="qrcode-item">
        <h4>Canvas 模式</h4>
        <hx-qr-code
          :value="debouncedValue"
          renderMode="canvas"
          :size="180"
          :show-download="true"
          download-file-name="qrcode-canvas"
        />
      </div>
    </div>
  </div>
</template>

<script setup lang="ts">
import { ref, watch } from 'vue'
import { HxQrCode } from "@whhx/ui"

const qrValue = ref('https://hxui.example.com')
const debouncedValue = ref(qrValue.value)

let debounceTimer: ReturnType<typeof setTimeout> | null = null

function debounce<T extends (...args: any[]) => void>(fn: T, delay: number): T {
  return ((...args: any[]) => {
    if (debounceTimer) clearTimeout(debounceTimer)
    debounceTimer = setTimeout(() => fn(...args), delay)
  }) as T
}

const updateDebouncedValue = debounce((value: string) => {
  debouncedValue.value = value
}, 300)

watch(qrValue, (newValue) => {
  updateDebouncedValue(newValue)
})
</script>

<style scoped>
.qrcode-dynamic-demo {
  display: flex;
  flex-direction: column;
  gap: 20px;
}

.qrcode-input {
  max-width: 400px;
}

.qrcode-row {
  display: flex;
  gap: 40px;
  flex-wrap: wrap;
}

.qrcode-item {
  display: flex;
  flex-direction: column;
  align-items: center;
  gap: 12px;
}

.qrcode-item h4 {
  margin: 0;
  font-weight: 500;
  color: var(--el-text-color-primary);
}
</style>

Logo

支持在二维码中心展示 Logo，自动添加白色背景。

通过 `logo` 属性配置 Logo 图片。

<template>
  <div class="qrcode-logo-demo">
    <hx-qr-code
      :value="qrValue"
      :size="200"
      :logo="{
        url: 'https://vitejs.cn/logo.svg',
        width: 40,
        height: 40,
      }"
      error-correction-level="M"
    />
  </div>
</template>

<script setup lang="ts">
import { HxQrCode } from "@whhx/ui"

const qrValue = 'https://hxui.example.com'
</script>

<style scoped>
.qrcode-logo-demo {
  display: flex;
  justify-content: center;
}
</style>

Logo 与纠错等级 L 不兼容，请使用 M 及以上等级。

全局配置

可通过 HxConfigProvider 在应用顶层统一配置二维码默认值：

<template>
  <HxConfigProvider :qrCode="{ size: 200, colorDark: '#333333' }">
    <App />
  </HxConfigProvider>
</template>

渲染模式

模式	说明	适用场景
svg（默认）	生成 SVG，缩放无损、CSS 可控	高清展示、主题适配
canvas	生成 Canvas，下载更直接	打印、直接保存

纠错等级

纠错等级越高，二维码可被遮挡的面积越大，但会导致码图变密。

等级	可纠错比例	说明
L	7%	低纠错，码图最简
M（默认）	15%	中等纠错
Q	25%	较高纠错
H	30%	高纠错，码图最密

Logo 与纠错等级 L 不兼容，请使用 M 及以上等级。

API

Props

属性	说明	类型	默认值
value	二维码内容（URL 或任意文本）	string	—
renderMode	渲染方式	'svg' | 'canvas'	'svg' 或 ConfigProvider 配置
size	二维码尺寸（宽高）	number | string	120 或 ConfigProvider 配置
colorDark	前景色（深色模块颜色）	string	'#000000' 或 ConfigProvider 配置
colorLight	背景色	string	'#ffffff' 或 ConfigProvider 配置
errorCorrectionLevel	纠错等级	'L' | 'M' | 'Q' | 'H'	'M' 或 ConfigProvider 配置
margin	周围留白（单位 px）	number	2 或 ConfigProvider 配置
showDownload	是否显示下载按钮	boolean	true
downloadText	下载按钮文案	string	'下载二维码'
downloadFileName	下载文件名（不含扩展名）	string	'qrcode'
downloadIcon	下载按钮图标组件	Component	Download
logo	Logo 配置	QrCodeLogo	undefined
style	自定义样式	Record<string, string>	{}

QrCodeLogo

属性	说明	类型	默认值
url	Logo 图片 URL	string	—
width	Logo 宽度（px）	number	40
height	Logo 高度（px）	number	40
offsetX	Logo 距中心的水平偏移（px）	number	0
offsetY	Logo 距中心的垂直偏移（px）	number	0

Expose

方法	说明	参数	返回值
regenerate	重新生成二维码	—	Promise<void>

类型定义

import type { QrCodeProps, QrCodeLogo, QrCodeRenderMode, QrCodeErrorCorrectionLevel } from '@whhx/ui'