# 二维码

- 页面: https://jiguang132.com/zh/resources/ant-design/docs/qr-code
- 资源: Ant Design (https://jiguang132.com/zh/resources/ant-design.md)
- 全部指南: https://jiguang132.com/zh/resources/ant-design/docs.md

能够将文本转换生成二维码的组件，支持自定义配色和 Logo 配置。


## 何时使用 {#when-to-use}

当需要将文本转换成为二维码时使用。

## 代码演示 {#examples}


- 基本使用 · `base`
- 带 Icon 的例子 · `icon`
- 不同的状态 · `status`
- 自定义状态渲染器 · `customStatusRender`
- 自定义渲染类型 · `type`
- 自定义尺寸 · `customSize`
- 自定义颜色 · `customColor`
- 下载二维码 · `download`
- 纠错比例 · `errorlevel`
- 高级用法 · `Popover`
- 自定义语义结构的样式和类 · `style-class`

## API

通用属性参考：[通用属性](#jguang-common-props)

> 自 `antd@5.1.0` 版本开始提供该组件。

| 参数 | 说明 | 类型 | 默认值 | 版本 | [全局配置](/components/config-provider#component-config) |
| :-- | :-- | :-- | :-- | :-- | --- |
| value | 扫描后的文本 | `string \| string[]` | - | `string[]`: 5.28.0 | × |
| type | 渲染类型 | `canvas \| svg` | `canvas` | 5.6.0 | × |
| icon | 二维码中图片的地址（目前只支持图片地址） | string | - | - | × |
| size | 二维码大小 | number | 160 | - | × |
| iconSize | 二维码中图片的大小 | number \| { width: number; height: number } | 40 | 5.19.0 | × |
| color | 二维码颜色 | string | `#000` | - | × |
| classNames | 用于自定义组件内部各语义化结构的 class，支持对象或函数 | Record<[SemanticDOM](#semantic-dom), string> \| (info: { props })=> Record<[SemanticDOM](#semantic-dom), string> | - | 6.0.0 | 6.0.0 |
| bgColor | 二维码背景颜色 | string | `transparent` | 5.5.0 | × |
| marginSize | 留白（安静区）大小（单位为模块数），`0` 表示无留白 | number | `0` | 6.2.0 | × |
| bordered | 是否有边框 | boolean | true | - | × |
| errorLevel | 二维码纠错等级 | `'L' \| 'M' \| 'Q' \| 'H'` | `M` | - | × |
| boostLevel | 如果启用，自动提升纠错等级，结果的纠错级别可能会高于指定的纠错级别 | `boolean` | true | 5.28.0 | × |
| status | 二维码状态 | `active \| expired \| loading \| scanned` | `active` | scanned: 5.13.0 | × |
| statusRender | 自定义状态渲染器 | (info: [StatusRenderInfo](/components/qr-code#statusrenderinfo)) => React.ReactNode | - | 5.20.0 | × |
| styles | 用于自定义组件内部各语义化结构的行内 style，支持对象或函数 | Record<[SemanticDOM](#semantic-dom), CSSProperties> \| (info: { props })=> Record<[SemanticDOM](#semantic-dom), CSSProperties> | - | 6.0.0 | 6.0.0 |

### StatusRenderInfo

```typescript
type StatusRenderInfo = {
  status: QRStatus;
  locale: Locale['QRCode'];
  onRefresh?: () => void;
};
```

## Semantic DOM

| 语义节点 | 原生说明 | 版本 |
| --- | --- | --- |
| `root` | 根元素，设置flex布局、内边距、背景色、边框、圆角和相对定位样式 | — |
| `cover` | 遮罩层元素，设置绝对定位、层级、背景色和加载状态覆盖样式 | — |

语义说明来源: `vendor/components/qr-code/demo/_semantic.tsx`

## 主题变量（Design Token）{#design-token}

类型、继承关系和原生令牌声明保持固定源码原文；默认值由原生主题计算，并可能受 ConfigProvider 覆盖。本表不伪造静态默认值。

原生 ComponentToken 未声明可直接提取的自有字段；共享令牌或继承关系以以下声明为准。

声明来源: `vendor/components/qr-code/style/index.ts`

```ts
import type { CSSObject } from '@ant-design/cssinjs';

import { unit } from '@ant-design/cssinjs';

import { FastColor } from '@ant-design/fast-color';

import { resetComponent } from '../../style';

import type { FullToken, GenerateStyle, GetDefaultToken } from '../../theme/internal';

import { genStyleHooks, mergeToken } from '../../theme/internal';

// biome-ignore lint/suspicious/noEmptyInterface: ComponentToken need to be empty by default
export interface ComponentToken {}

/**
 * @desc QRCode 组件的 Token
 * @descEN Token for QRCode component
 */
interface QRCodeToken extends FullToken<'QRCode'> {
  /**
   * @desc QRCode 文字颜色
   * @descEN Text color of QRCode
   */
  QRCodeTextColor: string;
  /**
   * @desc QRCode 遮罩背景颜色
   * @descEN Cover background color of QRCode
   */
  QRCodeCoverBackgroundColor: string;
}
```

## FAQ

### 关于二维码纠错等级 {#faq-error-correction-level}

纠错等级也叫纠错率，就是指二维码可以被遮挡后还能正常扫描，而这个能被遮挡的最大面积就是纠错率。

通常情况下二维码分为 4 个纠错级别：`L级` 可纠正约 `7%` 错误、`M级` 可纠正约 `15%` 错误、`Q级` 可纠正约 `25%` 错误、`H级` 可纠正约`30%` 错误。并不是所有位置都可以缺损，像最明显的三个角上的方框，直接影响初始定位。中间零散的部分是内容编码，可以容忍缺损。当二维码的内容编码携带信息比较少的时候，也就是链接比较短的时候，设置不同的纠错等级，生成的图片不会发生变化。

> 有关更多信息，可参阅相关资料：[https://www.qrcode.com/zh/about/error_correction](https://www.qrcode.com/zh/about/error_correction.html)

### ⚠️⚠️⚠️ 二维码无法扫描？ {#faq-cannot-scan}

若二维码无法扫码识别，可能是因为链接地址过长导致像素过于密集，可以通过 size 配置二维码更大，或者通过短链接服务等方式将链接变短。


## 原生通用属性 {#jguang-common-props}


> Tips: 以下通用属性适用于 antd 大部分组件，不支持的组件会单独说明。

| 参数 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| style | 自定义样式 | CSSProperties | - |
| className | 自定义类名 | string | - |
| rootClassName | 添加在组件最外层的 className | string | - |
| autoFocus | 自动获取焦点，仅对表单类、链接、交互容器等可聚焦元素生效 | boolean | false |


## 安装并复现示例

```bash
npm install antd@6.6.5 @ant-design/icons@6.3.4 dayjs@1.11.23
```

使用 ConfigProvider 和原生 App，并单独配置 dayjs 语言。每个示例在查看代码中列出完整源码文件和额外固定依赖。示例名称用于选择演示，不是组件通用属性。主题、语言与 SSR 初始化见资源安装指南。

## 原生类型参考

源码查看器包含未修改的原生实现和以下声明文件，继承类型仍位于原生包中。代码中的英文注释保留为源码参考。

- `vendor/components/qr-code/QrcodeStatus.tsx`
- `vendor/components/qr-code/index.tsx`
- `vendor/components/qr-code/interface.ts`
- `vendor/components/qr-code/style/index.ts`

## 来源与许可

https://github.com/ant-design/ant-design/tree/4a39f54842eade4e565ab336ef6097cd7e723cdd

保留原生中英文正文与可执行示例；官网专用的嵌入章节和令牌表格在本地展开。Ant Design 使用 MIT 许可，另列依赖的许可证也需保留。上传预览禁止向外发起请求，不提供后端服务。

---

JGuang 全部资源索引: https://jiguang132.com/llms.txt