qrcode.vue 3.9.0 → 3.10.0

package/CHANGELOG.md

@@ -1,3 +1,27 @@
+## [3.10.0] - 2026-06-13
+
+### Feature
+
+- Add `crossOrigin` support to `imageSettings` for both Canvas and SVG logo images.
+- Expose `toDataURL` and `download` methods via template ref on `QrcodeCanvas`.
+- Expose `toDataURL` and `download` methods via template ref on `QrcodeSvg`.
+- `QrcodeVue` now forwards the above template ref methods based on `render-as`.
+
+### Bugfix
+
+- Remove `aria-label` from rendered output to avoid leaking encoded `value`.
+- Fix declaration output path in Rollup build (`dist/src/index.d.ts` → `dist/index.d.ts`).
+
+## [3.9.1]
+
+### Bugfix
+
+- Remove static `useId` import to fix build errors for Vue < 3.5 (`No matching export for import "useId"`).
+
+### Feature
+
+- Add `id` prop for SSR hydration consistency. Pass `useId()` to ensure matching IDs between server and client.
+
 ## [3.9.0]
 
 ### Feature

package/README-zh_cn.md

@@ -4,7 +4,7 @@
 
 🔒 如果你正在使用 Vue 2，请保持 `qrcode.vue` 的版本为 `1.x`;
 
-一款 Vue.js 二维码组件，同时支持 Vue 2 和 Vue 3.
+一款 Vue.js 二维码组件，同时支援 Vue 2 和 Vue 3.
 
 [![GitHub license](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/scopewu/qrcode.vue/blob/main/LICENSE)
 
@@ -104,6 +104,7 @@ createApp({
     // x: 10,
     // y: 10,
     excavate: true,
+    // crossOrigin: 'anonymous', // 如需把 canvas 导出为图片，请设置此项。
   })
 
   // 可传入渐变相关的属性，支持渐变：
@@ -184,11 +185,50 @@ createApp({
     // 使用此选项可确保图像周围的边缘清晰。嵌入透明图像时也很有用。
     excavate?: boolean,
     borderRadius?: number, // 图片的边框圆角。
+    crossOrigin?: 'anonymous' | 'use-credentials' | '', // 图片的 CORS 属性。如需导出 canvas 为图片，请设置此项。
   }
   ```
 
 二维码图片 logo 配置。
 
+### `radius`
+
+- 类型：`number`
+- 默认值：`0`
+
+每个二维码模块的圆角半径，相对于模块宽度的比例。接受 `0` 到 `0.5` 的值。
+
+- `0`（默认）- 方形模块，直角
+- `0.5` - 最大圆角，模块变为圆形
+
+圆角是上下文感知的：相邻深色模块之间的内角保持直角，外角则圆角化。
+
+```html
+<qrcode-vue value="test" :radius="0.35" />
+```
+
+### `id`
+
+- 类型：`string`
+- 默认值：`undefined`
+
+自定义 SVG 内部元素（渐变、裁剪路径）的 ID。SSR 水合一致性需要此属性 — 传入 `useId()` 以确保服务端和客户端生成匹配的 ID。
+
+```html
+<script setup>
+  // 仅 vue 3.5+
+  import { useId } from 'vue'
+  const uid = useId()
+
+  // vue 3.4 及以下版本
+  // const uid = 'qrcode-1'
+  // const uid2 = 'qrcode-2'
+</script>
+<qrcode-svg value="test" :id="uid" render-as="svg" />
+```
+
+省略时使用模块级计数器，该计数器在多请求的 SSR 环境中不安全。
+
 ### `gradient`
 
 - 类型: `boolean`
@@ -217,28 +257,60 @@ createApp({
 
 渐变的结束颜色。
 
-### `radius`
+### `class`
 
-- 类型：`number`
-- 默认值：`0`
+- 类型：`string`
+- 默认值：`''`
 
-每个二维码模块的圆角半径，相对于模块宽度的比例。接受 `0` 到 `0.5` 的值。
+传递给二维码根元素的类名。
 
-- `0`（默认）- 方形模块，直角
-- `0.5` - 最大圆角，模块变为圆形
+## 模板 Ref 方法（`QrcodeCanvas` / `QrcodeSvg`）
 
-圆角是上下文感知的：相邻深色模块之间的内角保持直角，外角则圆角化。
+`QrcodeCanvas` 和 `QrcodeSvg` 都通过模板 ref 暴露以下方法。`QrcodeVue` 会根据当前的 `render-as` 转发这些方法。
+
+### `QrcodeCanvas`
 
 ```html
-<qrcode-vue value="test" :radius="0.35" />
+<script setup>
+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" />
 ```
 
-### `class`
+| 方法 | 签名 | 说明 |
+|------|------|------|
+| `toDataURL` | `(type?: string, quality?: number) => string \| undefined` | 将 canvas 转换为 Data URL。 |
+| `download` | `(filename?: string) => void` | 触发下载二维码 PNG 图片。 |
 
-- 类型：`string`
-- 默认值：`''`
+> **CORS 注意：** 当二维码包含跨域 Logo 图片时，请确保设置 `imageSettings.crossOrigin: 'anonymous'`，且图片服务器返回 `Access-Control-Allow-Origin` 响应头。否则 canvas 会被"污染"，导致 `toDataURL` / `download` 抛出 `SecurityError`。
 
-传递给二维码根元素的类名。
+### `QrcodeSvg`
+
+```html
+<script setup>
+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" />
+```
+
+| 方法 | 签名 | 说明 |
+|------|------|------|
+| `toDataURL` | `() => string \| undefined` | 将 SVG 元素转换为 Data URL。 |
+| `download` | `(filename?: string) => void` | 触发下载二维码 SVG 图片。 |
 
 ## `QrcodeVue` 3.5+
 

package/README.md

@@ -6,7 +6,7 @@
 
 A Vue.js component to generate [QRCode](https://en.wikipedia.org/wiki/QR_code). Both support Vue 2 and Vue 3.
 
-[中文](./README-zh_cn.md) | [日本語](./README-ja.md)
+[简体中文](./README-zh_cn.md) | [繁體中文](./README.zh-hant.md) | [日本語](./README-ja.md)
 
 ## install
 
@@ -107,6 +107,7 @@ When you use the component with Vue 3 with `TypeScript`:
     // x: 10,
     // y: 10,
     excavate: true,
+    // crossOrigin: 'anonymous', // Set this when you need to export the canvas to an image.
   })
 
   const gradient = ref(false)
@@ -182,11 +183,50 @@ The foreground color of qrcode.
     width: number,  // The height of image
     excavate?: boolean, // Whether or not to "excavate" the modules around the image.
     borderRadius?: number, // The border radius of image.
+    crossOrigin?: 'anonymous' | 'use-credentials' | '', // The CORS attribute for the image. Useful when exporting canvas to an image.
   }
   ```
 
 The settings to support qrcode image logo.
 
+### `radius`
+
+- Type: `number`
+- Default: `0`
+
+The corner radius of each QR module, as a ratio of the module width. Accepts values from `0` to `0.5`.
+
+- `0` (default) - square modules with sharp corners
+- `0.5` - maximum rounding, modules become circles
+
+The rounding is context-aware: inner corners between adjacent dark modules remain sharp, while outer corners are rounded.
+
+```html
+<qrcode-vue value="test" :radius="0.35" />
+```
+
+### `id`
+
+- Type: `string`
+- Default: `undefined`
+
+Custom ID for SVG internal elements (gradients, clip-paths). Required for SSR hydration consistency — pass `useId()` to ensure server and client generate matching IDs.
+
+```html
+<script setup>
+  // vue 3.5+ only
+  import { useId } from 'vue'
+  const uid = useId()
+
+  // older vue versions (3.4 and below)
+  // const uid = 'qrcode-1'
+  // const uid2 = 'qrcode-2'
+</script>
+<qrcode-svg value="test" :id="uid" render-as="svg" />
+```
+
+When omitted, a module-level counter is used, which is not SSR-safe across multiple requests.
+
 ### `gradient`
 
 - Type: `boolean`
@@ -215,28 +255,60 @@ The start color of the gradient.
 
 The end color of the gradient.
 
-### `radius`
+### `class`
 
-- Type: `number`
-- Default: `0`
+- Type: `string`
+- Default: `''`
 
-The corner radius of each QR module, as a ratio of the module width. Accepts values from `0` to `0.5`.
+The class name of qrcode element.
 
-- `0` (default) - square modules with sharp corners
-- `0.5` - maximum rounding, modules become circles
+## Template Ref Methods (`QrcodeCanvas` / `QrcodeSvg`)
 
-The rounding is context-aware: inner corners between adjacent dark modules remain sharp, while outer corners are rounded.
+Both `QrcodeCanvas` and `QrcodeSvg` expose the following methods via template ref. `QrcodeVue` forwards them based on the current `render-as`.
+
+### `QrcodeCanvas`
 
 ```html
-<qrcode-vue value="test" :radius="0.35" />
+<script setup>
+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" />
 ```
 
-### `class`
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `toDataURL` | `(type?: string, quality?: number) => string \| undefined` | Convert the canvas to a data URL. |
+| `download` | `(filename?: string) => void` | Trigger a download of the QR code as a PNG image. |
 
-- Type: `string`
-- Default: `''`
+> **CORS note:** When the QR code includes a cross-origin logo image, make sure to set `imageSettings.crossOrigin: 'anonymous'` and that the image server responds with the `Access-Control-Allow-Origin` header. Otherwise the canvas becomes "tainted" and `toDataURL` / `download` will throw a `SecurityError`.
 
-The class name of qrcode element.
+### `QrcodeSvg`
+
+```html
+<script setup>
+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" />
+```
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `toDataURL` | `() => string \| undefined` | Convert the SVG element to a data URL. |
+| `download` | `(filename?: string) => void` | Trigger a download of the QR code as an SVG image. |
 
 ## `QrcodeVue` 3.5+
 

package/README.zh-hant.md

@@ -0,0 +1,360 @@
+# qrcode.vue
+
+⚠️ 如果你正在使用 Vue 3，請升級 `qrcode.vue` 到 `3.x`;
+
+🔒 如果你正在使用 Vue 2，請保持 `qrcode.vue` 的版本爲 `1.x`;
+
+一款 Vue.js 二維碼組件(QR Code)，同時支援 Vue 2 和 Vue 3.
+
+[![GitHub license](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/scopewu/qrcode.vue/blob/main/LICENSE)
+
+## 快速開始
+
+快速添加 `qrcode.vue` 組件到項目中
+
+```bash
+npm install --save qrcode.vue # yarn add qrcode.vue
+```
+
+```
+dist/
+|--- qrcode.vue.cjs.js         // CommonJS
+|--- qrcode.vue.esm.js         // ES module
+|--- qrcode.vue.browser.js     // UMD for browser or require.js or CommonJS
+|--- qrcode.vue.browser.min.js // UMD Minimum size
+```
+
+## 使用
+
+e.g.
+
+```javascript
+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')
+```
+
+或者，在獨有單文件擴展 `*.vue` 中使用：
+
+```html
+<template>
+  <qrcode-vue :value="value" :size="size" level="H" />
+</template>
+<script>
+  import QrcodeVue from 'qrcode.vue'
+
+  export default {
+    data() {
+      return {
+        value: 'https://example.com',
+        size: 300,
+      }
+    },
+    components: {
+      QrcodeVue,
+    },
+  }
+</script>
+```
+
+在 Vue 3 中配合 `TypeScript` 使用：
+
+```html
+<template>
+  <qrcode-vue
+    :value="value"
+    :level="level"
+    :render-as="renderAs"
+    :background="background"
+    :foreground='foreground'
+    :gradient="gradient"
+    :gradient-type="gradientType"
+    :gradient-start-color="gradientStartColor"
+    :gradient-end-color="gradientEndColor"
+    :image-settings='imageSettings'
+    :radius="radius"
+  />
+</template>
+<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('qrcode')
+  const level = ref<Level>('M')
+  const renderAs = ref<RenderAs>('svg')
+  const background = ref('#ffffff')
+  const foreground = ref('#000000')
+  const margin = ref(0)
+  
+  // 可傳入二維碼圖片相關的屬性，支持二維碼 LOGO；
+  const imageSettings = ref<ImageSettings>({
+    src: 'https://github.com/scopewu.png',
+    width: 30,
+    height: 30,
+    // x: 10,
+    // y: 10,
+    excavate: true,
+    // crossOrigin: 'anonymous', // 如需把 canvas 導出為圖片，請設置此項。
+  })
+
+  // 可傳入漸變相關的屬性，支持漸變：
+  const gradient = ref(false)
+  const gradientType = ref<GradientType>('linear')
+  const gradientStartColor = ref('#000000')
+  const gradientEndColor = ref('#38bdf8')
+  // 可傳入圓角半徑：
+  const radius = ref(0)
+</script>
+```
+
+## Component props
+
+### `value`
+
+- 類型：`string`
+- 默認值：`''`
+
+二維碼的內容值。
+
+### `size`
+
+- 類型：`number`
+- 默認值：`100`
+
+二維碼大小。
+
+### `render-as`
+
+- 類型：`RenderAs('canvas' | 'svg')`
+- 默認值：`canvas`
+
+生成二維碼的 HTML 標籤，可選 `canvas` 或 `svg`。其中 `svg` 可以用於 SSR。
+
+### `margin`
+
+- 類型：`number`
+- 默認值：`0`
+
+定義空白區的寬度應該是多少。
+
+### `level`
+
+- 類型：`Level('L' | 'M' | 'Q' | 'H')`
+- 默認值：`L`
+
+二維碼的容錯能力等級，取值爲 'L', 'M', 'Q', 'H' 之一。瞭解更多，[維基百科：QR_code](https://en.wikipedia.org/wiki/QR_code#Error_correction)。
+
+### `background`
+
+- 類型：`string`
+- 默認值：`#ffffff`
+
+二維碼背景顏色。
+
+### `foreground`
+
+- 類型：`string`
+- 默認值：`#000000`
+
+二維碼前景顏色。
+
+### `image-settings`
+
+- 類型: `ImageSettings`
+- 默認值: `{}`
+
+  ```ts
+  export type ImageSettings = {
+    src: string, // 圖片的地址。
+    x?: number,  // 水平橫向偏移。沒有設定值時，圖片劇中
+    y?: number,  // 垂直豎向偏移。沒有設定值時，圖片劇中
+    height: number, // 圖片的高度
+    width: number,  // 圖片的寬度
+    // 是否“挖掘”圖像周圍的模塊。
+    // 這意味着嵌入圖像重疊的任何模塊都將使用背景顏色。
+    // 使用此選項可確保圖像周圍的邊緣清晰。嵌入透明圖像時也很有用。
+    excavate?: boolean,
+    borderRadius?: number, // 圖片的邊框圓角。
+    crossOrigin?: 'anonymous' | 'use-credentials' | '', // 圖片的 CORS 屬性。如需導出 canvas 為圖片，請設置此項。
+  }
+  ```
+
+二維碼圖片 logo 配置。
+
+### `radius`
+
+- 類型：`number`
+- 默認值：`0`
+
+每個二維碼模塊的圓角半徑，相對於模塊寬度的比例。接受 `0` 到 `0.5` 的值。
+
+- `0`（默認）- 方形模塊，直角
+- `0.5` - 最大圓角，模塊變爲圓形
+
+圓角是上下文感知的：相鄰深色模塊之間的內角保持直角，外角則圓角化。
+
+```html
+<qrcode-vue value="test" :radius="0.35" />
+```
+
+### `id`
+
+- 類型：`string`
+- 默認值：`undefined`
+
+自定義 SVG 內部元素（漸變、裁剪路徑）的 ID。SSR 水合一致性需要此屬性 — 傳入 `useId()` 以確保服務端和客戶端生成匹配的 ID。
+
+```html
+<script setup>
+  // 僅 vue 3.5+
+  import { useId } from 'vue'
+  const uid = useId()
+
+  // vue 3.4 及以下版本
+  // const uid = 'qrcode-1'
+  // const uid2 = 'qrcode-2'
+</script>
+<qrcode-svg value="test" :id="uid" render-as="svg" />
+```
+
+省略時使用模塊級計數器，該計數器在多請求的 SSR 環境中不安全。
+
+### `gradient`
+
+- 類型: `boolean`
+- 默認值: `false`
+
+啓用二維碼的漸變填充。
+
+### `gradient-type`
+
+- 類型: `GradientType('linear' | 'radial')`
+- 默認值: `linear`
+
+指定漸變類型。
+
+### `gradient-start-color`
+
+- 類型: `string`
+- 默認值: `#000000`
+
+漸變的起始顏色。
+
+### `gradient-end-color`
+
+- 類型: `string`
+- 默認值: `#ffffff`
+
+漸變的結束顏色。
+
+### `class`
+
+- 類型：`string`
+- 默認值：`''`
+
+傳遞給二維碼根元素的類名。
+
+## 模板 Ref 方法（`QrcodeCanvas` / `QrcodeSvg`）
+
+`QrcodeCanvas` 與 `QrcodeSvg` 都透過模板 ref 暴露以下方法。`QrcodeVue` 會根據目前的 `render-as` 轉發這些方法。
+
+### `QrcodeCanvas`
+
+```html
+<script setup>
+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" />
+```
+
+| 方法 | 簽名 | 說明 |
+|------|------|------|
+| `toDataURL` | `(type?: string, quality?: number) => string \| undefined` | 將 canvas 轉換為 Data URL。 |
+| `download` | `(filename?: string) => void` | 觸發下載二維碼 PNG 圖片。 |
+
+> **CORS 注意：** 當二維碼包含跨域 Logo 圖片時，請確保設置 `imageSettings.crossOrigin: 'anonymous'`，且圖片伺服器返回 `Access-Control-Allow-Origin` 響應頭。否則 canvas 會被「污染」，導致 `toDataURL` / `download` 拋出 `SecurityError`。
+
+### `QrcodeSvg`
+
+```html
+<script setup>
+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" />
+```
+
+| 方法 | 簽名 | 說明 |
+|------|------|------|
+| `toDataURL` | `() => string \| undefined` | 將 SVG 元素轉換為 Data URL。 |
+| `download` | `(filename?: string) => void` | 觸發下載二維碼 SVG 圖片。 |
+
+## `QrcodeVue` 3.5+
+
+`QrcodeVue` 3.5+ 後導出獨立的 `QrcodeCanvas` 和 `QrcodeSvg` 組件，爲此修改了 rollup 的配置：
+
+```
+// rollup.config.js
+
+-    exports: 'default',
++    exports: 'named',
+```
+
+現在在 common.js 和 cdn 直接引用 `QrcodeVue` 需要使用 `default` 字段：
+
+```js
+const QrcodeVue = require('qrcode.vue').default
+const { default: QrcodeVue, QrcodeCanvas, QrcodeSvg } = require('qrcode.vue')
+```
+
+```html
+<!--With HTML-->
+<div id="root">
+  <p class="flex space-x">
+  <qrcode-vue :value="test" render-as="svg"></qrcode-vue>
+  <qrcode-canvas :value="test"></qrcode-canvas>
+  </p>
+<p><input v-model="test" /></p>
+</div>
+<script src="https://cdn.jsdelivr.net/npm/vue@3.5/dist/vue.global.prod.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/qrcode.vue@3.5/dist/qrcode.vue.browser.min.js"></script>
+
+<script>
+Vue.createApp({
+  data() { return {
+    test: 'Hello World',
+  }},
+  components: {
+    QrcodeVue: QrcodeVue.default,
+    QrcodeCanvas: QrcodeVue.QrcodeCanvas,
+  },
+}).mount('#root')
+</script>
+```
+
+## 軟件許可
+
+copyright &copy; 2021 scopewu, license by [MIT](https://github.com/scopewu/qrcode.vue/blob/main/LICENSE)