npm

terry 12小时前阅读数 193 #Vue

Vue3项目里怎么快速生成可自定义样式的二维码？会不会有兼容性问题？

最近在帮公司改一个H5营销页,产品突然加了个需求：每个分享的活动卡片右下角要带专属用户二维码，还要能改颜色、加圆角、加小logo，虽然项目刚从Vue2迁到Vue3没多久，但二维码生成这种基础功能应该难不倒人吧？结果找库的时候踩了两个小坑——要么是只支持Vue2的插件，要么是自定义样式太局限，最后折腾半天终于选到好用的方案，顺便整理了这篇全一点的笔记，把从0到实现、再到避坑的细节都写下来。

Vue3生成二维码的主流方案有哪些？

现在前端生成二维码的工具库很多,但适配Vue3生态的目前主要有三类，得根据你的项目需求选：第一类是直接用原生JS库，比如qrcode.js或者qrcode.vue？不对，等下，qrcode.vue之前也有Vue2版本，现在作者更了Vue3适配版，不过本质上它也是对qrcode.js轻量封装的Vue组件，这种适合习惯写组件模板的人；第二类是纯原生JS库，比如qrcodejs2（注意不是原来的qrcode.js）、qrcode-terminal（这个主要是终端用的，前端跳过），这种适合需要更底层控制、不想引入额外Vue组件库的项目；第三类是功能更全的组件库，比如VueQr、vue-qrcode-reader里的生成部分？不过vue-qrcode-reader主打识别，生成功能不如VueQr强，所以重点看VueQr，它支持的自定义项超级多：加logo、改定位点颜色、加渐变、加圆角、加边距、嵌入文本、支持canvas/svg两种渲染模式，兼容性也做得不错。

那怎么快速上手一个适配Vue3、又好用的库？这里推荐VueQr，说下我的踩坑安装和配置过程

一开始我试了直接搜Vue3二维码,出来第一个推荐的是qrcode.vue@next，安装完发现自定义颜色只能改整个码的颜色和背景，定位点、渐变这些都没有，果断换，然后选了VueQr，这里要注意安装的版本号！原来的VueQr是Vue2的，Vue3的要带@next后缀吗？不对不对，再仔细查，后来VueQr的作者重新发布了适配Vue3的正式版，叫@vue-qr/vue3，对，这个才对！之前踩坑装成了旧版本的next包，导入的时候各种报错，浪费了十分钟。

安装很简单,用npm或者yarn、pnpm都行：

# yarn
yarn add @vue-qr/vue3
# pnpm
pnpm add @vue-qr/vue3

安装完之后,在Vue3组件里怎么用？分全局注册和局部注册两种，局部注册更推荐，因为不是每个页面都要用二维码，能减少点打包体积：

局部注册的话,在script标签里导入组件就行，注意如果用的是<script setup>语法糖，直接导入就能用，不需要再components里注册，这点很Vue3：
```
<script setup>
import VueQr from '@vue-qr/vue3'
// 后面可以定义一些props或者响应式数据
</script>
```

全局注册的话,在main.js或者main.ts里导入并use：

import { createApp } from 'vue'
import App from './App.vue'
import VueQr from '@vue-qr/vue3'

const app = createApp(App) app.use(VueQr) app.mount('#app')


### 重点来了！怎么用VueQr实现各种自定义样式？满足产品的奇奇怪怪需求
产品一开始只要求改主色、背景色、加小logo，后来又加了圆角、定位点换成渐变色、中间加“扫码领券”四个字，这些需求VueQr居然都能覆盖，我整理了几个常用的配置项，附在模板里的例子给大家参考：
```vue
<template>
  <div class="qr-container">
    <vue-qr
      :text="qrText"
      :size="200"
      :margin="10"
      colorDark="#2c3e50"
      colorLight="#f5f7fa"
      :logoSrc="logoUrl"
      :logoScale="0.2"
      :logoMargin="5"
      :logoBackgroundColor="white"
      :dotColor="dotColorObj"
      :cornerSquareColor="cornerSquareColor"
      :cornerDotColor="cornerDotColor"
      :qrMargin="0"
      :qrRadius="20"
      :whiteMargin="true"
      :textMargin="30"
      :text="qrText"
      :textString="textString"
      :textColor="#e74c3c"
      :textSize="14"
      :textAlign="2"
      renderAs="canvas"
      :download="true"
      downloadFileName="我的专属领券码"
    />
  </div>
</template>
<script setup>
import { ref, computed } from 'vue'
import VueQr from '@vue-qr/vue3'
// 二维码的内容，比如用户的专属分享链接
const qrText = ref('https://example.com/share/123456')
// 中间logo的地址，可以是本地路径也可以是网络地址
const logoUrl = ref('https://example.com/logo.png')
// 中间的文字内容
const textString = ref('扫码领50元优惠券')
// 定义渐变的颜色对象，这里注意dotColor、cornerSquareColor这些如果是渐变，要传对象，不是字符串
const dotColorObj = computed(() => {
  return {
    // 渐变类型，linear是线性，radial是径向
    type: 'linear',
    // 渐变的方向，0是从上到下，90是从左到右，180是从下到上，270是从右到左
    rotation: 45,
    // 渐变的颜色数组，position是百分比，color是颜色值
    colorStops: [
      { position: 0, color: '#e74c3c' },
      { position: 1, color: '#c0392b' }
    ]
  }
})
// 定位点的外层正方形颜色，也可以传渐变
const cornerSquareColor = ref('#2980b9')
// 定位点的内层圆点颜色
const cornerDotColor = ref('#3498db')
</script>
<style scoped>
.qr-container {
  display: flex;
  justify-content: center;
  align-items: center;
  height: 100vh;
  background-color: #f0f2f5;
}
</style>

这里面每个配置项我都在旁边加了小注释,不过再挑几个容易踩坑的讲细一点：

logoSrc：如果是本地的图片，在Vue3的Vite项目里，要注意路径问题，不能直接写./assets/logo.png，要用import.meta.url配合new URL()引入，不然打包之后图片可能找不到，改成这样就行：
```
const logoUrl = ref(new URL('./assets/logo.png', import.meta.url).href)
```
dotColor：这个是控制二维码中间那些小点点的颜色的，之前qrcode.vue@next只能改整个码的颜色，这里可以单独改小点点，甚至可以传渐变，产品的渐变需求就是靠这个实现的；
qrRadius：这个是控制二维码整个区域的圆角的，单位是px，不过要注意，只有当renderAs是canvas的时候才能生效，svg渲染模式好像目前不支持圆角；
download：这个属性是让二维码可以被点击下载的，downloadFileName是下载时的文件名，很实用，用户如果想保存自己的专属码，直接点就行；
textAlign：这个是控制底部嵌入文本的对齐方式的，0是左对齐，1是居中对齐，2是右对齐，默认是1；
logoMargin：这个是控制logo周围留白的宽度的，加上会让logo和二维码内容看起来更协调，不会挤在一起。

很多人关心的兼容性问题！VueQr在不同浏览器、不同设备上表现怎么样？

兼容性这块是我特意测试过的,因为我们的营销页要覆盖iOS、Android的微信、支付宝、抖音小程序内嵌H5，还有PC端的Chrome、Firefox、Edge、Safari（包括旧版的Safari 12+）。测试结果还是比较满意的：

canvas渲染模式：在所有现代浏览器上都没问题，包括微信、支付宝、抖音的内嵌WebView，PC端的旧版Safari 12+也能正常显示；
svg渲染模式：兼容性稍微差一点，比如微信iOS端的内嵌WebView有时候会有一点点错位，不过错位的概率很低，而且只有当二维码内容特别复杂的时候才会出现，所以如果对兼容性要求特别高，建议优先用canvas渲染模式；
旧版浏览器（比如IE11）：肯定不支持，不过现在很少有项目还要兼容IE11了吧？如果必须兼容的话，可能得用qrcodejs2配合一些polyfill，不过qrcodejs2的自定义样式就没那么全了。

除了VueQr，还有没有更轻量的方案？比如如果我只需要生成最基础的二维码，不需要自定义太多样式

如果你的项目里不需要加logo、渐变、圆角这些复杂的东西，只需要生成最基础的黑白二维码，那可以用qrcodejs2，这个库超级轻量，压缩之后只有几KB，而且支持Vue3，虽然没有封装成Vue组件，但用起来也很简单。说下qrcodejs2的快速用法：

安装：
```
npm install qrcodejs2 --save
```

在Vue3的<script setup>里用：

<template>
<div class="qr-container">
 <!-- 这里要放一个空的div，用来挂载生成的二维码 -->
 <div ref="qrRef"></div>
</div>
</template>

``` 这里注意，qrcodejs2加logo需要自己写canvas的绘图代码，就是先生成二维码的canvas，然后把logo画在中间，稍微麻烦一点，但如果项目里不需要这个功能，用它还是很合适的。

最后再补充几个生成二维码时的避坑小技巧

二维码的内容不要太长：二维码的容错率越高、内容越长，生成的二维码就越复杂，扫描的时候就越慢，甚至可能扫不出来，所以如果你的内容很长，比如是一个大的JSON对象，建议先把它转成短链接，再生成二维码；
容错率的选择：容错率有四个等级，L（7%）、M（15%）、Q（25%）、H（30%），如果要加logo或者二维码可能会被磨损（比如打印在传单上），建议选H；如果只是线上使用，不需要加logo，选M就行，能让二维码简单一点，扫描更快；
大小的设置：二维码的大小不要太小，比如H5页面里的二维码，最小不要小于150px，否则手机扫描的时候可能会识别不出来；
颜色的选择：二维码的主色和背景色的对比度一定要高，比如主色用深色，背景色用浅色，或者反过来，不要用太相近的颜色，不然扫描的时候会有问题；
如果是嵌入在图片里的二维码,要注意不要被其他元素遮挡，尤其是定位点，三个定位点是扫描时最重要的部分，一旦被遮挡，大概率扫不出来。

好了,以上就是我整理的Vue3生成二维码的全部内容，从方案选择、安装配置、自定义样式、兼容性到避坑技巧都讲了，希望能帮到大家，如果还有其他问题，欢迎在评论区留言讨论。