在 Caffeine AI 前端需要设备摄像头二维码扫描时…

适用于在 Caffeine AI 项目中通过设备摄像头扫描二维码（原文 caffeineai-subscription 为 [none]），并展示扫码结果与错误。

适用场景

解决思路

1. 确保安装兼容依赖：`@caffeineai/qr-code` 为 `~0.1.1`，`@caffeineai/camera` 为 `~0.1.1`。
2. 使用 Caffeine AI 的预制 React hook：从 `@caffeineai/qr-code` 导入 `useQRScanner`；原文说明该 hook 位于 `@caffeinelabs/qr-code/src/hooks/useQRScanner.ts`，且不能修改。
3. 在组件中调用 `useQRScanner(config?)`，可按需传入 `facingMode`、`scanInterval`（默认 100）、`maxResults`（默认 10）、`jsQRUrl`（默认 jsdelivr CDN）等 `QRScannerConfig` 配置。
4. 从 hook 返回值中解构所需内容：`qrResults`（最新在前，元素为 `QRResult`，含 `data: string` 和 `timestamp: number`）、`isScanning`、`jsQRLoaded`、`isActive`、`isSupported`、`error`、`isLoading`、`currentFacingMode`、`startScanning`、`stopScanning`、`switchCamera`、`clearResults`、`reset`、`retry`、`videoRef`、`canvasRef`、`isReady`、`canStartScanning`。
5. 记住方法契约：`startScanning`、`switchCamera`、`retry` 返回 `Promise<boolean>`；`stopScanning` 返回 `Promise<void>`；`clearResults`、`reset` 返回 `void`。
6. 当 `isSupported === false` 时，渲染「Camera not supported」或等效的不支持提示。
7. 把 `videoRef` 挂到 `<video>` 元素上作为相机预览，设置 `playsInline`、`muted`，样式如 `style={{ width: '100%', height: 'auto' }}`。
8. 把 `canvasRef` 挂到 `<canvas>` 元素上用于二维码处理，并隐藏该元素，例如 `style={{ display: 'none' }}`。
9. 当 `error` 存在时，在应用中正确显示错误信息，例如渲染 `Error: {error.message}`。
10. 提供开始扫描按钮：`onClick={startScanning}`，并用 `disabled={!canStartScanning}` 控制禁用状态。
11. 提供停止扫描按钮：`onClick={stopScanning}`，并用 `disabled={isLoading || !isActive}` 控制禁用状态。
12. 仅在移动端显示切换摄像头按钮：使用 `/Android|iPhone|iPad|iPod|BlackBerry|IEMobile|Opera Mini/i.test(navigator.userAgent)` 判断；按钮 `onClick={switchCamera}`，`disabled={isLoading || !isActive}`。
13. 展示扫码结果：遍历 `qrResults`，以 `result.timestamp` 作为 `key`，显示 `new Date(result.timestamp).toLocaleTimeString()` 和 `result.data`。
14. 当 `qrResults.length > 0` 时显示 Clear 按钮，点击调用 `clearResults` 清空结果。
15. 需要停止扫描并清空结果时调用 `reset`；相机初始化出错后调用 `retry` 重试；用 `jsQRLoaded`、`isReady`、`canStartScanning` 判断是否就绪或可开始扫描。
16. 确保在应用界面中正确展示二维码扫描错误消息。

适用边界 · 注意事项

• 不在 Caffeine AI 项目中，或无法安装 `@caffeineai/qr-code` 与 `@caffeineai/camera` 时，不适用。
• 需要修改预制 `useQRScanner` hook 内部实现或自定义 jsQR 解码流程时，不适用，因为原文说明该 hook 不能修改。
• 设备无摄像头或浏览器不支持相机（`isSupported === false`）时，无法正常完成扫码。