extension-qr-code

QR 碼掃描器

用於 Caffeine AI 的 QR 碼掃描擴充功能。

概述

此技能可透過裝置相機掃描 QR 碼。它建構在相機元件之上，並使用 jsQR 進行解碼。

前端

QR 碼掃描器支援：

有一個預先建置的 React hook，從 @caffeinelabs/qr-code 匯入，且無法修改。

import { RefObject } from 'react';
import { CameraConfig, CameraError } from '@caffeineai/camera';

export interface QRResult {
  // 解碼後的 QR 碼資料
  data: string;
  // QR 碼掃描時的時間戳記
  timestamp: number;
}

export interface QRScannerConfig extends CameraConfig {
  // 掃描 QR 碼的間隔時間（毫秒，預設：100）
  scanInterval?: number;
  // 保留在歷史記錄中的最大結果數（預設：10）
  maxResults?: number;
  // 載入 jsQR 函式庫的 URL（預設：jsdelivr CDN）
  jsQRUrl?: string;
}

export interface UseQRScannerReturn {
  // 掃描到的 QR 碼陣列（最新的在前）
  qrResults: QRResult[];
  // 是否正在掃描 QR 碼
  isScanning: boolean;
  // jsQR 函式庫是否已載入
  jsQRLoaded: boolean;
  
  // 相機狀態（從 useCamera 傳遞）
  isActive: boolean;
  isSupported: boolean | null;
  error: CameraError | null;
  isLoading: boolean;
  currentFacingMode: 'user' | 'environment';
  
  // 啟動相機並開始掃描 - 成功時回傳 true
  startScanning: () => Promise<boolean>;
  // 停止掃描與相機
  stopScanning: () => Promise<void>;
  // 切換相機前後鏡頭 - 成功時回傳 true
  switchCamera: () => Promise<boolean>;
  // 清除所有掃描結果
  clearResults: () => void;
  // 重置掃描器狀態（停止掃描並清除結果）
  reset: () => void;
  // 在錯誤後重試相機初始化 - 成功時回傳 true
  retry: () => Promise<boolean>;
  
  // 附加到影片元素以顯示相機預覽的 ref
  videoRef: RefObject<HTMLVideoElement>;
  // 附加到用於 QR 處理的 canvas 元素的 ref（可隱藏）
  canvasRef: RefObject<HTMLCanvasElement>;
  
  // 計算狀態
  // 掃描器是否準備好使用（jsQR 已載入且相機支援）
  isReady: boolean;
  // 是否可以開始掃描（準備好且未在載入）
  canStartScanning: boolean;
}

export declare function useQRScanner(config?: QRScannerConfig): UseQRScannerReturn;

使用範例：

import { useQRScanner } from '@caffeineai/qr-code';

function QRScannerComponent() {
    const { 
        qrResults,
        isScanning,
        isActive,
        isSupported,
        error,
        isLoading,
        canStartScanning,
        startScanning,
        stopScanning,
        switchCamera,
        clearResults,
        videoRef,
        canvasRef 
    } = useQRScanner({ 
        facingMode: 'environment',
        scanInterval: 100,
        maxResults: 5
    });

    if (isSupported === false) {
        return <div>不支援相機</div>;
    }

    return (
        <div>
            <video 
                ref={videoRef} 
                style={{ width: '100%', height: 'auto' }}
                playsInline
                muted
            />
            <canvas ref={canvasRef} style={{ display: 'none' }} />
            
            {error && <div>錯誤：{error.message}</div>}
            
            <div>
                <button onClick={startScanning} disabled={!canStartScanning}>
                    開始掃描
                </button>
                <button onClick={stopScanning} disabled={isLoading || !isActive}>
                    停止掃描
                </button>
                {/* 僅在行動裝置上顯示切換相機 */}
                {/Android|iPhone|iPad|iPod|BlackBerry|IEMobile|Opera Mini/i.test(navigator.userAgent) && (
                    <button onClick={switchCamera} disabled={isLoading || !isActive}>
                        切換相機
                    </button>
                )}
            </div>
            
            <div>
                <h3>結果 {qrResults.length > 0 && <button onClick={clearResults}>清除</button>}</h3>
                {qrResults.map(result => (
                    <div key={result.timestamp}>
                        <small>{new Date(result.timestamp).toLocaleTimeString()}</small>
                        <p>{result.data}</p>
                    </div>
                ))}
            </div>
        </div>
    );
}

在應用程式中正確顯示 QR 掃描器的錯誤訊息。