qrcode.vue

Star {{ stargazersCount }}

用於產生 QR Code 的 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 '' QR Code 編碼的內容。
size number 100 QR Code 元素的尺寸（寬與高），單位為像素。
render-as 'canvas' | 'svg' 'canvas' 渲染格式。使用 svg 以支援 SSR。
margin number 0 QR Code 靜默區（留白）寬度。
level 'L' | 'M' | 'Q' | 'H' 'L' 容錯等級。等級越高，可恢復的損壞越多。
background string '#ffffff' QR Code 背景色。
foreground string '#000000' QR Code 模組的前景色。
radius number 0 模組圓角比例（0 到 0.5）。0.5 時模組變為圓形。
gradient boolean false 啟用 QR Code 模組的漸層填充。
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 '' QR Code 元素的 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 將 QR Code 轉換為 Data URL。
download (filename?: string) => void 觸發下載 QR Code 圖片。
QrcodeSvg toDataURL () => string | undefined 將 SVG 元素轉換為 Data URL。
download (filename?: string) => void 觸發下載 QR Code 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 }}

設定

圖片設定