React Barcode Scanner 常见问题
这里提供常见实现和故障排查问题的直接答案。精确的函数签名和默认值请查看 API 参考。
React Barcode Scanner 是什么？
React Barcode Scanner 是一个使用 TypeScript 编写的 React 浏览器扫码组件与 Hooks 库。它基于 Barcode Detection API，随包提供可选的 ZBar WebAssembly polyfill，也兼容 ZXing WASM 等符合该 API 的实现。
可以使用 ZXing WASM 吗？
可以。在安装说明中切换到 ZXing Tab，即可查看对应的安装命令和导入方式。
ZXing polyfill 和随包提供的 ZBar polyfill 都不会覆盖浏览器已有的原生 BarcodeDetector。如果浏览器存在原生实现，实际使用的仍是原生实现。
React Barcode Scanner 支持 Next.js 和 SSR 吗？
包本身可以在服务端渲染期间导入，相机只会在组件挂载到浏览器后启动。在 Next.js 中，应将 Provider、扫码组件和控制组件放在同一个客户端组件内。
如果通过 next/dynamic 禁用 SSR，应动态加载完整的扫码面板。具体参考 Next.js 示例。
如何同时使用多个扫码器？
为每个活动扫码器及其控制组件分别创建 BarcodeScannerProvider。不同 Provider 的媒体流、闪光灯状态、能力检测和错误相互隔离。
具体用法见快速入门中的 Hooks 状态作用域说明。
其他组件可以读取当前相机流或闪光灯状态吗？
可以。将组件放到同一个 BarcodeScannerProvider 下，再调用 useStreamState 或 useTorch。没有 Provider 时，Hooks 会使用全局兼容作用域。
为什么浏览器提示相机不可用？
相机访问需要 HTTPS 或 localhost、用户授予相机权限，并且设备上存在可用相机。通过 onCameraError 或 useCamera().error 可以读取浏览器返回的原始错误。浏览器相机 API 仅允许在安全上下文 中使用。
常见原因包括：用户拒绝权限、相机正被其他应用占用、没有满足约束条件的相机，或者通过非 localhost 域名的普通 HTTP 页面访问。
支持哪些条码格式？
默认格式是 qr_code，实际支持范围取决于当前 BarcodeDetector 实现。随包提供的 ZBar polyfill 不支持 aztec、data_matrix 和 pdf417，可选的 ZXing polyfill 支持这些格式；浏览器原生实现可通过 BarcodeDetector.getSupportedFormats() 查询。通过 options.formats 传入实际需要的格式，减少格式数量也可以避免不必要的检测工作。
<BarcodeScanner options={{ formats: ['qr_code', 'code_128'] }} />为什么闪光灯按钮不可用？
闪光灯支持取决于当前相机、浏览器和设备。等待相机媒体流就绪后检查 useTorch().isTorchSupported。桌面摄像头通常不提供闪光灯能力。
支持 React 18 和 React 19 吗？
支持。React 和 React DOM 是 peer dependencies；组件包使用 React 19 测试，文档应用使用 React 18 构建。业务项目中的 react 和 react-dom 应保持相同版本。
同时支持 ESM 和 CommonJS 吗？
支持。发布包分别提供 ESM、CommonJS 入口和 TypeScript 类型声明。在两种模块系统中都可以使用随包提供的 ZBar polyfill；第三方 polyfill 的模块格式支持请以其自身文档为准。
如何反馈可复现的问题？
请在 GitHub 仓库 创建 issue，并提供包版本、框架和浏览器版本、设备信息、错误回调输出以及最小复现。