# QRCode 二维码
能够将文本转换生成二维码的组件,支持自定义配色和 Logo 配置。
## 何时使用
- 当需要将文本转换成为二维码时使用。
## 代码演示
[基本用法](./demo/basic.tsx)
- 最简单的用法。
[不同的状态](./demo/status.tsx)
- 可以通过 status 的值控制二维码的状态,提供了 active、expired、loading、scanned 四个值。
[自定义属性](./demo/custom.tsx)
- 可以通过一些自定义属性来自定义二维码展示方式。
[卡片和下载](./demo/download.tsx)
- 在卡片中展示, 和下载二维码。
[自定义状态](./demo/custom-status.tsx)
- 自定义状态展示。
[外观](./demo/appearance.tsx)
- `theme` 画在二维码外圈那一层表面上,矩阵里的墨点五档都不变;不写 `theme` 时是 `outline`。
## API
| 属性 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| value | 二维码解析的文本内容或跳转链接。 | `string` | 必填 |
| size | 二维码的正方形边长,单位 `px`。组件内部已做高清屏适配,大屏拉伸不模糊。 | `number` | `160` |
| colorDark | 前景色(二维码实点颜色)。支持十六进制、RGB 以及 CSS 变量,组件会自动监听根节点 `theme-mode` 属性进行动态重绘适配。 | `string` | `"var(--kui-color-reverse)"` |
| colorLight | 背景色。支持十六进制、RGB 以及 CSS 变量。暗黑模式下建议设置为深色系,切勿设为完全透明以免影响扫码识别率。 | `string` | `"var(--kui-color-bg)"` |
| bordered | 是否保留外边框和它托住的 12px 内边距。只想去掉表面(不留底色、边框透明)请写 `theme="plain"`,内边距会保留。 | `boolean` | `true` |
| status | 二维码的当前业务状态。可选值:
• `'active'`: 正常可扫描状态
• `'loading'`: 安全链路加载中状态
• `'expired'`: 长期未扫码已失效状态(展示刷新按钮)
• `'scanned'`: 已成功扫描状态(可配合插槽定制遮罩) | `"active" \| "loading" \| "expired" \| "scanned"` | `'active'` |
| logo | 二维码正中心的 Logo 图片地址(支持网络 URL 或 Base64)。 | `string` | - |
| logoSize | 正中心 Logo 的尺寸大小,单位 `px`。如果不传,组件内部会自动计算为整个二维码尺寸的 `22%`。 | `number` | - |
| logoRadius | 正中心 Logo 的圆角弧度,单位 `px`。 | `number` | `4` |
| logoBorder | Logo 是否开启白色隔离保护边框。开启后会在 Logo 外围自动绘制一圈背景色保护带,防止二维码矩阵格子死死贴住 Logo 导致视觉杂乱。 | `boolean` | `true` |
| margin | 二维码矩阵区域四周的空白边距(即白边格子的层数)。 | `number` | `0` |
| errorLevel | 二维码的容错率纠错级别。可选值:`'L'` (7%), `'M'` (15%), `'Q'` (25%), `'H'` (30%)。
_注:如果需要在正中心嵌入 Logo,建议维持在 'M' 或强行改为 'H',以确保中心被遮挡后依然能百分百被识别。_ | `"L" \| "M" \| "Q" \| "H"` | `'M'` |
| shape | 二维码形状 | `"round" \| "default" \| "square" \| "circle"` | `round` |
| theme | 外观主题 | `"dashed" \| "solid" \| "fill" \| "outline" \| "plain"` | outline |
| loadingContent | 自定义 `loading` 状态的遮罩内容。 | `ReactNode` | - |
| expiredContent | 自定义 `expired` 状态的遮罩内容。 | `ReactNode` | - |
| scannedContent | 自定义 `scanned` 状态的遮罩内容。 | `ReactNode` | - |
| onRefresh | 点击 `expired` 状态遮罩时触发。 | `(() => void)` | - |
### Ref
| 方法 | 说明 | 类型 |
| :------- | :------------------------------------- | :------------------------------------- |
| download | 等待二维码及 Logo 绘制完成后下载 PNG。 | `(fileName?: string) => Promise` |
## 主题
`theme` 支持 `fill`、`outline`、`plain`、`solid`、`dashed` 五种外观,不写 `theme` 时就是 `outline`:一圈库的边框色,外加它托住的 12px 内边距。`fill` 换成一层浅底,`dashed` 把边框换成虚线,`solid` 用主色铺满,并把“已过期”这类遮罩文字一起反白。`plain` 只去掉这层表面——不留底色、边框透明,12px 内边距仍然保留;要连边框和内边距一起去掉,请写 `bordered={false}`。`underlined` 是给可输入的控件用的,二维码会按 `outline` 呈现。