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.jsCommonJS
qrcode.vue.esm.jsES module
qrcode.vue.browser.min.jsUMD (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

屬性類型預設值說明
valuestring''QR Code 編碼的內容。
sizenumber100QR Code 元素的尺寸（寬與高），單位為像素。
render-as'canvas' | 'svg''canvas'渲染格式。使用 svg 以支援 SSR。
marginnumber0QR Code 靜默區（留白）寬度。
level'L' | 'M' | 'Q' | 'H''L'容錯等級。等級越高，可恢復的損壞越多。
backgroundstring'#ffffff'QR Code 背景色。
foregroundstring'#000000'QR Code 模組的前景色。
radiusnumber0模組圓角比例（0 到 0.5）。0.5 時模組變為圓形。
gradientbooleanfalse啟用 QR Code 模組的漸層填充。
gradient-type'linear' | 'radial''linear'啟用 gradient 時使用的漸層類型。
gradient-start-colorstring'#000000'漸層起始顏色。
gradient-end-colorstring'#ffffff'漸層結束顏色。
image-settingsImageSettings{}Logo 圖片設定，詳見下方說明。
idstringundefinedSVG 內部元素的自訂 ID。傳入 useId() 以確保 SSR 水合一致性。
classstring''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 轉發這些方法：

組件方法簽名說明
QrcodeCanvastoDataURL(type?: string, quality?: number) => string | undefined將 QR Code 轉換為 Data URL。
download(filename?: string) => void觸發下載 QR Code 圖片。
QrcodeSvgtoDataURL() => 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 }}

設定

圖片設定