{"_id":"vue3-next-qrcode","_rev":"30-a8eb52d7ad1f8925123a489a09e499f8","name":"vue3-next-qrcode","dist-tags":{"beta":"4.1.0-beta.1","latest":"4.1.1"},"versions":{"2.0.0":{"name":"vue3-next-qrcode","version":"2.0.0","author":{"name":"Ray"},"license":"MIT","_id":"vue3-next-qrcode@2.0.0","maintainers":[{"name":"account_name_ray","email":"443547225@qq.com"}],"dist":{"shasum":"571eee248fa54f22f7eab3bfd83c6aa9039b7216","tarball":"https://registry.npmjs.org/vue3-next-qrcode/-/vue3-next-qrcode-2.0.0.tgz","fileCount":29,"integrity":"sha512-8XPjm3U+IY4HQcYzCIVKV70/Ex2bhWpHffbpdMan0iaznMGuSj7ryx3CgPbWTgJ6RawAP3eeoUm6yUfFx+tCjQ==","signatures":[{"sig":"MEQCIFYzafP8NPOl3iuKDeGRvUVvj1cWZZQ4yw0ZiR7MNAs6AiAVgtFAU3GzXDDRtUJmUTTRkJwNeEBrKXYQSVkO9Ji3Dw==","keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA"}],"unpackedSize":56609},"main":"lib/index.js","type":"module","types":"lib/index.d.ts","module":"es/index.js","private":false,"scripts":{"dev":"vite --config vite.build.config.ts","preview":"vite preview","build:lib":"vite build --config vite.build.config.ts","build:umd":"vite build --config vite.bundle.config.ts"},"_npmUser":{"name":"account_name_ray","email":"443547225@qq.com"},"_npmVersion":"8.19.4","description":"A QR code component about vue3","directories":{},"_nodeVersion":"16.20.1","dependencies":{"vue":"^3.3.4"},"_hasShrinkwrap":false,"devDependencies":{"add":"^2.0.6","sass":"^1.66.1","vite":"^4.4.5","vue-tsc":"^1.8.5","naive-ui":"^2.34.4","awesome-qr":"2.1.5-rc.0","typescript":"^5.0.2","@types/node":"^20.5.9","vite-plugin-dts":"^2.3.0","@vitejs/plugin-vue":"^4.2.3","@vitejs/plugin-vue-jsx":"^3.0.2"},"_npmOperationalInternal":{"tmp":"tmp/vue3-next-qrcode_2.0.0_1693884726337_0.42645803836788354","host":"s3://npm-registry-packages"}},"2.0.1":{"name":"vue3-next-qrcode","version":"2.0.1","keywords":["vue3","qrcode"],"author":{"name":"Ray"},"license":"MIT","_id":"vue3-next-qrcode@2.0.1","maintainers":[{"name":"account_name_ray","email":"443547225@qq.com"}],"homepage":"https://github.com/XiaoDaiGua-Ray/vue3-next-qrcode#readme","bugs":{"url":"https://github.com/XiaoDaiGua-Ray/vue3-next-qrcode/issues"},"dist":{"shasum":"c75399bcdebeee04804b96228702738848dfab77","tarball":"https://registry.npmjs.org/vue3-next-qrcode/-/vue3-next-qrcode-2.0.1.tgz","fileCount":77,"integrity":"sha512-SxQcJgGQDXoEZWI8xfNfxU+Gkb2uTqm19gAnw4VjFCH/VjkcfpwQz2ZJGLXQ0XczLplKrbTFsirqSgkOsX4IZQ==","signatures":[{"sig":"MEQCIBDARXrESEJ3AmB1JTsiv1FnOo9v6aZ3c/0izDhhYe3KAiATLqTYM0IQ8X31hGWMuelWJOO2Z1EdRDlrGuI/HceYXg==","keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA"}],"unpackedSize":292456},"main":"lib/index.js","type":"module","types":"lib/index.d.ts","module":"es/index.js","gitHead":"ca5d9cb6d7c88e21ea4ddcc158770a368f31d31a","private":false,"scripts":{"dev":"vite --config vite.build.config.ts","preview":"vite preview","build:lib":"vite build --config vite.build.config.ts","build:umd":"vite build --config vite.bundle.config.ts"},"_npmUser":{"name":"account_name_ray","email":"443547225@qq.com"},"repository":{"url":"git+https://github.com/XiaoDaiGua-Ray/vue3-next-qrcode.git","type":"git"},"_npmVersion":"8.19.4","description":"

\n \n \"vue3-next-qrcode\"\n \n

\n\n

\n \"npm\n \"license\"\n

\n\n
\n\n# vue3-next-qrcode\n\n[English](https://github.com/XiaoDaiGua-Ray/vue3-next-qrcode/blob/main/README.md) | 简体中文\n\n面向 Vue 3 的二维码组件，支持 Logo、图片/GIF 背景、状态 UI、`useQRCode`，并且包入口可在 SSR 中安全导入。\n\n
\n\n## 效果预览\n\n

\n \"带\n \"自定义样式二维码\"\n

\n\n## 为什么用它\n\n- 既可以作为 Vue 组件使用，也可以用 `useQRCode` 编程式生成二维码。\n- 支持 Logo、图片背景、GIF 背景、自定义点样式、加载/错误状态和下载。\n- 根入口在 Nuxt 等 SSR 框架中可以安全导入。\n- 渲染核心按需懒加载，GIF parser/encoder 只在使用 GIF 背景时加载。\n- GIF 渲染带资源保护并按需加载；当前包构建使用已验证的主线程渲染路径。\n- 使用 TypeScript 编写，提供组件、composable 和实例类型。\n\n## 安装\n\n```bash\npnpm add vue3-next-qrcode\n```\n\n```bash\nnpm install vue3-next-qrcode\n```\n\n支持 Vue `3.0.1` 及以上版本，peer 范围继续保持 `^3.0.1`。\n\n## 快速开始\n\n```vue\n\n\n\n```\n\n如果你更喜欢全局注册：\n\n```ts\nimport { createApp } from 'vue'\nimport Vue3NextQrcode from 'vue3-next-qrcode'\nimport 'vue3-next-qrcode/style.css'\nimport App from './App.vue'\n\ncreateApp(App).use(Vue3NextQrcode).mount('#app')\n```\n\n## 常见用法\n\n### 自定义大小和颜色\n\n```vue\n\n\n\n```\n\n### 中间添加 Logo\n\n```vue\n\n```\n\n### GIF 背景\n\n```vue\n\n\n\n```\n\n普通二维码不会加载 GIF parser 和 encoder 代码。只有使用 `gifBackgroundURL` 或 `gifBackground` 时才会按需加载。\n\n### 加载和错误状态\n\n```vue\n\n```\n\n默认 UI 不够时可以使用插槽：\n\n```vue\n\n \n\n```\n\n### 下载二维码\n\n```vue\n\n\n\n```\n\n## Nuxt 4 和 SSR\n\n包入口可以在 SSR 阶段安全导入。二维码图片生成仍然依赖浏览器 Canvas，因此组件渲染请放到 `` 或等价的客户端边界中。\n\n```vue\n\n\n\n```\n\n也可以对特定路由关闭 SSR：\n\n```ts\nexport default defineNuxtConfig({\n routeRules: {\n '/qrcode': { ssr: false },\n },\n})\n```\n\nNuxt 4 项目应把页面或组件放在 `app/pages/` 或 `app/components/` 下，并显式导入\n`vue3-next-qrcode/style.css`。Nuxt 会从服务端构建中 tree-shake 掉 ``\n默认插槽，因此只由内部组件引入的 CSS 不一定出现在首屏 HTML 中；建议同时提供\n`#fallback`，保证 SSR 占位稳定并减少布局抖动。多数项目不需要 `transpile`、alias\n或 `optimizeDeps` 配置。\n\n参考官方 [Nuxt `` 文档](https://nuxt.com/docs/4.x/api/components/client-only)\n和 [Nuxt 4 升级指南](https://nuxt.com/docs/4.x/getting-started/upgrade)。\n\n## 编程式生成\n\n当你只想拿到二维码图片，而不想使用组件内置 UI 时，可以使用 `useQRCode`。\n\n```vue\n\n\n\n```\n\n### `useQRCode` 返回值\n\n```ts\nfunction useQRCode(): {\n qrcodeURL: Ref\n isLoading: Ref\n status: Ref<'idle' | 'loading' | 'success' | 'error' | 'cancelled'>\n error: Ref\n generate: (\n options: UseQRCodeOptions,\n ) => Promise\n canDownload: ComputedRef\n download: (fileName?: string) => Promise\n cancel: () => void\n reset: () => void\n clear: () => void\n dispose: () => void\n}\n```\n\n`useQRCode({ defaultOptions, concurrency })` 支持兼容默认值 `reject` 和\n`latest`。当 `defaultOptions.text` 完整提供时，可以无参数调用 `generate()`。\n被替代、取消或 dispose 的调用会以 `QRCodeGenerationCancelledError` 拒绝。\n`cancel()` 保留上一次成功图片；`reset()` 清空结果；`clear()` 继续作为\n`reset()` 的兼容别名。Vue 作用域中的 Hook 会自动 dispose，也可以显式调用。\n\n如果只需要复用下载行为，也可以直接使用导出的 `useQRCodeDownload(sourceRef)`。需要清理共享 GIF URL 缓存时，调用 `clearQRCodeGIFCache()`。\n\n## 包导出\n\n```ts\nimport {\n Vue3NextQrcode,\n useQRCode,\n useQRCodeDownload,\n clearQRCodeGIFCache,\n} from 'vue3-next-qrcode'\nimport { QRCodeClient } from 'vue3-next-qrcode/client'\nimport 'vue3-next-qrcode/style.css'\n```\n\n旧样式路径仍然保留：\n\n```ts\nimport 'vue3-next-qrcode/es/style.css'\nimport 'vue3-next-qrcode/lib/style.css'\n```\n\n## Props\n\n| Prop | 类型 | 默认值 | 说明 |\n| ------------------------ | ----------------------------------- | ----------------------------- | --------------------------------------------------------------------------- |\n| `text` | `string` | 必填 | 编码到二维码里的文本。 |\n| `size` | `number` | `160` | 二维码尺寸，单位像素。 |\n| `margin` | `number` | `12` | 二维码主体周围的安静区边距。 |\n| `correctLevel` | `0 \\| 1 \\| 2 \\| 3` | `1` | 纠错级别映射：`L=1`、`M=0`、`Q=3`、`H=2`，推荐使用 `QRErrorCorrectLevel`。 |\n| `watchText` | `boolean` | `true` | `text` 变化时自动重新渲染。 |\n| `status` | `'loading' \\| 'error' \\| 'success'` | `undefined` | 展示加载或错误状态。 |\n| `colorDark` | `string` | `'#000000'` | 二维码模块颜色。 |\n| `colorLight` | `string` | `'#ffffff'` | 二维码背景颜色。 |\n| `autoColor` | `boolean` | `true` | 尽可能根据图片/GIF 背景推导二维码颜色。 |\n| `backgroundImage` | `string` | `undefined` | 静态背景图 URL 或 data URL。 |\n| `backgroundDimming` | `string` | `'rgba(0, 0, 0, 0)'` | 背景图上方的遮罩颜色。 |\n| `gifBackgroundURL` | `string` | `undefined` | GIF 背景 URL。 |\n| `gifBackground` | `ArrayBuffer` | `undefined` | GIF 背景二进制数据。 |\n| `logoImage` | `string` | `undefined` | 中间 Logo 图片 URL 或 data URL。 |\n| `logoScale` | `number` | `0.4` | Logo 相对二维码尺寸的比例。 |\n| `logoMargin` | `number` | `6` | Logo 边距，单位像素。 |\n| `logoCornerRadius` | `number` | `8` | Logo 圆角，单位像素。 |\n| `dotScale` | `number` | `undefined` | 可选全局点阵比例 `(0, 1]`；显式设置时覆盖 data/timing/alignment 比例。 |\n| `whiteMargin` | `boolean` | `true` | 使用白色安静区，而不是透明安静区。 |\n| `components` | `ComponentOptions` | 内置默认值 | 精细控制二维码局部样式。 |\n| `maskPattern` | `number` | `undefined` | 强制指定 `0` 到 `7` 的 QR mask pattern，一般无需设置。 |\n| `version` | `number` | `undefined` | 强制指定 QR version，范围 `1` 到 `40`，一般无需设置。 |\n| `defineProvider` | `Partial` | `undefined` | 当前组件的 CSS 变量覆盖。 |\n| `maskColor` | `string` | `'rgba(255, 255, 255, 0.96)'` | 加载/错误遮罩颜色。 |\n| `errorDescription` | `string \\| VNode` | `'二维码已过期'` | 错误状态描述。 |\n| `errorActionDescription` | `string` | `'重新加载'` | 错误操作文案。 |\n| `onSuccess` | `(result) => void` 或数组 | `null` | 生成成功后触发，结果为 `string \\| ArrayBuffer \\| Uint8Array \\| undefined`。 |\n| `onError` | `(error) => void` 或数组 | `null` | 生成失败后触发。 |\n| `onReload` | `() => void` 或数组 | `null` | 点击内置错误操作时触发。 |\n\n在 SFC 模板中，你可以按项目习惯使用 camelCase（`gifBackgroundURL`）或 kebab-case（`gif-background-url`）。\n\n## 插槽和实例方法\n\n| 插槽 | 说明 |\n| ------------- | -------------------- |\n| `loading` | 自定义加载状态。 |\n| `errorAction` | 自定义错误操作区域。 |\n\n```ts\ninterface QRCodeInst {\n downloadQRCode: (fileName?: string) => Promise\n}\n```\n\n## CSS 变量\n\n| 区域 | 变量 |\n| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| 尺寸 | `--r-qrcode-width`、`--r-qrcode-height` |\n| 容器 | `--r-qrcode-background-color`、`--r-qrcode-border-width`、`--r-qrcode-border-style`、`--r-qrcode-border-color`、`--r-qrcode-border-radius`、`--r-qrcode-overflow`、`--r-qrcode-font-family` |\n| 图片/遮罩 | `--r-qrcode-image-object-fit`、`--r-qrcode-mask-color` |\n| Loading | `--r-qrcode-loading-spinner-size`、`--r-qrcode-loading-spinner-border-width`、`--r-qrcode-loading-spinner-color`、`--r-qrcode-loading-animation-duration` |\n| Error | `--r-qrcode-error-z-index`、`--r-qrcode-error-gap`、`--r-qrcode-error-color`、`--r-qrcode-error-content-padding` |\n| Action | `--r-qrcode-action-color`、`--r-qrcode-action-hover-color`、`--r-qrcode-action-active-color`、`--r-qrcode-action-transition-duration` |\n\n旧变量 `--r-qrcode-primary-color`、`--r-qrcode-primary-color-2`、\n`--r-qrcode-spin-size` 继续作为兼容 fallback。\n\n使用 `defineProvider` 可以对单个组件覆盖：\n\n```vue\n\n```\n\n## TypeScript\n\n```ts\nimport type {\n QRCodeInst,\n QRCodeLevel,\n QRCodeStatus,\n QRCodeProps,\n QRCodeOptions,\n ComponentOptions,\n UseQRCodeOptions,\n UseQRCodeReturnType,\n QRCodeDownloadSource,\n UseQRCodeDownloadReturn,\n} from 'vue3-next-qrcode'\n```\n\n## 测试\n\n当前包同时覆盖单元测试和发布 smoke：\n\n- `vitest` + `happy-dom` 覆盖 prop 校验、GIF URL 缓存/请求去重、下载行为、渲染队列语义、`useQRCode`、`QRCode` 组件异步渲染，以及当前包构建的主线程渲染路径。\n- `scripts/smoke.mjs` 校验 ESM/CJS 根入口、client 子路径、样式导出、发布文件完整性、声明文件消费、私有路径残留、packaged worker 禁用引用，以及 emoji 二维码编码。\n\n执行完整验证：\n\n```bash\npnpm run test\n```\n\n## 迁移说明\n\n### v4.1.0\n\n- 推荐使用 `vue3-next-qrcode/style.css` 引入样式。\n- Nuxt 中推荐使用 `vue3-next-qrcode/client` 和 ``。\n- 根入口和 `useQRCode` 导入是 SSR-safe 的，但二维码图片生成仍在客户端。\n- 浏览器侧二进制结果使用 `Uint8Array`，不再暴露 Node `Buffer` 类型。\n- `downloadQRCode()` 返回 `Promise`。\n- 非法 `version`、`maskPattern`、`dotScale` 会直接校验失败。\n- 未列入 package `exports` 的内部深层导入不受支持。\n- Vue 最低版本仍是 `3.0.1`，不是破坏性升级。\n\n详见 [v4.1.0 迁移文档](./docs/releases/v4.1.0-migration.md)。\n\n### 从 v3 迁移\n\n- CSS 类名前缀从 `ray-qrcode` 改为 `r-qrcode`。\n- `img_tag` 改为 `data-component`。\n- GIF 和图片渲染逻辑现在会按需懒加载。\n\n## 常见问题\n\n### SSR 中能 import 吗？\n\n可以。根入口和 `useQRCode` 都可以在 SSR 阶段安全导入。二维码图片渲染仍需要放到客户端。\n\n### Nuxt SSR 时为什么看不到二维码？\n\n`QRCodeClient` 是客户端渲染组件。如果需要 SSR 占位内容，可以给 `` 添加 fallback。\n\n### GIF 渲染需要配置 Worker 吗？\n\n不需要。当前包构建使用已验证的主线程 GIF 渲染。Worker 渲染会等相对 worker URL 通过 ESM 和 CJS 包 smoke 后再恢复。\n\n### 可以在小程序里使用吗？\n\n不能直接使用。小程序使用平台特定 Canvas API，需要单独适配。\n\n## License\n\n[MIT](./LICENSE)\n","readmeFilename":"README.zh-CN.md"}