# 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` 呈现。