QRCode
将内容编码为二维码。中文惯用名：二维码。
稳定本期新增已接入
元信息
| 字段 | 值 |
|---|---|
| 规范 ID | component.qrcode |
| 名称 | QRCode |
| 二级分类 | 数据展示（data-display） |
| 用途 | 将内容编码为二维码 |
| 描述 | 中文惯用名：二维码。 |
预览
静态结构：QRCode 以 qrcode 包在 effect 中生成内联 SVG（toString(value, { type: "svg", margin: 0 })），自生成的可信 SVG 字符串经 dangerouslySetInnerHTML 注入容器，容器按 size（缺省 128px）定宽高；bordered 时外层加圆角边框与内边距。value 为空或生成失败时渲染同尺寸灰色占位块 + image 图标。color / bgColor 经 hex 校验（# 开头的 3 / 4 / 6 / 8 位，可带透明度位）后透传为码体 dark / light 色，非法值回退生成库内建黑 / 白默认。
DSL 结构
{
"type": "QRCode",
"props": {
"value": "https://pactor.example.com/invite/8f2k",
"size": 128,
"bordered": true
}
}何时用
何时使用
- 将短文本编码为可扫码图形：分享链接、下载地址、登录凭证、凭证编号。
- 移动端接力场景：桌面端展示二维码，手机扫码继续流程。
- 需要控制码体尺寸、配色与边框的嵌入式展示。
何时不用
- 承载长文或复杂结构化数据：二维码容量有限且不可读，长内容用链接承接。
- 需要用户直接阅读 / 复制内容：二维码不替代文本，应同时给出原文。
- 展示条形码等其他码制：QRCode 仅生成 QR 码。
变体
| 变体 | 视觉形态 | 适用场景 |
|---|---|---|
| 默认 | 128px 黑码白底内联 SVG | 常规分享 / 跳转编码 |
| bordered 带边框 | 圆角边框 + 内边距 | 独立展示的码块，与白底内容区区分 |
| 自定义尺寸 | size 控制边长（px） | 卡片角标小码或海报级大码 |
| 自定义配色 | color / bgColor（hex，可带透明度位） | 品牌色码体；需保证扫码对比度 |
| 占位态 | 同尺寸灰底占位块 + 图标 | value 为空或生成失败 |
API 属性
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
value | string | — | 编码内容；为空时渲染占位块 |
size | number | 128 | 尺寸（px），同时约束 SVG 容器与占位块 |
color | string | — | 码体颜色：仅接受 # 开头 hex（3 / 4 / 6 / 8 位，可带透明度位），非法值回退生成库内建黑色 |
bgColor | string | — | 背景色：格式同 color，非法值回退生成库内建白色 |
bordered | boolean | false | 带边框与内边距 |
className | string | — | 通用：根节点 class（与内置样式合并） |
style | CSSProperties | — | 通用：根节点内联样式 |
使用规范
- value 保持短小（链接 / 编号级），内容越长码点越密，过小尺寸下难以识别；size 与内容长度匹配。
- 安全要求：二维码旁必须展示编码后的真实目标（如完整链接文本），用户跳转前可核对；不展示「只码无文」的不可核验入口。
- 自定义 color / bgColor 必须保持深浅对比（码深底浅），低对比或反色组合会导致扫码失败；非法 hex 静默回退默认色，配置后应确认生效。
- 二维码不替代可复制文本：重要链接同时提供文本与复制入口。
- value 动态变化时组件自动重新生成；空 value 期间呈现占位块，避免闪现错误码。
正例
- ✓ 分享弹层：value 传分享链接，码下方附链接文本与「复制链接」按钮，bordered 独立成块。
- ✓ 移动端接力：详情页侧栏 size={96} 小码，文案提示「扫码在手机上继续」。
- ✓ 品牌活动页：color 传品牌主色 hex、bgColor 留白，实测扫码可用后上线。
反例
- ✕ 只展示二维码不给出编码目标文本，用户无法核对跳转去向（违反安全要求）。
- ✕ 把整段长文 / JSON 编码进 QRCode，码点过密无法识别。
- ✕ 用低对比配色（浅色码浅底）或 rgb() 等非 hex 值配置颜色（非法值会被回退）。
Design Token 映射
不适用：组件 tokenRefs 为空：样式 Token 数据尚未接入，三层映射（Primitive → Semantic → Component）待样式 Token 接入后回填。