Html5-QRCode 使用紀錄II

§ 參考舊的紀錄文章

Html5-QRCode

這次應用在 react 19 開發環境。有一陣子沒用了重新再紀錄一輪。

§ 關鍵知識

支援二種應用模式： 一、Html5Qrcode 未包裝成元件的函式庫。可以自訂成自己喜歡的行為。比如：一進畫面就啟動相機掃碼。 二、Html5QrcodeScanner 包裝成元件了。功能完善。但只能有限的自訂外觀與功能。無法一進畫面就啟動相機掃碼。 在整合應用上建議採用 Html5Qrcode 模式應用。

§ 使用 Html5Qrcode 函式庫

包裝成元件。一進入畫面就啟動相機掃碼。掃碼成功一次就關閉掃碼。

widgets/QRCodeScanOnceWidget

import { useEffect, useId, useMemo } from 'react';
import { Html5Qrcode, Html5QrcodeSupportedFormats, type Html5QrcodeFullConfig } from "html5-qrcode";
import { beep } from '../tools/utils'

export default function QRCodeScanOnceWidget(props: {
  onScanSuccess: (decodedText: string) => void
}) {
  const id = useId();
  const qrcodeRegionId = useMemo(() => (`qri-${id}`), [id]);

  useEffect(() => {
    scanQrCodeOnce(qrcodeRegionId, props.onScanSuccess)
  }, []);

  return (
    <div id={qrcodeRegionId} /> 
  );
}

/**
 * 掃描 QR code 成功後立刻停止。
 */
function scanQrCodeOnce(elementId: string, onScanSuccess: (decodedText: string) => void) {
  //# 建立掃描物件，只掃QR Code而已。
  const targetElement = document.getElementById(elementId);
  if (!targetElement) throw new Error(`elementId:${elementId}不存在!`);

  const config: Html5QrcodeFullConfig = {
    formatsToSupport: [Html5QrcodeSupportedFormats.QR_CODE],
    verbose: false
  };

  const html5QrCode = new Html5Qrcode(elementId, config);

  //# 開始掃描 QR code
  html5QrCode.start(
    { facingMode: "environment" }, // to prefer back camera
    {
      fps: 10,    // Optional frame per seconds for qr code scanning
      qrbox: 250  // Optional if you want bounded box UI
    },
    (decodedText: string) => {
      // 掃碼成功嗶一下
      beep();

      // when read code then stop immediately.
      html5QrCode.stop();

      // send the scan code return
      onScanSuccess(decodedText);
    },
    (_errorMessage: string) => {
      //※ 掃碼失敗不用處理。
      //console.warn('html5QrCode 掃碼失敗:' + errorMessage);
    }
  ).catch(error => {
    const title = 'html5QrCode.start() 出現例外或禁止啟用相機！'
    console.error(title, { error });
    alert(title);
  })
}

使用範例程式碼。

import { useState } from "react";
import { Box, Container, Typography, useEventCallback } from "@mui/material";
import QRCodeScanOnceWidget from "../../widgets/QRCodeScanOnceWidget";

export default function Demo02_AppForm() {
  const [qrcodeMessage, setQrcodeMessage] = useState<string | null>(null)

  const handleScanSuccess = useEventCallback((decodedText: string) => {
    setQrcodeMessage(decodedText)
  });

  return (
    <Container maxWidth='xs'>
      <Typography>測試手機體驗</Typography>

      {qrcodeMessage === null && 
        <QRCodeScanOnceWidget onScanSuccess={handleScanSuccess} />
      }

      <Box>qrcodeMessage:{qrcodeMessage}</Box>
    </Container>
  )
}

§ 使用 Html5QrcodeScanner 元件

仍須再包裝成更友善的高階元件。因操作行為無法滿足一進畫面就啟動相關掃碼故只好放棄。留存參考。

widgets/Html5QrcodePlugin.tsx

/*
 * ref→[Html5QrcodePlugin.jsx](https://github.com/scanapp-org/html5-qrcode-react/blob/main/src/Html5QrcodePlugin.jsx)
 */
import { useCallback, useEffect, useId, useMemo, useState } from 'react';
import { useNavigate } from 'react-router'
import { Html5QrcodeScanner } from 'html5-qrcode';
import type { Html5QrcodeScannerConfig } from 'html5-qrcode/esm/html5-qrcode-scanner';
import { ErrorBoundary, type FallbackProps } from "react-error-boundary";
import { Alert, AlertTitle, Button } from '@mui/material';

// Creates the configuration object for Html5QrcodeScanner.
const dfaultConfig: Html5QrcodeScannerConfig = {
  fps: 10,
  supportedScanTypes: [0],
  rememberLastUsedCamera: true,
  videoConstraints: {
    facingMode: 'environment',
  }
};

export default function Html5QrcodePlugin(props: any) {
  const navigate = useNavigate()
  const id = useId()
  const qrcodeRegionId = useMemo(() => (`qri${id}`), [])
  const [errMsg, setErrMsg] = useState<string | null>(null)

  const handleScanSuccess = (decodedText: string, decodedResult: any) => {
    // handle decoded results here
    console.trace('handleScanSuccess', { decodedText, decodedResult })
    setErrMsg(null)
    props.qrCodeSuccessCallback && props.qrCodeSuccessCallback(decodedText, decodedResult)
  };

  const handleScanFailure = useCallback((error: string) => {
    // handle scan failure, usually better to ignore and keep scanning.
    console.error('handleScanFailure', { error })
    setErrMsg(error)
  }, []);

  useEffect(() => {
    // when component mounts
    const config = dfaultConfig;
    const verbose = false;

    const html5QrcodeScanner = new Html5QrcodeScanner(qrcodeRegionId, config, verbose);
    html5QrcodeScanner.render(handleScanSuccess, handleScanFailure);

    // cleanup function when component will unmount
    return () => {
      html5QrcodeScanner.clear().catch(error => {
        console.error("Failed to clear html5QrcodeScanner. ", error);
      });
    };
  }, []);

  return (
    <ErrorBoundary fallbackRender={fallbackRender}
      onReset={(_details) => {
        navigate(0); // 無法重設此元件只好刷新頁面
      }}>
      <div>
        <div id={qrcodeRegionId} />
        {errMsg && <pre style={{ color: 'red' }}>{errMsg}</pre>}
      </div>
    </ErrorBoundary>
  );
};

//-------------------------------------
function fallbackRender({ error, resetErrorBoundary }: FallbackProps) {
  const errorMessage = error instanceof Error ? error.message
    : error;

  return (
    <Alert severity="error">
      <AlertTitle>元件出現問題！</AlertTitle>
      <span>{errorMessage}</span><br />
      <Button onClick={() => resetErrorBoundary()}>重設元件</Button>
    </Alert>
  )
}

(EOF)