Barcode Scanning 掃碼技術：使用 html5-qrcode 實現瀏覽器端的高效掃描

在生活物資管理的場景中，手動輸入「過期日期」已經夠累了，如果還要手動輸入「品名」和「規格」，使用者很快就會放棄。DueWise 的核心目標是「極簡錄入」，而實現這一點的關鍵就是 Barcode Scanning (條碼掃描)。

在 Web 瀏覽器上，我們無法直接使用原生作業系統的掃描 API（如 iOS 的 Vision 或 Android 的 ML Kit）。我們必須仰賴 JavaScript 調用相機並進行影像處理。這篇文章將介紹我們如何利用 html5-qrcode 庫構建這套系統。

技術選型：為什麼是 html5-qrcode？

在開源社群中，有許多掃描庫可供選擇（如 QuaggaJS, ZXing）。我們最終選擇 html5-qrcode 的原因在於：

1. 相機權限管理: 它優雅地處理了媒體設備請求與權限拒絕的邊界案例。
2. 多格式支援: 支援 EAN-13, EAN-8 (超市商品常見條碼), UPC-A 以及 QR Code。
3. 效能平衡: 它在解碼速度與 CPU 佔用率之間取得了良好的平衡。

核心實作：ScannerModal 組件

在 DueWise 中，掃描功能被封裝在一個專屬的 Modal 內。為了保證效能，我們只在 Modal 開啟時才啟動相機。

1. 初始化掃描器

const html5QrCode = new Html5Qrcode("reader"); // "reader" 是 DOM 的 ID
const config = { 
  fps: 10, // 每秒取樣數，太高會導致舊手機發燙
  qrbox: { width: 250, height: 150 }, // 針對條碼形狀優化掃描框
  aspectRatio: 1.0 
};

2. 啟動相機並監聽結果

html5QrCode.start(
  { facingMode: "environment" }, // 強制使用後置鏡頭
  config,
  (decodedText) => {
    // 成功解碼！
    handleScanSuccess(decodedText);
    playBeepSound(); // 仿超市的回饋音效
    html5QrCode.stop(); // 停止相機以省電
  },
  (errorMessage) => {
    // 掃描中（大多數時間是在嘗試對焦，不需理會報錯）
  }
).catch(err => console.error("無法啟動相機", err));

面臨的挑戰：對焦與低光源

Web 掃描器最大的痛點在於微距對焦。當使用者把條碼靠得太近，瀏覽器權限下的相機通常無法自動對焦，導致解碼失敗。

我們採取的優化方案：

1. UI 視覺引導: 我們在掃描畫面上加了一層半透明的 Overlay，並用文字提醒使用者「請保持 15 公分距離，等待自動對焦」。
2. 動態縮放 (Zoom): 部分現代 Android 瀏覽器支援 videoTrack.applyConstraints({ advanced: [{ zoom: 2 }] })。我們研發了動態縮放檢測，如果設備支援，會自動拉近焦距。
3. 手電筒 (Torch): 如果環境太暗，我們提供了一個「開啟閃光燈」的按鈕，這同樣是透過控制 MediaStream 的 Constraints 實現的。

資料對接：從條碼到品名

掃到一串數字（如 4710186000103）只是第一步。DueWise 的願景是透過這串 EAN 碼自動填寫品名。

雖然目前這部分仍在實驗階段，但我們的技術路徑是：

• 優先查詢我們在 D1 中建立的高頻商品快取表。
• 若無結果，則異步請求外部的 Open Food Facts API 或其他第三方資料庫。
• 將獲取的資料透過 Zustand Store 更新到 ItemForm 中，使用者只需確認即可。

使用者回饋：為什麼它感覺「快」？

速度感往往來自於回饋。當 html5-qrcode 解碼成功的那一毫秒，我們做了三件事：

1. 震動回饋: navigator.vibrate(200)。
2. 音效回饋: 播放一段清脆的音頻檔案。
3. 視覺凍結: 立即暫停 video 流，顯示一張「打勾」的成功標誌。

這些細微的設計，讓 DueWise 的掃描體驗從「可以用」躍升到了「好用」。

結論

透過 html5-qrcode 結合精細的相機控制，我們在瀏覽器內實現了接近原生應用的掃描體驗。這不僅解決了用戶的建檔煩惱，更展現了 Web 技術在硬體驅動上的巨大潛力。

下一篇文章，我們將討論多語系與動態路由的藝術：「i18n 多國語系動態路由：[lang] 架構與 SSG 預渲染的技術細節」。