Barcode Detection API识别图片条码二维码方法

Barcode Detection API 功能强大，但许多开发者在首次使用时便会遇到障碍——直接将 传递给 detect() 方法，结果要么静默失败，要么抛出异常。这并非 API 本身存在缺陷，而是其对输入源有严格限制。只有四类图像源能够被接受：ImageBitmap、HTMLCanvasElement、OffscreenCanvas 或 VideoFrame。DOM 中的 元素本身不具备绘制能力，传入后可能导致 Promise 一直处于 pending 状态，返回空数组，极端情况下还会报 NotAllowedError 错误。

为何直接传递 给 detect() 会失败

这里涉及几个容易被忽略的细节。首先是加载状态——img.complete 必须为 true，否则 drawImage 无法绘制任何内容，后续操作均无效。其次是跨域问题，如果图片来自 CDN 或其他域，必须提前设置 img.crossOrigin = 'anonymous'，否则 canvas 会被标记为“被污染”，调用 transferToImageBitmap() 时直接报错。最后是尺寸精度，canvas 的宽高必须精确等于 img.naturalWidth 和 img.naturalHeight，任何拉伸或缩放都会显著降低识别率。

ImageBitmap 的两种生成方式如何选择

生成 ImageBitmap 有两种主流方式：canvas.transferToImageBitmap() 和 createImageBitmap(canvas)。前者是推荐方案，性能更优，因为它将 canvas 的内存直接“移交”给 ImageBitmap，不复制像素数据，内存控制更佳。后者兼容性稍高（Chrome 52+ 即可），但可能触发额外的解码开销。

实际差异主要体现在移动端。Android Chrome 90+ 对 transferToImageBitmap 支持良好，但部分旧版本 WebView 可能无法使用，此时需要 fallback 到 createImageBitmap。一个实用的策略是：优先使用 transferToImageBitmap，配合 try/catch，兜底至 createImageBitmap(canvas)。另外需注意，不要直接用 createImageBitmap(img) 转换 DOM 图片，它仍受跨域限制，且尺寸精度无法保证，是最容易踩坑的写法。

检测失败时最应检查的三个硬性条件

返回空数组并不代表 API 损坏，大概率是输入图像未达到最低质量门槛。Barcode Detection API 不做图像增强，一切依赖原始像素匹配。

第一个条件是物理宽度。条码在 canvas 上的实际宽度建议不低于 100px（针对 EAN/UPC 类）或 120px（针对 QR 码），过小则直接忽略。第二个条件是倾斜角，一旦超过 ±15°，漏检概率急剧上升，尤其是 QR 码的四个角点模糊时，几乎无法定位。第三个条件是对比度，如果背景过浅（如浅灰底配白码）、反射光严重或阴影遮挡超过 30%，特征点提取将失败。

一个实用的调试技巧：使用 canvas.toDataURL('image/png') 截取一帧保存下来，肉眼观察条码是否清晰、居中、无畸变。很多时候问题不在代码，而在图片本身。

格式列表写错一个字母即导致 detector 初始化失败

构造 BarcodeDetector 实例时，formats 数组既不能为空，每个值也必须严格符合规范。例如二维码必须写成 "qr_code"，而不是 "qrcode"、"QR_CODE" 或 "qr"。一旦写错，浏览器会直接抛出 TypeError: format list must not be empty——即使数组非空，由于值非法，也会被视为空处理。

那么哪些格式可用？以 detector.getSupportedFormats() 返回为准。Chrome 103+ 支持 ["qr_code", "ean_13", "code_128", "upc_a", "itf", "codabar"] 等常见格式。需注意格式名区分大小写，下划线不可省略。如果只需扫描二维码，仅传递 ["qr_code"] 即可，减少格式列表可略微降低检测延迟，在移动端效果更明显。

最后谈一个更现实的问题：此 API 在 Safari 和 Firefox 中永远不可用。即使编写了 feature detection，'BarcodeDetector' in window 也始终返回 false。不要试图使用 polyfill 或强制启用，现阶段它仅适用于基于 Chromium 的浏览器——认清这一边界，比解决所有技术细节更为重要。