# QRCode 二维码
基于**纯 TypeScript 零依赖编码器**（自研）的二维码组件，输出内联 SVG，可扫码、可下载。
## 基础用法
`value` 支持任意文本（数字/字母数字/字节模式自动选择），默认尺寸 128px。
## 尺寸
`size` 控制渲染宽高（最小 32，非法值回退 128）；SVG 用 `viewBox` 缩放，任意尺寸均清晰。
## 纠错级别
error-correction 接受 l/m/q/h 四级别（默认 l），自研编码器全级别真实实现（v1–40 全版本），不再归一降级。级别越高容错越强（H 级约可容忍 30% 污损），同内容下码更密；中心 logo / 弱光扫码场景建议 q/h。
## 中心 Logo
icon 为中心图片 URL（SVG 内嵌渲染，底部自动铺背景色托底）；icon-size 默认 size/5（经验取值 ≤1/5），过大将吃掉纠错余量导致不可扫——logo 遮挡场景请用 q/h 级纠错。
## 颜色与暗色可扫性
前景 color 缺省固定深色 #18181b（与固定白静区配套保证 dark 可扫，可用 --oas-qrcode-color 变量覆盖），可给任意 CSS 色值或 11 个预设名（如 blue → var(--oas-preset-blue)）；背景 bg-color 默认固定纯白——二维码可扫性优先于主题一致性，dark 主题下同样可扫（也可用 --oas-qrcode-bg 变量全局覆盖）。静区边距 margin 默认 4 模块（QR 标准静区要求）。
## 形状与渐变
dot-shape：square（默认）/ rounded / dots；corner-shape：square（默认）/ rounded（三处定位图形换圆角）。非法值静默回落 square。码点形状只改变渲染外观，不改模块矩阵与纠错编码。
gradient 传 JSON 数组（2–3 个色值，如 '["#0b6cff","#7c3aed"]'），按 gradient-angle（CSS 约定，0° 自下而上、90° 自左向右）线性渐变，生效时覆盖 color；非法值回落 color。icon-hide-dots 在中心 logo 覆盖区清空码点（避免点阵从半透明 logo 边缘透出）。可扫性提示：圆点/圆角与渐变会降低边缘对比度，弱光、低分辨率打印或长内容建议保持默认 dot-shape="square"，或提高 error-correction 到 q/h。
## 状态（过期 / 加载 / 已扫描）
点击过期二维码上的「刷新」按钮触发 oas-refresh 事件（demo 中模拟刷新流程：loading → active）。
`status` 取值：`active`（默认）/ `expired` / `loading` / `scanned`。非 active 时盖覆盖层：expired 显示「已过期」+ 刷新按钮（点击派发 `oas-refresh`）、loading 显示加载动画（`aria-busy`）、scanned 显示「已扫描」。覆盖层内容可整体自定义：`template[slot="status"]` 克隆替换。
## 下载 PNG
下载 PNG
点击按钮下载 4 倍清晰度 PNG（静区/颜色/logo 与屏幕渲染一致）
`download()` 把当前二维码离屏栅格化为 PNG 触发下载——渲染层保持 SVG-only（矢量 + SSR 快照一致性），不引入常驻 canvas；中心 logo 在栅格化阶段二次绘制（浏览器会拦截 SVG 内嵌外部图）。
## 空态与超长
`value` 为空时显示「暂无内容」占位；内容超出所选纠错级别、版本 1–40 的容量（v40-L 字节容量 2953）时显示「内容过长」提示。
## 无障碍
图形元素 `role="img"`；`aria-label` 属性优先，缺省走 locale 默认文案（中文「二维码」/ 英文「QR code」），可被屏幕阅读器读出。
## API
### oas-qrcode
#### 属性
| 属性 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| `aria-label` | 容器可访问名称，缺省走 i18n | — | — |
| `bg-color` | 背景色（默认白色——扫码器要求浅色静区，dark 主题下保持白底保证可扫；`--oas-qrcode-bg` 变量可覆盖） | `string` | — |
| `color` | 前景色（码点颜色，默认固定深色 `#18181b`——与固定白静区配套保证 dark 可扫；`--oas-qrcode-color` 变量或预设名/任意色值覆盖） | `string` | — |
| `corner-shape` | 定位图形形状：`square`（默认，与模块栅格逐像素等价）/ `rounded`（三处定位图形换圆角） | `string` | `square` |
| `dot-shape` | 码点形状：`square`（默认）/ `rounded` / `dots`（非法值静默回落 `square`） | `string` | `square` |
| `error-correction` | 纠错级别 l/m/q/h（四级均已实现，默认 l；中心 logo 遮挡或弱光/污损场景建议 q/h） | `string` | `l` |
| `gradient` | 渐变前景：JSON 数组（2–3 个色值，如 `["#0b6cff","#7c3aed"]`），生效时覆盖 `color`（非法值回落 `color`） | `string` | — |
| `gradient-angle` | 渐变角度（CSS 约定：0° 自下而上、90° 自左向右，默认 45） | `string` | `45` |
| `icon` | 中心 logo 图片 URL（建议配合 `error-correction="h"` 保可扫性） | `string` | — |
| `icon-hide-dots` | 中心 logo 覆盖区的码点挖空（布尔属性，避免点阵从半透明 logo 边缘透出） | `boolean` | — |
| `icon-size` | 中心 logo 尺寸（px，默认 size/5， clamp 在 [16, size/2]） | — | — |
| `margin` | 静区边距（模块单位，默认 4） | `string` | `4` |
| `size` | 渲染宽高（px） | `string` | `128` |
| `status` | 状态机：`active`（默认）/ `expired`（过期遮罩，点击刷新派 `oas-refresh`）/ `loading` / `scanned` | `string` | `active` |
| `value` | 二维码内容文本 | `string` | — |
#### 事件
| 事件 | 说明 |
| --- | --- |
| `oas-refresh` | 过期态点击刷新按钮时派发，宿主重新赋值内容后切回 `active` |
#### 插槽
| 名称 | 说明 |
| --- | --- |
| `template[slot="status"]` | 自定义状态覆盖层内容（缺省为各状态内建遮罩） |
#### CSS 变量
| CSS 变量 | 默认值 |
| --- | --- |
| `--oas-qrcode-bg` | `#ffffff` |
| `--oas-qrcode-color` | `#18181b` |
编码器函数（`encodeQR` / `matrixToPath` 等）由 `@oas-ui/ui` 导出，可直接用于 SSR 或自定义渲染。