Vue 3 二维码扫描终极指南：轻松集成 html5-qrcode，让你的应用“码”力全开！

哈喽，各位代码魔法师们！👋

你是否曾想过，在你的 Vue 应用中加入一个炫酷的二维码扫描功能？比如，扫码登录、扫码支付、或者扫码签到？听起来是不是很酷？今天，我们就来揭秘如何使用 html5-qrcode 这个神器，在 Vue 3 项目中轻松实现二维码扫描功能。准备好了吗？让我们一起“码”上出发！

html5-qrcode 是何方神圣？

html5-qrcode 是一个功能强大的 HTML5 二维码和条形码扫描库。它非常轻量，而且不依赖任何特定的 UI 框架（比如 jQuery），这意味着它和我们心爱的 Vue 3 是天作之合！

它的超能力包括：

• ✅ 直接在浏览器中扫描，无需后端处理。
• ✅ 支持摄像头扫描和本地图片文件扫描。
• ✅ 高度可定制，你可以随心所欲地调整扫描界面。
• ✅ 跨浏览器兼容性良好。

听起来是不是已经迫不及待了？别急，我们马上动手！

集成步骤

第一步：准备你的“魔法工坊”

首先，你需要一个 Vue 3 项目。如果你还没有，可以用 Vite 快速创建一个：

npm create vite@latest my-qrcode-app -- --template vue
cd my-qrcode-app

接下来，请出我们今天的主角——html5-qrcode：

npm install html5-qrcode

安装完成后，我们的准备工作就绪，可以开始施展魔法了！

第二步：召唤二维码扫描器

让我们来创建一个 QrCodeScanner.vue 组件，它将成为我们扫描器的“家”。

<template>
  <div class="min-h-screen bg-gray-50 flex items-center justify-center p-4">
    <div class="w-full max-w-md">
      <div class="bg-white shadow-lg rounded-lg p-8 space-y-6">
        <h2 class="text-2xl font-bold text-gray-800 text-center">
          Vue 3 二维码扫描器
        </h2>

        <div
          id="reader"
          ref="reader"
          class="w-full border-2 border-gray-200 rounded-lg overflow-hidden"
        ></div>

        <div
          v-if="scanResult"
          class="mt-6 p-4 bg-green-50 border border-green-200 rounded-lg"
        >
          <h3 class="text-lg font-semibold text-green-800 mb-2">扫描结果：</h3>
          <p class="text-green-700 break-all">{{ scanResult }}</p>
        </div>
      </div>
    </div>
  </div>
</template>

<script setup>
import { ref, onMounted, onBeforeUnmount } from "vue";
import { Html5QrcodeScanner } from "html5-qrcode";

const reader = ref(null);
const scanResult = ref("");
let html5QrcodeScanner = null;

const onScanSuccess = (decodedText, decodedResult) => {
  console.log(`扫描成功！结果: ${decodedText}`, decodedResult);
  scanResult.value = decodedText;
  stopScan();
};

const onScanFailure = (error) => {
  // console.warn(`扫描失败: ${error}`);
};

const startScan = () => {
  if (reader.value) {
    html5QrcodeScanner = new Html5QrcodeScanner(
      reader.value.id,
      {
        fps: 10,
        qrbox: { width: 250, height: 250 },
        rememberLastUsedCamera: true,
      },
      false
    );
    html5QrcodeScanner.render(onScanSuccess, onScanFailure);
  }
};

const stopScan = () => {
  if (html5QrcodeScanner) {
    html5QrcodeScanner.clear().catch((error) => {
      console.error("停止扫描失败.", error);
    });
  }
};

onMounted(() => {
  startScan();
});

onBeforeUnmount(() => {
  stopScan();
});
</script>

第三步：见证奇迹的时刻

现在，你只需要在你的 App.vue 或者任何其他页面中引入并使用 QrCodeScanner 组件：

<template>
  <main>
    <QrCodeScanner />
  </main>
</template>

<script setup>
import QrCodeScanner from "./components/QrCodeScanner.vue";
</script>

运行你的项目 (npm run dev)，打开浏览器，授权摄像头权限，然后……见证奇迹吧！将一个二维码对准摄像头，扫描结果会立刻出现在页面上。

兼容性和扩展性

为了让你更全面地了解 html5-qrcode，这里补充一些额外的知识点：

跨框架的“瑞士军刀”

html5-qrcode 最酷的一点是它的“零依赖”特性。这意味着它不局限于任何特定的前端框架。除了我们今天演示的 Vue 3，你还可以在以下框架中轻松使用它：

• React
• Angular
• Svelte
• 甚至在没有框架的原生 JavaScript 项目中！

只要有浏览器和 DOM，它就能大显身手。

不仅仅是二维码

虽然我们称之为“二维码扫描库”，但它的能力远不止于此。它支持多种条码格式，几乎涵盖了所有常见类型：

• 二维码 (QR Code)
• Aztec Code
• Codabar
• Code 39, Code 93, Code 128
• Data Matrix
• EAN-8, EAN-13
• ITF (Interleaved 2 of 5)
• MaxiCode
• PDF417
• UPC-A, UPC-E

这使得它不仅能用于扫码登录、付款，还能用于仓储管理、商品追溯等多种场景。

强大的兼容性

html5-qrcode 依赖于 getUserMedia API 来访问摄像头，这是一个现代浏览器的标准功能。因此，它在主流浏览器上都有很好的支持：

浏览器	桌面端支持	移动端支持
Chrome	✅	✅
Firefox	✅	✅
Safari	✅ (11+)	✅ (11+)
Edge	✅	✅
Opera	✅	✅
微信/企业微信	✅	✅

注意：在生产环境中，请务必确保你的网站通过 HTTPS 协议提供服务，因为浏览器出于安全考虑，通常只在 HTTPS 环境下才允许调用摄像头 API。

总结

看，是不是超级简单？通过 html5-qrcode，我们只用了几十行代码，就为 Vue 3 应用赋予了强大的二维码扫描能力。你不仅学会了如何集成它，还了解了如何启动、停止扫描以及处理扫描结果。

现在，轮到你了！发挥你的想象力，将这个功能应用到你的项目中去吧。无论是做一个有趣的个人项目，还是为你的产品增加一个实用的功能，二维码扫描都将是一个不错的选择。