QRCode 二维码

avue-qrcode 用于生成二维码，支持 Canvas、SVG 两种渲染方式，以及加载、过期和已扫码状态。

基础用法

效果预览可直接操作下方示例

正在加载示例…

<template>
  <el-space wrap alignment="center" :size="20">
    <avue-qrcode :value="value" />
    <el-input
      v-model="value"
      class="qrcode-demo__input"
      placeholder="请输入二维码内容"
      :maxlength="120"
      show-word-limit
    />
  </el-space>
</template>

<script setup>
import { ref } from 'vue';

const value = ref('https://avuejs.com');
</script>

<style scoped>
.qrcode-demo__input {
  width: 280px;
}
</style>

自定义外观

可以设置二维码尺寸、前景色、背景色、容错级别和中心图标；带中心图标时建议使用 Q 或 H 容错级别。

效果预览可直接操作下方示例

正在加载示例…

<template>
  <div class="qrcode-custom">
    <avue-qrcode
      :value="value"
      :type="type"
      :size="size"
      :color="color"
      :bg-color="bgColor"
      :error-level="errorLevel"
      :icon="icon"
      :icon-size="size / 4"
    />
    <div class="qrcode-custom__controls">
      <el-input v-model="value" placeholder="二维码内容" />
      <el-radio-group v-model="type">
        <el-radio-button label="canvas">Canvas</el-radio-button>
        <el-radio-button label="svg">SVG</el-radio-button>
      </el-radio-group>
      <el-radio-group v-model="errorLevel">
        <el-radio-button v-for="item in errorLevels" :key="item" :label="item">
          容错 {{ item }}
        </el-radio-button>
      </el-radio-group>
      <el-space>
        <span>尺寸</span>
        <el-slider v-model="size" :min="96" :max="260" :step="4" />
      </el-space>
      <el-space>
        <span>前景</span>
        <el-color-picker v-model="color" />
        <span>背景</span>
        <el-color-picker v-model="bgColor" show-alpha />
      </el-space>
    </div>
  </div>
</template>

<script setup>
import { ref } from 'vue';

const value = ref('https://avuejs.com');
const type = ref('canvas');
const size = ref(160);
const color = ref('#409eff');
const bgColor = ref('#ecf5ff');
const errorLevel = ref('H');
const errorLevels = ['L', 'M', 'Q', 'H'];
const icon = "data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 64 64'%3E%3Crect width='64' height='64' rx='12' fill='%23409eff'/%3E%3Cpath d='M18 18h28v28H18z' fill='white'/%3E%3Cpath d='M26 26h12v12H26z' fill='%23409eff'/%3E%3C/svg%3E";
</script>

<style scoped>
.qrcode-custom {
  display: flex;
  flex-wrap: wrap;
  align-items: center;
  gap: 24px;
}

.qrcode-custom__controls {
  display: grid;
  flex: 1;
  min-width: 260px;
  gap: 12px;
}

.qrcode-custom :deep(.el-slider) {
  width: 180px;
}
</style>

状态控制

通过 status 展示加载、过期和已扫码状态。二维码过期后，用户点击刷新按钮会触发 refresh 事件，由业务侧重新获取内容或恢复状态。

效果预览可直接操作下方示例

正在加载示例…

<template>
  <el-space direction="vertical" alignment="flex-start" :size="16">
    <el-radio-group v-model="status">
      <el-radio-button v-for="item in statuses" :key="item" :label="item">
        {{ labels[item] }}
      </el-radio-button>
    </el-radio-group>
    <avue-qrcode
      value="https://avuejs.com/login"
      :status="status"
      @refresh="handleRefresh"
    />
    <span>当前状态：{{ labels[status] }}</span>
  </el-space>
</template>

<script setup>
import { ref } from 'vue';
import { ElMessage } from 'element-plus';

const status = ref('active');
const statuses = ['active', 'loading', 'expired', 'scanned'];
const labels = {
  active: '正常',
  loading: '加载中',
  expired: '已过期',
  scanned: '已扫码',
};

const handleRefresh = () => {
  status.value = 'active';
  ElMessage.success('已重新获取二维码');
};
</script>

导出二维码

通过组件 ref 调用 toDataURL，可分别下载 Canvas PNG 和 SVG 二维码。

效果预览可直接操作下方示例

正在加载示例…

<template>
  <el-space wrap alignment="center" :size="20">
    <avue-qrcode ref="canvasRef" :value="value" type="canvas" color="#409eff" />
    <avue-qrcode ref="svgRef" :value="value" type="svg" color="#67c23a" />
    <el-space direction="vertical" alignment="flex-start">
      <el-input v-model="value" class="qrcode-export__input" />
      <el-button type="primary" @click="download(canvasRef, 'avue-qrcode.png')">
        下载 PNG
      </el-button>
      <el-button @click="download(svgRef, 'avue-qrcode.svg')">下载 SVG</el-button>
    </el-space>
  </el-space>
</template>

<script setup>
import { ref } from 'vue';
import { ElMessage } from 'element-plus';

const canvasRef = ref();
const svgRef = ref();
const value = ref('https://avuejs.com');

const download = async (qrcodeRef, filename) => {
  try {
    const url = await qrcodeRef.toDataURL();
    const link = document.createElement('a');
    link.download = filename;
    link.href = url;
    link.click();
  } catch {
    ElMessage.error('二维码尚未准备完成，请稍后重试');
  }
};
</script>

<style scoped>
.qrcode-export__input {
  width: min(260px, 100%);
}
</style>

Attributes

参数	说明	类型	可选值	默认值
value	二维码内容	string	-	''
type	渲染方式	string	canvas / svg	canvas
size	二维码宽高，单位为 px	number	-	160
color	前景色	string	-	#000
bgColor	背景色	string	-	transparent
bordered	是否显示边框	boolean	true / false	true
errorLevel	容错级别	string	L / M / Q / H	M
icon	中央图标地址	string	-	-
iconSize	中央图标尺寸，最大为二维码尺寸的一半	number	-	40
status	状态遮罩	string	active / loading / expired / scanned	active

Events

事件名	说明	回调参数
refresh	status 为 expired 时，点击“刷新”触发	-
error	二维码内容无法生成时触发	error
icon-error	Canvas 中央图标加载失败时触发	-

Methods

通过组件 ref 调用。

方法名	说明	参数
toDataURL	异步返回 Promise<string>；Canvas 默认 PNG，SVG 固定返回 SVG data URL	type = 'image/png', quality?: number
refresh	触发 refresh 事件，由业务更新二维码内容	无

使用说明

修改 value 会重新生成二维码；切换状态只改变遮罩，不会自动请求新的二维码。扫码登录的轮询与状态更新由业务控制。

在组件挂载后 await ref.toDataURL() 并处理异常。该方法等待下一次 Vue 更新，不代表远程中心图标已完成加载；需要包含图标的导出应先确保图片可用，跨域图片还需服务端允许 Canvas 跨域使用。当前组件没有插槽。