# @castlenine/svelte-qrcode 中文文档

规范地址：https://npmcn.com/package/%40castlenine/svelte-qrcode/

版本：2\.3\.0
npm 元数据更新时间：2024-10-03T12:02:09.317Z
中文译文更新时间：2026-11-09T04:21:20.568Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40castlenine/svelte-qrcode
原文对照：https://npmcn.com/package/%40castlenine/svelte-qrcode/?lang=original
项目主页：https://github.com/castlenine/svelte-qrcode#readme
源码仓库：https://github.com/castlenine/svelte-qrcode

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：89.8 kB，12 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：svelte \>=3\.54\.0
- 首次发布：2023-09-05T08:58:58.340Z
- 最新版本发布：2024-10-03T12:02:09.158Z
- 近 30 天下载量：29219（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：10（近 12 个月 0 个）

## 中文简介

Svelte & SvelteKit 的 QR 代码生成器组件, 没有依赖性

## 安装

```sh
npm install @castlenine/svelte-qrcode
```

也可以使用：`pnpm add @castlenine/svelte-qrcode`、`yarn add @castlenine/svelte-qrcode`、`bun add @castlenine/svelte-qrcode`

## README

# `@castlenine/svelte-qrcode`

[![npm.badge](https://img.shields.io/npm/v/@castlenine/svelte-qrcode)](https://www.npmjs.com/package/@castlenine/svelte-qrcode) [![download.badge](https://img.shields.io/npm/d18m/@castlenine/svelte-qrcode)](https://www.npmjs.com/package/@castlenine/svelte-qrcode) [![repl.badge](https://img.shields.io/static/v1?label=&message=Svelte+REPL&logo=svelte&logoColor=fff&color=ff3e00)](https://svelte.dev/repl/3e0c8ebeb0c74d7098a1e939800456c2?version=4.2.15) [![contribution.badge](https://img.shields.io/badge/contributions-welcome-green)](https://github.com/Castlenine/svelte-qrcode)

Svelte & SvelteKit 的 QR 代码生成器, 没有依赖性

## 安装

使用您的软件包管理器安装 :

```bash
npm install --save-dev @castlenine/svelte-qrcode
```

## 快速启动

```svelte
<script>
  import QRCode from '@castlenine/svelte-qrcode';
</script>

<QRCode data="Hello world!" />
```

![Alt text](https://github.com/Castlenine/svelte-qrcode/blob/master/readme/sample-hello-world.svg?sanitize=true)

## 从v1到v2的迁移

许多新功能被添加到2.0版本中,一些属性被重新命名.

以下是更改列表:

| 旧财产名称 | 新属性名称 | 说明 |
| --- | --- | --- |
| `content` | `data` |  |
| `errorCorrection` | `errorCorrectionLevel` |  |
| `base64Image` | `logoInBase64` |  |
| `logoWidth` | `logoSize` | `logoSize` 适用于 `logoWidth` 财务报告和审定财务报表 `logoHeight` (新财产) |
| `dispatchDownloadLink` | `dispatchDownloadUrl` |  |

| 旧事件名称 | 新事件名称 |
| --- | --- |
| `downloadLinkGenerated` | `downloadUrlGenerated` |

## 属性

### 数据

QR代码所编码的数据一般由网站的URL或应用程序使用的代码组成,例如处理基于时间的一次性密码(TOTP)应用程序中的秘密.

这是生成QR代码所需的唯一属性.

| 属性名称 | 类型 | 需求 |
| --- | --- | --- |
| `data` | `string` | **对** |

```svelte
<QRCode data="https://duxreserve.com" />
```

### QR 代码类型编号

QR代码型号,从1到40的整数,决定了QR代码的数据容量. 默认值为 `0`,允许自动检测.

[更多细节](https://github.com/Castlenine/svelte-qrcode/blob/master/readme/qr-code-type-number.png)

| 属性名称 | 类型 | 默认值 |
| --- | --- | --- |
| `typeNumber` | 整数 `number` 0至40岁 | `0` |

**说明:** 在大多数情况下,设定这种财产是不必要的。 但是,如果需要生成一个有特定类型编号的QR代码,可以设置如下:

```svelte
<QRCode data="https://duxreserve.com" typeNumber={4} />
```

### 错误更正级别

QR码具有错误校正能力,在代码被弄脏或损坏时可以恢复数据. 根据操作环境可以选择四个错误校正级别. 提高这一级别提高了错误校正能力,但也增加了数据QR代码的大小并降低了QR代码的数据容量.

要选择错误校正级别,需要考虑操作环境和QR代码大小等各种因素. 职等 `Q` 或者说 `H` 可选择用于QR码被弄脏的工厂环境,而级别 `L` 可选取具有大量数据的清洁环境。 通常,级别 `M` 最常被选中的是15%.

-   职等 `L` 约7%
-   职等 `M` 大约 15% (默认值)
-   职等 `Q` 约25%
-   职等 `H` 约30%

| 属性名称 | 类型 | 默认值 |
| --- | --- | --- |
| `errorCorrectionLevel` | `'L'`, (中文(简体) ), `'M'`, (中文(简体) ), `'Q'`, (中文(简体) ), `'H'` | `'M'` |

```svelte
<QRCode data="https://duxreserve.com" errorCorrectionLevel="L" />

<QRCode data="https://duxreserve.com" errorCorrectionLevel="M" />

<QRCode data="https://duxreserve.com" errorCorrectionLevel="Q" />

<QRCode data="https://duxreserve.com" errorCorrectionLevel="H" />
```

### 颜色

您可以使用十六进制颜色代码自定义 QR 代码的颜色或 [CSS 颜色关键词](https://www.w3.org/wiki/CSS/Properties/color/keywords) 例如 `'transparent'` 财务报告和审定财务报表 `'red'`。 。 。 .

| 属性名称 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `backgroundColor` | `string` | `'#ffffff'` |  |
| `color` | `string` | `'#000000'` | 将适用于 `modulesColor`, (中文(简体) ),`anchorsOuterColor` 财务报告和审定财务报表 `anchorsInnerColor` 如果没有定义 |
| `modulesColor` | `string` | 与 `color` 属性 |  |
| `anchorsOuterColor` | `string` | 与 `modulesColor` 属性 |  |
| `anchorsInnerColor` | `string` | 与 `anchorsOuterColor` 属性 |  |

```svelte
<QRCode data="https://duxreserve.com" backgroundColor="#009900" color="#ffffff" />

<QRCode data="https://duxreserve.com" backgroundColor="black" modulesColor="#ffffff" anchorsOuterColor="red" anchorsInnerColor="#00ff00" />
```

![Alt text](https://github.com/Castlenine/svelte-qrcode/blob/master/readme/sample-colors-1.svg?sanitize=true)

![Alt text](https://github.com/Castlenine/svelte-qrcode/blob/master/readme/sample-colors-2.svg?sanitize=true)

### 形状

您有两个选项可以自定义 QR 代码形状 : `'square'` 财务报告和审定财务报表 `'circle'`。 。 。 .

设定 `haveBackgroundRoundedEdges` 属性改为 `true` 以圆绕 QR 代码背景的边缘.

设定 `haveGappedModules` 属性改为 `true` 在模块之间产生空白.

| 属性名称 | 类型 | 默认值 |
| --- | --- | --- |
| `shape` | `'square'`, (中文(简体) ), `'circle'` | `'square'` |
| `haveBackgroundRoundedEdges` | `boolean` | `false` |
| `haveGappedModules` | `boolean` | `false` |

```svelte
<!-- No need to set the shape for `square` (default value) -->
<QRCode data="https://duxreserve.com" />

<QRCode data="https://duxreserve.com" shape="circle" />

<QRCode data="https://duxreserve.com" haveBackgroundRoundedEdges />

<QRCode data="https://duxreserve.com" haveGappedModules />
```

![Alt text](https://github.com/Castlenine/svelte-qrcode/blob/master/readme/sample-square.svg?sanitize=true)

![Alt text](https://github.com/Castlenine/svelte-qrcode/blob/master/readme/sample-circle.svg?sanitize=true)

![Alt text](https://github.com/Castlenine/svelte-qrcode/blob/master/readme/sample-rounded-edge.svg?sanitize=true)

![Alt text](https://github.com/Castlenine/svelte-qrcode/blob/master/readme/sample-gapped-modules.svg?sanitize=true)

### 加入唯一的 SVG 元素

若为 `isJoin` 设置为 `true`,则QR代码将作为单一SVG元素生成. 如果设置为 `false`,每个平方将是一个单独的 SVG 元素.

这个 `isJoin` 属性对性能优化有用,特别是在生成大量QR代码时。 但是,锚和模块的颜色不会不同,形状只能是 `'square'` 何时 `isJoin` 设置为 `true`。 。 。 .

**说明:** 大部分案件,你不需要 设置这个财产到 `true`。 。 。 .

| 属性名称 | 类型 | 默认值 |
| --- | --- | --- |
| `isJoin` | `boolean` | `false` |

```svelte
<QRCode data="https://duxreserve.com" isJoin />
```

### 响应

若为 `isResponsive` 设置为 `true`,QR代码将响应并适应其母元素中可用的空间.

| 属性名称 | 类型 | 默认值 |
| --- | --- | --- |
| `isResponsive` | `boolean` | `false` |

```svelte
<div style="width: 30%; height: 30%;">
  <QRCode data="https://duxreserve.com" isResponsive />
</div>
```

### QR 代码大小

您可以调整 QR 代码的编码和大小 。 增加体积能增强扫描的便捷性.

这个 `padding` 以“模块单位”计量,而 `size`, (中文(简体) ), `width` 财务报告和审定财务报表 `height` 处于像素中.

**说明:** 建议使用平方形的 QR 代码,如果你喜欢不同的 `width` 财务报告和审定财务报表 `height` 数值。 测试大小不同的QR代码,以确保其可扫描.

| 属性名称 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `padding` | `number` (单元单位) | `1` "单元单位" | 1个平板=1个模块单元 |
| `size` | `number` (像素) (中文(简体) ) | `256` 像素 | 将适用于 `width` 财务报告和审定财务报表 `height` 如果没有定义 |
| `width` | `number` (像素) (中文(简体) ) | 与 `size` 属性 |  |
| `height` | `number` (像素) (中文(简体) ) | 与 `size` 属性 |  |

```svelte
<QRCode data="https://duxreserve.com" padding={5} size={1000} />

<QRCode data="https://duxreserve.com" padding={5} width={1000} height={800} />
```

### 居中标志

您可以在 QR 代码的中心添加一个标志; 它会被自动缩放以适应并插入生成的 SVG.

如果你没准备好 `logoInBase64` 或者说 `logoPath`,该标志将不会显示。 你也可以用这个 `logoPath` 或者说 `logoInBase64` 要指定标志图像。 使用 `logoInBase64` 改为 `logoPath` 用于更快的标识加载时间。 如果您使用 `logoInBase64`,则 `logoPath` 财产将被忽略。 对基础64编码没有验证 `logoInBase64`; 确保它有效.

`logoPath` 可以是本地路径也可以是 URL。 通常情况下,标志文件位于静态文件夹. 如果路径不正确或未定义,则不会显示标志. 它使用获取API来加载图像;因此,如果URL是外部的,它必须是CORS启用的. 使用时加载图像可能稍有延迟 `logoPath`设置 `waitForLogo` 改为 `true` 以确保在提供 QR 代码前的标志加载.

如果你没准备好 `logoBackgroundColor`,该标志将具有与QR代码相同的背景颜色.

**说明:** 对基础64编码没有验证 `logoInBase64`; 确保它有效.

| 属性名称 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `logoInBase64` | base64(图像) `string` | `''` (没有标志) |  |
| `logoPath` | `string` | `''` (没有标志) |  |
| `logoBackgroundColor` | `string` | `''` (与QR码相同) `backgroundColor` (财产) |  |
| `logoPadding` | `number` (单元单位) | `1` "单元单位" | 1个标识板=1个模块单元 |
| `logoSize` | `number` (像素) (中文(简体) ) | `15`QR 代码% `size` 属性 | 将适用于 `logoWidth` 财务报告和审定财务报表 `logoHeight` 如果没有定义 |
| `logoWidth` | `number` (像素) (中文(简体) ) | 与 `logoSize` 属性 |  |
| `logoHeight` | `number` (像素) (中文(简体) ) | 与 `logoSize` 属性 |  |
| `waitForLogo` | `boolean` | `false` |  |

```svelte
<QRCode data="https://duxreserve.com" logoPath="/logo/lightning.svg" />

<!-- External URL -->
<QRCode data="https://duxreserve.com" logoPath="https://upload.wikimedia.org/wikipedia/commons/a/a8/Lightning_bolt_simple.png" />

<!-- WaitForLogo -->
<QRCode data="https://duxreserve.com" logoPath="https://upload.wikimedia.org/wikipedia/commons/a/a8/Lightning_bolt_simple.png" waitForLogo />

<!-- logoInBase64 -->
<QRCode data="https://duxreserve.com" logoInBase64="data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIzMiIgaGVpZ2h0PSIzMiIgdmlld0JveD0iMCAwIDI0IDI0Ij48cGF0aCBmaWxsPSJjdXJyZW50Q29sb3IiIGQ9Im0xOC40OTYgMTAuNzA5bC04LjYzNiA4Ljg4Yy0uMjQuMjQ2LS42MzgtLjAzOS0uNDgyLS4zNDVsMy4wNzQtNi4wNjZhLjMuMyAwIDAgMC0uMjY4LS40MzZINS43MThhLjMuMyAwIDAgMS0uMjE0LS41MWw4LjAxLTguMTE1Yy4yMzItLjIzNS42MTguMDIzLjQ4OS4zMjhMMTEuNzA2IDkuODZhLjMuMyAwIDAgMCAuMjguNDE3bDYuMjkxLS4wNzhhLjMuMyAwIDAgMSAuMjIuNTA5Ii8+PC9zdmc+" />

<!-- logo background color -->
<QRCode data="https://duxreserve.com" logoPath="/logo/lightning.svg" logoBackgroundColor="#ff0000" />

<!-- logo padding -->
<QRCode data="https://duxreserve.com" logoPath="/logo/lightning.svg" logoPadding={2} />

<!-- logo size -->
<QRCode data="https://duxreserve.com" logoPath="/logo/lightning.svg" logoSize={20} />

<QRCode data="https://duxreserve.com" logoPath="/logo/lightning.svg" logoWidth={20} logoHeigh={15} />
```

![Alt text](https://github.com/Castlenine/svelte-qrcode/blob/master/readme/sample-logo.svg?sanitize=true)

### 下载 QR 代码

您可以将 QR 代码作为文件下载( N)`'svg'` | `'png'` | `'jpg'` | `'jpeg'` | `'webp'`),使用启动下载的锚标记. 要启用此功能, 请设置 `dispatchDownloadUrl` 属性改为 `true` 并倾听 `downloadUrlGenerated` 获取下载 URL 的事件。 您可以通过设置文件格式 `downloadUrlFileFormat` 属性改为 `'svg'` (违约), `'png'`, (中文(简体) ), `'jpg'`, (中文(简体) ), `'jpeg'`,或 `'webp'`。 。 。 .

添加数据 `download` 属性到锁定标记以指定已下载文件的文件名。 文件名中的扩展名是可选的;文件格式将由 `downloadUrlFileFormat` 属性.

此外,列入 `target="_blank"` 属性在锁定标签中打开新标签中的下载.

**说明:** 你无法使用 `downloadUrlFileFormat` 其他 `'svg'` 在非浏览器环境中.

| 属性名称 | 类型 | 默认值 |
| --- | --- | --- |
| `dispatchDownloadUrl` | `boolean` | `false` |
| `downloadUrlFileFormat` | `'svg'`, (中文(简体) ), `'png'`, (中文(简体) ), `'jpg'`, (中文(简体) ), `'jpeg'`, (中文(简体) ), `'webp'` | `'svg'` |

```svelte
<script>
  import QRCode from '@castlenine/svelte-qrcode';

  let downloadUrl = '';

  const handleDownloadUrlGenerated = (url = '') => {
    downloadUrl = url;
  };
</script>

<div>
  <QRCode
    data="https://duxreserve.com"
    logoPath="/logo/lightning.svg"
    downloadUrlFileFormat="png"
    dispatchDownloadUrl
    on:downloadUrlGenerated={(event) => handleDownloadUrlGenerated(event.detail.url)}
  />
</div>


{#if downloadUrl}
  <a href={downloadUrl} download="QR-code-filename.png" target="_blank">Download QR Code</a>
{/if}
```

### 其他活动

您可以聆听以下事件 :

-   `qrCodeGenerated`: QR 代码已成功生成
-   `qrCodeRegeneratedWithLogo`: QR 代码已成功重新生成并带有标志
-   `qrCodeGenerationFailed`: QR 代码生成失败. 错误消息可通过 `event.detail`。检查控制台了解更多信息

```svelte
<QRCode
  data="https://duxreserve.com"
  on:qrCodeGenerated={handleQrCodeGenerated}
  on:qrCodeRegeneratedWithLogo={handleQrCodeRegeneratedWithLogo}
  on:qrCodeGenerationFailed={handleQrCodeGenerationFailed}
/>
```

### 基于时间的一次性密码( TOTP)

Acme 应用程序上的 John Doe 用户的 URL 样本 :

```svelte
<QRCode data="otpauth://totp/ACME%20Co:john.doe@email.com?secret=HXDMVJECJJWSRB3HWIZR4IFUGFTMXBOZ&issuer=ACME%20Co&algorithm=SHA1&digits=6&period=30" />
```

![Alt text](https://github.com/Castlenine/svelte-qrcode/blob/master/readme/sample-totp.svg?sanitize=true)

## 常见问题

### @castlenine/svelte-qrcode 是什么？

Svelte & SvelteKit 的 QR 代码生成器组件, 没有依赖性

### 如何安装 @castlenine/svelte-qrcode？

在项目目录运行 npm install @castlenine/svelte-qrcode，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：svelte（\>=3\.54\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @castlenine/svelte-qrcode 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @castlenine/svelte-qrcode 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @castlenine/svelte-qrcode 可以商用吗？

@castlenine/svelte-qrcode 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @castlenine/svelte-qrcode 的下载量有多少？

根据 npm 官方下载统计，@castlenine/svelte-qrcode 在 2026/10/09 – 2026/11/07 这 30 天内被下载 29,219 次，日均约 974 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @castlenine/svelte-qrcode 还在维护吗？

最新版本 2\.3\.0 发布于 2024/10/03（2 年前）；至今共发布 10 个版本，其中过去 12 个月发布了 0 个；首次发布于 2023/09/05。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。