浏览器异步解析条形码：Barcode Detection API 使用指南

在浏览器中直接解析图片内的条形码，Barcode Detection API 提供了一个现代化且功能强大的解决方案。然而，它并非直接可用，需要理解其工作原理才能有效实施。

首先需要明确：Barcode Detection API 无法直接处理页面中的 元素。它仅支持四种“可绘制”的图像源：ImageBitmap、HTMLCanvasElement、OffscreenCanvas 和 VideoFrame。因此，核心步骤是将静态图片转换为API能够识别的格式。

将DOM图片转换为可检测的ImageBitmap

转换过程有几个关键注意事项，处理不当容易遇到问题。核心流程是：确保图片加载完成、解决跨域限制、然后将图片绘制到画布上。

• 确保图片加载就绪：首先检查 img.complete === true。如果为 false，必须监听图片的 load 事件，否则获取的画布内容可能为空。
• 处理跨域问题：如果图片来自其他域名（例如CDN），必须设置 img.crossOrigin = 'anonymous'。这一步至关重要，否则在canvas上绘制时会触发“画布污染”，导致API调用失败。
• 创建尺寸匹配的画布：新建canvas时，其宽高应设置为图片的自然尺寸（img.naturalWidth 和 img.naturalHeight），以避免图像拉伸变形，影响条形码识别精度。
• 绘制与转换：使用 ctx.drawImage(img, 0, 0) 将图片绘制到canvas后，推荐使用 canvas.transferToImageBitmap() 来获取 ImageBitmap。若需考虑更广泛的兼容性，createImageBitmap(canvas) 可作为备选方案。

调用BarcodeDetector.detect()并解析结果

获得 ImageBitmap 后，调用API就相对直接了。首先需要实例化检测器，并指定希望识别的条形码格式，例如 ['ean_13', 'code_128', 'qr_code']。

• 异步检测：detect() 方法返回一个 Promise，通常配合 await detector.detect(bitmap) 使用。
• 理解返回结果：调用成功会返回一个数组。数组中的每个对象都包含解码后的字符串（rawValue）、识别出的码制（format，如 "qr_code"），以及条形码在图像中的边界框信息（boundingBox）。
• 空数组的含义：返回空数组并不代表程序出错，仅表示API在当前图片中未识别到任何符合条件的条形码。常见原因包括条形码尺寸过小（建议有效宽度不低于100像素）、图像模糊、倾斜角度过大（超过15°），或背景与条形码对比度不足。

兼容性处理与优化建议

需要注意的是，该API目前主要由Chromium内核的浏览器支持（Chrome 87+、Edge 87+、Opera 73+），Safari和Firefox暂无支持计划。因此，在生产环境中必须做好兼容性处理。

• 先行特性检测：在使用前，务必通过 'BarcodeDetector' in window 进行判断。如果API不存在，应立即回退到纯JavaScript方案，例如使用 jsQR 或 html5-qrcode 等第三方库。
• 性能与图像预处理：对于单张图片，直接检测即可，无需额外节流。但若需批量处理大量图片，建议使用 Promise.allSettled() 控制并发，避免阻塞主线程。此外，在检测前可以对canvas内容进行简单预处理，例如转换为灰度图、使用 ctx.filter = 'contrast(1.5)' 增强对比度，这通常能有效提升低质量截图或照片的识别成功率。