SepQRCode 二维码组件

支持 Canvas / SVG 双渲染、中心图标、状态遮罩、动态更新，以及图片识别二维码（支持倾斜旋转）的二维码组件

1. 基础用法

最基础的二维码渲染，默认使用 Canvas 模式。

JS API 初始化

2. SVG 渲染模式

使用 SVG 渲染，适合需要矢量放大或导出的场景。

JS API 初始化

3. 自定义颜色

自定义前景色与背景色，适应不同主题。

JS API 初始化

4. 纠错等级

支持 L（7%）/ M（15%）/ Q（25%）/ H（30%）四级纠错能力。等级越高越能容忍污损，但容量越小。

JS API 初始化

4.1 自动纠错等级

errorLevel: 'auto' 自动选择：无图标用 M，有图标用 H，避免设错导致无法扫描。

JS API 初始化

无图标 → M

有图标 → H

5. 中心图标

叠加中心 Logo 图标，可自定义圆角（iconRadius）和白色描边（iconBorder）。

JS API 初始化

5.1 圆点样式

dotType: 'dots' 将方块渲染为圆点，类似微信支付码风格。

JS API 初始化

5.2 圆角样式

dotType: 'rounded' 圆角方块，dotRadius 控制圆角比例（0~0.5）。

JS API 初始化

5.3 前景渐变

开启 colorGradient，配合 colorStart / colorEnd 实现对角线渐变。

JS API 初始化

5.4 定位点色

通过 finderColor 单独设置三个定位角的颜色，与前景色区分。

JS API 初始化

5.5 连块圆角

connectedBlocks: true 让相邻模块在接触面上无圆角，视觉上连成一体。

JS API 初始化

5.6 图标边框粗细与背景色

iconBorderSize 控制边框粗细，iconBgColor 设置图标背景色。

JS API 初始化

6. 状态：已失效

二维码过期时显示遮罩与刷新按钮。

JS API 初始化
点击二维码中的刷新按钮

7. 状态：加载中

内容尚未生成时显示加载动画。

JS API 初始化

7.1 状态：已扫描

扫码成功后显示 scanned 状态遮罩。

JS API 初始化

8. 动态更新内容

通过 setValue 动态更换二维码内容。

JS API 初始化
当前值：初始内容

9. 切换渲染类型

运行时通过 setType 在 Canvas / SVG 之间切换。

JS API 初始化
当前类型：canvas

10. 下载二维码

通过 toDataURL 获取 base64 图片，download 方法直接下载。

JS API 初始化

11. 点击事件

点击二维码时触发 onClick 回调，返回当前 value。

JS API 初始化
点击左侧二维码

12. 销毁实例

调用 destroy() 清理 DOM 与事件。

JS API 初始化
点击按钮销毁实例

13. 图片识别二维码

上传包含二维码的图片，自动识别并返回内容。支持倾斜、旋转的二维码。识别采用分层降级策略：优先调用浏览器原生 BarcodeDetector API（Chrome/Edge 安卓识别率最高、性能最优），不支持或识别失败时自动 fallback 到自主解码器。可通过 SepQRCode.scanFile(file, cb)（异步，自动分层）或 SepQRCode.decode(imageSource)（同步，仅自主解码）调用。

上传图片识别
预览
请选择一张包含二维码的图片
识别本页二维码（回环演示）
点击按钮识别上方基础示例中的二维码

14. 摄像头实时扫码

调用摄像头实时识别二维码。通过 SepQRCode.startScan(videoEl, options, cb) 启动，返回 controller 调用 stop() 停止。默认后置摄像头，识别成功自动停止；设置 continuous: true 可连续识别。识别采用分层降级策略（BarcodeDetector 优先 → 自主解码兜底）。支持拍照+手动识别：调用 controller.captureFrame() 截取当前视频帧，再用 SepQRCode.decodeAsync(canvas) 手动识别，适合实时扫描困难的场景。支持手动数字放大（拖滑块调整 1x~8x）和自动闪光灯：连续识别失败时，若设备支持 torch 则自动开启闪光灯，否则通过 onStatus 回调抛出 suggest-torch 事件提示用户。可通过 controller.setTorch(bool) 手动控制。

实时扫码
点击「开启摄像头」
等待识别...

15. 背景图叠加

在二维码下方叠加背景图片，通过 backgroundImage 指定图片 URL，backgroundAlpha 控制透明度（0~1，默认 0.3）。Canvas 模式下图片烘焙进画布，SVG 模式下作为 image 元素嵌入。建议配合高纠错等级（H）使用。

背景图叠加示例
当前使用内置示例背景图

16. 专用二维码模板

通过 SepQRCode.buildContent(type, data) 生成 WiFi、名片、邮箱、电话等标准格式内容，再传入组件渲染。与 parseContent() 互为逆操作。

选择类型并填写字段
点击「生成二维码」查看原始内容

详细说明

组件定位

SepQRCode 是一个轻量级二维码组件，内置纯 JS QR 编码与解码算法（无第三方依赖），支持 Canvas / SVG 双渲染模式，可满足网页展示、矢量导出、移动端扫码、图片识别等场景。

核心用法

  • 通过 value 指定二维码内容（支持中文 UTF-8 编码）
  • type 选 'canvas' 或 'svg'
  • errorLevel 选 L/M/Q/H，含图标时推荐 H
  • status 控制 active/expired/loading/scanned 遮罩
  • SepQRCode.scanFile(file, cb) 识别图片文件中的二维码
  • SepQRCode.startScan(video, opts, cb) 摄像头实时扫码
  • backgroundImage + backgroundAlpha 叠加背景图

注意事项

  • 中文内容自动按 UTF-8 字节编码，版本号随之提升
  • 中心图标需配合高纠错等级（H），否则可能无法扫描
  • toDataURL() 在 SVG 模式下返回 SVG base64
  • 动态更新 onClick 需通过 setState({onClick})
  • dotType: 'dots' 或 'rounded' 可能轻微影响识别率，建议用 M 级以上
  • 图片识别基于纯 JS 实现，支持倾斜/旋转，识别失败返回 null

API 速查

getEl()getValue()setValue() getSize()setSize()getType() setType()setColor()setBgColor() getErrorLevel()setErrorLevel() setDotType()getDotType() setDotRadius()getDotRadius() setColorGradient()setColorStart() setColorEnd()isColorGradient() setIconRadius()getIconRadius() setIconBorder()setIconBorderColor() setBackgroundImage()setBackgroundAlpha() setStatus()refresh() toDataURL()download() getState()setState() subscribe()destroy() SepQRCode.decode() SepQRCode.decodeAsync() SepQRCode.decodeMatrix() SepQRCode.scanFile() SepQRCode.startScan() SepQRCode.barcodeDetectorSupported() SepQRCode.parseContent() SepQRCode.buildContent() SepQRCode.scanHistory() SepQRCode.clearScanHistory() SepQRCode.copyToClipboard()

17. 自动化断言