qrcode.vue 3.9.1 → 3.11.0

package/dist/qrcode.vue.cjs.js

@@ -1,8 +1,8 @@
 /*!
- * qrcode.vue v3.9.1
+ * qrcode.vue v3.11.0
  * A Vue.js component to generate QRCode. Both support Vue 2 and Vue 3
  * © 2017-PRESENT @scopewu(https://github.com/scopewu)
- * MIT License.
+ * @license MIT.
  */
 'use strict';
 
@@ -1073,6 +1073,14 @@ function useQRCode(props) {
     });
     return { margin: margin, numCells: numCells, cells: cells, fgPath: fgPath, imageProps: imageProps, imageBorderProps: imageBorderProps };
 }
+function downloadDataURLAsFile(data, filename) {
+    var link = document.createElement('a');
+    link.download = filename;
+    link.href = data;
+    document.body.appendChild(link);
+    link.click();
+    document.body.removeChild(link);
+}
 var QRCodeProps = {
     value: {
         type: String,
@@ -1098,38 +1106,32 @@ var QRCodeProps = {
     },
     margin: {
         type: Number,
-        required: false,
         default: DEFAULT_MARGIN,
+        validator: function (m) { return m >= 0; },
     },
     imageSettings: {
         type: Object,
-        required: false,
         default: function () { return ({}); },
     },
     gradient: {
         type: Boolean,
-        required: false,
         default: false,
     },
     gradientType: {
         type: String,
-        required: false,
         default: 'linear',
         validator: function (t) { return ['linear', 'radial'].indexOf(t) > -1; },
     },
     gradientStartColor: {
         type: String,
-        required: false,
         default: '#000',
     },
     gradientEndColor: {
         type: String,
-        required: false,
         default: '#fff',
     },
     radius: {
         type: Number,
-        required: false,
         default: 0,
         validator: function (r) { return !isNaN(r) && r >= 0 && r <= 0.5; },
     },
@@ -1147,8 +1149,9 @@ var QRCodeVueProps = __assign(__assign({}, QRCodeProps), { renderAs: {
 var QrcodeSvg = vue.defineComponent({
     name: 'QRCodeSvg',
     props: QRCodeProps,
-    setup: function (props) {
+    setup: function (props, ctx) {
         var _a = useQRCode(props), numCells = _a.numCells, fgPath = _a.fgPath, imageProps = _a.imageProps, imageBorderProps = _a.imageBorderProps;
+        var svgEl = vue.ref();
         var uid = getUid(props.id);
         var qrGradientId = "qrcode.vue-gradient-".concat(uid);
         var qrLogoClipPathId = "qrcode.vue-logo-clip-path-".concat(uid);
@@ -1197,15 +1200,32 @@ var QrcodeSvg = vue.defineComponent({
                 }),
             ]);
         });
+        var getSvgDataURL = function (svg) { return 'data:image/svg+xml;charset=utf-8,' +
+            encodeURIComponent('<?xml version="1.0" standalone="no"?>' + new XMLSerializer().serializeToString(svg)); };
+        ctx.expose({
+            toDataURL: function () {
+                var svg = svgEl.value;
+                if (!svg)
+                    return;
+                return getSvgDataURL(svg);
+            },
+            download: function (filename) {
+                if (filename === void 0) { filename = 'qrcode.svg'; }
+                var svg = svgEl.value;
+                if (!svg)
+                    return;
+                downloadDataURLAsFile(getSvgDataURL(svg), filename);
+            },
+        });
         return function () { return vue.h('svg', {
+            ref: svgEl,
             width: props.size,
             height: props.size,
             xmlns: 'http://www.w3.org/2000/svg',
             viewBox: "0 0 ".concat(numCells.value, " ").concat(numCells.value),
             role: 'img',
-            'aria-label': props.value,
         }, [
-            vue.h('defs', {}, [gradientVNode.value, clipPathVNode.value]),
+            vue.h('defs', {}, [gradientVNode.value, clipPathVNode.value].filter(Boolean)),
             vue.h('rect', {
                 width: '100%',
                 height: '100%',
@@ -1224,7 +1244,7 @@ var QrcodeSvg = vue.defineComponent({
                 rx: imageBorderProps.value.borderRadius,
                 ry: imageBorderProps.value.borderRadius,
             }),
-            props.imageSettings.src && imageProps.value && vue.h('image', __assign(__assign({ href: props.imageSettings.src }, imageProps.value), (imageProps.value.borderRadius > 0 ? { 'clip-path': "url(#".concat(qrLogoClipPathId, ")") } : {}))),
+            props.imageSettings.src && imageProps.value && vue.h('image', __assign({ href: props.imageSettings.src, crossorigin: props.imageSettings.crossOrigin, 'clip-path': imageProps.value.borderRadius > 0 ? "url(#".concat(qrLogoClipPathId, ")") : void 0 }, imageProps.value)),
         ]); };
     },
 });
@@ -1310,12 +1330,23 @@ var QrcodeCanvas = vue.defineComponent({
             }
         };
         vue.onMounted(generate);
-        vue.watchEffect(generate);
+        vue.watchEffect(generate, { flush: 'post' });
+        ctx.expose({
+            toDataURL: function (type, quality) { var _a; return (_a = canvasEl.value) === null || _a === void 0 ? void 0 : _a.toDataURL(type, quality); },
+            download: function (filename) {
+                if (filename === void 0) { filename = 'qrcode.png'; }
+                var canvas = canvasEl.value;
+                if (!canvas)
+                    return;
+                downloadDataURLAsFile(canvas.toDataURL('image/png'), filename);
+            },
+        });
         return function () { return vue.h(vue.Fragment, [
-            vue.h('canvas', __assign(__assign({}, ctx.attrs), { ref: canvasEl, role: 'img', 'aria-label': props.value, style: __assign(__assign({}, ctx.attrs.style), { width: "".concat(props.size, "px"), height: "".concat(props.size, "px") }) })),
+            vue.h('canvas', __assign(__assign({}, ctx.attrs), { ref: canvasEl, role: 'img', style: __assign(__assign({}, ctx.attrs.style), { width: "".concat(props.size, "px"), height: "".concat(props.size, "px") }) })),
             props.imageSettings.src && vue.h('img', {
                 ref: imageEl,
                 src: props.imageSettings.src,
+                crossorigin: props.imageSettings.crossOrigin,
                 style: { display: 'none' },
                 onLoad: generate,
             })
@@ -1325,8 +1356,14 @@ var QrcodeCanvas = vue.defineComponent({
 var QrcodeVue = vue.defineComponent({
     name: 'Qrcode',
     props: QRCodeVueProps,
-    setup: function (props) {
+    setup: function (props, ctx) {
+        var childRef = vue.ref();
+        ctx.expose({
+            toDataURL: function (type, quality) { var _a, _b; return (_b = (_a = childRef.value) === null || _a === void 0 ? void 0 : _a.toDataURL) === null || _b === void 0 ? void 0 : _b.call(_a, type, quality); },
+            download: function (filename) { var _a, _b; return (_b = (_a = childRef.value) === null || _a === void 0 ? void 0 : _a.download) === null || _b === void 0 ? void 0 : _b.call(_a, filename); },
+        });
         return function () { return vue.h(props.renderAs === 'svg' ? QrcodeSvg : QrcodeCanvas, {
+            ref: childRef,
             value: props.value,
             size: props.size,
             margin: props.margin,

package/dist/qrcode.vue.esm.js

@@ -1,10 +1,10 @@
 /*!
- * qrcode.vue v3.9.1
+ * qrcode.vue v3.11.0
  * A Vue.js component to generate QRCode. Both support Vue 2 and Vue 3
  * © 2017-PRESENT @scopewu(https://github.com/scopewu)
- * MIT License.
+ * @license MIT.
  */
-import { defineComponent, computed, h, ref, onMounted, watchEffect, Fragment } from 'vue';
+import { defineComponent, ref, computed, h, onMounted, watchEffect, Fragment } from 'vue';
 
 /******************************************************************************
 Copyright (c) Microsoft Corporation.
@@ -1069,6 +1069,14 @@ function useQRCode(props) {
     });
     return { margin: margin, numCells: numCells, cells: cells, fgPath: fgPath, imageProps: imageProps, imageBorderProps: imageBorderProps };
 }
+function downloadDataURLAsFile(data, filename) {
+    var link = document.createElement('a');
+    link.download = filename;
+    link.href = data;
+    document.body.appendChild(link);
+    link.click();
+    document.body.removeChild(link);
+}
 var QRCodeProps = {
     value: {
         type: String,
@@ -1094,38 +1102,32 @@ var QRCodeProps = {
     },
     margin: {
         type: Number,
-        required: false,
         default: DEFAULT_MARGIN,
+        validator: function (m) { return m >= 0; },
     },
     imageSettings: {
         type: Object,
-        required: false,
         default: function () { return ({}); },
     },
     gradient: {
         type: Boolean,
-        required: false,
         default: false,
     },
     gradientType: {
         type: String,
-        required: false,
         default: 'linear',
         validator: function (t) { return ['linear', 'radial'].indexOf(t) > -1; },
     },
     gradientStartColor: {
         type: String,
-        required: false,
         default: '#000',
     },
     gradientEndColor: {
         type: String,
-        required: false,
         default: '#fff',
     },
     radius: {
         type: Number,
-        required: false,
         default: 0,
         validator: function (r) { return !isNaN(r) && r >= 0 && r <= 0.5; },
     },
@@ -1143,8 +1145,9 @@ var QRCodeVueProps = __assign(__assign({}, QRCodeProps), { renderAs: {
 var QrcodeSvg = defineComponent({
     name: 'QRCodeSvg',
     props: QRCodeProps,
-    setup: function (props) {
+    setup: function (props, ctx) {
         var _a = useQRCode(props), numCells = _a.numCells, fgPath = _a.fgPath, imageProps = _a.imageProps, imageBorderProps = _a.imageBorderProps;
+        var svgEl = ref();
         var uid = getUid(props.id);
         var qrGradientId = "qrcode.vue-gradient-".concat(uid);
         var qrLogoClipPathId = "qrcode.vue-logo-clip-path-".concat(uid);
@@ -1193,15 +1196,32 @@ var QrcodeSvg = defineComponent({
                 }),
             ]);
         });
+        var getSvgDataURL = function (svg) { return 'data:image/svg+xml;charset=utf-8,' +
+            encodeURIComponent('<?xml version="1.0" standalone="no"?>' + new XMLSerializer().serializeToString(svg)); };
+        ctx.expose({
+            toDataURL: function () {
+                var svg = svgEl.value;
+                if (!svg)
+                    return;
+                return getSvgDataURL(svg);
+            },
+            download: function (filename) {
+                if (filename === void 0) { filename = 'qrcode.svg'; }
+                var svg = svgEl.value;
+                if (!svg)
+                    return;
+                downloadDataURLAsFile(getSvgDataURL(svg), filename);
+            },
+        });
         return function () { return h('svg', {
+            ref: svgEl,
             width: props.size,
             height: props.size,
             xmlns: 'http://www.w3.org/2000/svg',
             viewBox: "0 0 ".concat(numCells.value, " ").concat(numCells.value),
             role: 'img',
-            'aria-label': props.value,
         }, [
-            h('defs', {}, [gradientVNode.value, clipPathVNode.value]),
+            h('defs', {}, [gradientVNode.value, clipPathVNode.value].filter(Boolean)),
             h('rect', {
                 width: '100%',
                 height: '100%',
@@ -1220,7 +1240,7 @@ var QrcodeSvg = defineComponent({
                 rx: imageBorderProps.value.borderRadius,
                 ry: imageBorderProps.value.borderRadius,
             }),
-            props.imageSettings.src && imageProps.value && h('image', __assign(__assign({ href: props.imageSettings.src }, imageProps.value), (imageProps.value.borderRadius > 0 ? { 'clip-path': "url(#".concat(qrLogoClipPathId, ")") } : {}))),
+            props.imageSettings.src && imageProps.value && h('image', __assign({ href: props.imageSettings.src, crossorigin: props.imageSettings.crossOrigin, 'clip-path': imageProps.value.borderRadius > 0 ? "url(#".concat(qrLogoClipPathId, ")") : void 0 }, imageProps.value)),
         ]); };
     },
 });
@@ -1306,12 +1326,23 @@ var QrcodeCanvas = defineComponent({
             }
         };
         onMounted(generate);
-        watchEffect(generate);
+        watchEffect(generate, { flush: 'post' });
+        ctx.expose({
+            toDataURL: function (type, quality) { var _a; return (_a = canvasEl.value) === null || _a === void 0 ? void 0 : _a.toDataURL(type, quality); },
+            download: function (filename) {
+                if (filename === void 0) { filename = 'qrcode.png'; }
+                var canvas = canvasEl.value;
+                if (!canvas)
+                    return;
+                downloadDataURLAsFile(canvas.toDataURL('image/png'), filename);
+            },
+        });
         return function () { return h(Fragment, [
-            h('canvas', __assign(__assign({}, ctx.attrs), { ref: canvasEl, role: 'img', 'aria-label': props.value, style: __assign(__assign({}, ctx.attrs.style), { width: "".concat(props.size, "px"), height: "".concat(props.size, "px") }) })),
+            h('canvas', __assign(__assign({}, ctx.attrs), { ref: canvasEl, role: 'img', style: __assign(__assign({}, ctx.attrs.style), { width: "".concat(props.size, "px"), height: "".concat(props.size, "px") }) })),
             props.imageSettings.src && h('img', {
                 ref: imageEl,
                 src: props.imageSettings.src,
+                crossorigin: props.imageSettings.crossOrigin,
                 style: { display: 'none' },
                 onLoad: generate,
             })
@@ -1321,8 +1352,14 @@ var QrcodeCanvas = defineComponent({
 var QrcodeVue = defineComponent({
     name: 'Qrcode',
     props: QRCodeVueProps,
-    setup: function (props) {
+    setup: function (props, ctx) {
+        var childRef = ref();
+        ctx.expose({
+            toDataURL: function (type, quality) { var _a, _b; return (_b = (_a = childRef.value) === null || _a === void 0 ? void 0 : _a.toDataURL) === null || _b === void 0 ? void 0 : _b.call(_a, type, quality); },
+            download: function (filename) { var _a, _b; return (_b = (_a = childRef.value) === null || _a === void 0 ? void 0 : _a.download) === null || _b === void 0 ? void 0 : _b.call(_a, filename); },
+        });
         return function () { return h(props.renderAs === 'svg' ? QrcodeSvg : QrcodeCanvas, {
+            ref: childRef,
             value: props.value,
             size: props.size,
             margin: props.margin,

package/llms.txt

@@ -0,0 +1,30 @@
+# qrcode.vue
+
+> A Vue.js component to generate QR codes. Version 3.x supports Vue 3 (peer dependency `vue@^3.0.0`, no runtime dependencies); Vue 2 apps use qrcode.vue 1.x. Renders to `<canvas>` or `<svg>`, with gradients, rounded modules, and embedded logo images. MIT licensed.
+
+Install: `npm install --save qrcode.vue`
+
+```ts
+import QrcodeVue, { QrcodeCanvas, QrcodeSvg } from 'qrcode.vue'
+```
+
+Key props: `value` (required), `size` (default 100), `render-as` (`canvas`|`svg`, svg works on SSR), `level` (L/M/Q/H, default L), `margin`, `background`/`foreground`, `gradient` + `gradient-type` + `gradient-start-color`/`gradient-end-color`, `radius` (0–0.5 rounded modules), `image-settings` (embedded logo: `src`, `x`/`y`, `width`/`height`, `excavate`, `borderRadius`, `crossOrigin`), `id` (SSR-safe internal SVG ids, pass `useId()`). Template-ref methods: `toDataURL()`, `download(filename)`.
+
+## Docs
+
+- [README (English)](https://github.com/scopewu/qrcode.vue/blob/main/README.md): install, usage, full props reference, template ref methods
+- [README (简体中文)](https://github.com/scopewu/qrcode.vue/blob/main/README-zh_cn.md)
+- [README (繁體中文)](https://github.com/scopewu/qrcode.vue/blob/main/README.zh-hant.md)
+- [README (日本語)](https://github.com/scopewu/qrcode.vue/blob/main/README-ja.md)
+- [CHANGELOG](https://github.com/scopewu/qrcode.vue/blob/main/CHANGELOG.md): version history and breaking changes
+
+## AI assistant resources
+
+- [SKILL.md](https://github.com/scopewu/qrcode.vue/blob/main/skills/qrcode-vue/SKILL.md): Agent Skills–format skill with props table, recipes, and pitfalls. Also shipped in the npm package at `node_modules/qrcode.vue/skills/qrcode-vue/SKILL.md`.
+- [Live demo](https://qr-vue.tie.pub): interactive playground for all props
+
+## Source
+
+- [src/index.ts](https://github.com/scopewu/qrcode.vue/blob/main/src/index.ts): the whole library — components, props, exported types (`Level`, `RenderAs`, `GradientType`, `ImageSettings`)
+- [npm package](https://www.npmjs.com/package/qrcode.vue)
+- [Repository](https://github.com/scopewu/qrcode.vue)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qrcode.vue",
-  "version": "3.9.1",
+  "version": "3.11.0",
   "description": "A Vue.js component to generate QRCode. Both support Vue 2 and Vue 3",
   "type": "module",
   "main": "./dist/qrcode.vue.cjs.js",
@@ -18,8 +18,10 @@
     "./package": "./package.json"
   },
   "scripts": {
-    "dev": "rsbuild dev",
+    "dev": "node example/scripts/generate-i18n.js && rsbuild dev",
     "build": "rollup -c",
+    "build:example": "node example/scripts/generate-i18n.js && rsbuild build",
+    "generate:i18n": "node example/scripts/generate-i18n.js",
     "test": "rstest"
   },
   "repository": "https://github.com/scopewu/qrcode.vue.git",
@@ -34,9 +36,10 @@
   ],
   "files": [
     "/dist",
+    "/skills",
     "CHANGELOG.md",
-    "README-zh_cn.md",
-    "README.md"
+    "README.md",
+    "llms.txt"
   ],
   "author": "scope.wu <scope.wu@gmail.com>",
   "license": "MIT",
@@ -50,13 +53,13 @@
   "dependencies": {},
   "devDependencies": {
     "@rollup/plugin-terser": "^1.0.0",
-    "@rsbuild/core": "^2.0.5",
-    "@rstest/core": "^0.9.10",
-    "@vue/test-utils": "^2.4.10",
-    "happy-dom": "^20.9.0",
-    "rollup": "^4.60.3",
+    "@rsbuild/core": "^2.2.1",
+    "@rstest/core": "^0.11.10",
+    "@vue/test-utils": "^2.5.0",
+    "happy-dom": "^20.11.12",
+    "rollup": "^4.63.1",
     "rollup-plugin-typescript2": "^0.37.0",
     "typescript": "^5.9.3",
-    "vue": "^3.5.34"
+    "vue": "^3.5.42"
   }
 }

package/skills/qrcode-vue/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: qrcode-vue
+description: Generate QR codes in Vue 3 apps with the qrcode.vue component library. Use this skill whenever the user wants to render, style, or download a QR code in Vue — including QR with a logo/image, gradient or rounded modules, SVG vs canvas output, SSR/Nuxt usage, or TypeScript typing — even if they don't name the library explicitly.
+---
+
+# qrcode.vue
+
+A Vue.js component to generate QR codes. Version 3.x targets **Vue 3 only** (Vue 2 apps must use qrcode.vue 1.x). Peer dependency: `vue@^3.0.0`. No other runtime dependencies.
+
+## Install
+
+```bash
+npm install --save qrcode.vue   # or: yarn add qrcode.vue
+```
+
+## Exports
+
+```ts
+import QrcodeVue, { QrcodeCanvas, QrcodeSvg } from 'qrcode.vue'
+import type { Level, RenderAs, GradientType, ImageSettings } from 'qrcode.vue'
+```
+
+- `QrcodeVue` (default) — switches between canvas and SVG via the `render-as` prop.
+- `QrcodeCanvas` / `QrcodeSvg` (named) — single-renderer components. Prefer these when the renderer is fixed.
+
+CommonJS / CDN note: exports are named since 3.5 — use `require('qrcode.vue').default` or `QrcodeVue.default` when loading the UMD bundle.
+
+## Props
+
+All three components share these props (`render-as` exists only on `QrcodeVue`):
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `value` | `string` | `''` | **Required.** QR content. |
+| `size` | `number` | `100` | Element size in px. |
+| `render-as` | `'canvas' \| 'svg'` | `'canvas'` | `QrcodeVue` only. Use `'svg'` for SSR. |
+| `level` | `'L' \| 'M' \| 'Q' \| 'H'` | `'L'` | Error correction. Use `'H'` when embedding a logo. |
+| `background` | `string` | `'#fff'` | Background color. |
+| `foreground` | `string` | `'#000'` | Module color (ignored when `gradient` is on). |
+| `margin` | `number` | `0` | Quiet-zone width in modules, `>= 0`. |
+| `radius` | `number` | `0` | Module corner radius, `0`–`0.5`. `0.5` = circular modules. Inner corners between adjacent modules stay sharp. |
+| `gradient` | `boolean` | `false` | Enable gradient fill. |
+| `gradient-type` | `'linear' \| 'radial'` | `'linear'` | Gradient direction type. |
+| `gradient-start-color` | `string` | `'#000'` | Gradient start. |
+| `gradient-end-color` | `string` | `'#fff'` | Gradient end. |
+| `image-settings` | `ImageSettings` | `{}` | Embedded logo, see below. |
+| `id` | `string` | `undefined` | ID base for internal SVG defs. Pass `useId()` (Vue 3.5+) for SSR hydration safety. |
+
+```ts
+type ImageSettings = {
+  src: string                                          // image URL
+  x?: number; y?: number                               // offset; centered when omitted
+  height?: number; width?: number                      // default: 10% of `size`
+  excavate?: boolean                                   // clear modules behind the image
+  borderRadius?: number
+  crossOrigin?: 'anonymous' | 'use-credentials' | ''   // required to export canvas with a cross-origin logo
+}
+```
+
+## Template ref methods
+
+Expose `toDataURL` and `download` on all components (`QrcodeVue` forwards to the active renderer):
+
+```html
+<script setup>
+import { ref } from 'vue'
+import { QrcodeCanvas } from 'qrcode.vue'
+
+const qrRef = ref()
+const save = () => qrRef.value?.download('qrcode.png')
+</script>
+
+<template>
+  <qrcode-canvas ref="qrRef" value="https://example.com" />
+  <button @click="save">Download</button>
+</template>
+```
+
+- Canvas: `toDataURL(type?, quality?)`, `download(filename?)` → PNG.
+- SVG: `toDataURL()`, `download(filename?)` → SVG.
+
+## Recipes
+
+QR with a centered logo — always raise `level` so the code stays scannable:
+
+```html
+<qrcode-svg
+  value="https://example.com"
+  :size="300"
+  level="H"
+  :image-settings="{ src: logoUrl, width: 60, height: 60, excavate: true, borderRadius: 8 }"
+/>
+```
+
+Gradient + rounded modules:
+
+```html
+<qrcode-vue
+  value="https://example.com"
+  render-as="svg"
+  gradient
+  gradient-type="radial"
+  gradient-start-color="#000000"
+  gradient-end-color="#38bdf8"
+  :radius="0.35"
+/>
+```
+
+SSR / Nuxt — render as SVG and pass a stable `id`:
+
+```html
+<script setup>
+import { useId } from 'vue'
+import { QrcodeSvg } from 'qrcode.vue'
+const uid = useId() // Vue 3.5+; on older versions pass any unique string
+</script>
+
+<template>
+  <qrcode-svg value="https://example.com" :id="uid" />
+</template>
+```
+
+## Pitfalls
+
+- **Vue 2**: do not use 3.x — install `qrcode.vue@1.x`.
+- **Tainted canvas**: with a cross-origin logo, set `imageSettings.crossOrigin: 'anonymous'` and ensure the image server sends `Access-Control-Allow-Origin`, or `toDataURL`/`download` throws `SecurityError`.
+- **SSR hydration**: without an explicit `id`, internal SVG IDs come from a module-level counter and can mismatch between server and client. Always pass `useId()` under SSR.
+- **Scannability**: keep contrast high between `foreground`/`gradient` and `background`; a logo covering too much area breaks scanning even at level `H`.
+- **Multiple instances with gradients**: `id` keeps each SVG's `<defs>` unique; collisions cause one QR's gradient to leak into another.