跳至內容

Barcode Scanner Emulator

如何在 Web 應用程式中測試 QR 碼掃描器輸入

許多能讀 QR 的外接掃描器使用鍵盤楔入模式,把解碼後的 QR 文字打進取得焦點的欄位。掃描一段已知有效載荷,並把它和頁面收到的值比較,即可測試這條路徑。並非每台 QR 掃描器都像鍵盤那樣打字。序列埠裝置與相機解碼器是另一條整合,瀏覽器鍵盤事件也不能辨識實體掃描器。

QR 碼保存資料。掃描器或相機解碼器把這些資料變成文字。Web 應用程式接著必須收到這段文字,判斷掃描何時結束,並加以驗證。本指南就是這項應用程式測試。產生標籤、檢查對比度,以及確認裝置能解碼 QR Code,見QR 碼測試:如何測試 QR 掃描器。包括 EAN 檢查碼在內的一般條碼表單,見如何在 Web 應用程式中測試條碼掃描器。

在 60 秒內測試 QR 掃描器輸入

使用你自己選定的有效載荷,這樣錯一個字元就很明顯。本演練使用 QR-INPUT-TEST-12345。

  1. 開啟QR 碼產生器,為 QR-INPUT-TEST-12345 產生 QR 碼。產生器在瀏覽器中執行。它不會連絡掃描器。
  2. 接上一台設為鍵盤楔入模式、能夠讀取 QR 的掃描器。僅支援一維碼的掃描器無法解碼這個符號。
  3. 開啟條碼輸入測試器。
  4. 點選開始測試,或點選掃描區域,讓欄位取得焦點。測試器不會自己取得焦點,也不會開啟掃描器。
  5. 掃描該 QR 碼。
  6. 讀取擷取的文字與字元數。
  7. 把這段文字與 QR-INPUT-TEST-12345 比較。相符包括大小寫、連字號與長度。
  8. 讀取後綴。掃描器送出這些鍵之一時,測試器回報 ENTER、TAB 或無。

測試器記錄瀏覽器看得到的鍵盤事件。它不辨識 USB 裝置,不讀取序列埠,也不解碼 QR 影像。

QR 掃描器的輸入模式

同一張印好的 QR 碼可以透過三種不同整合到達。測試一種模式並不會涵蓋另外兩種。

鍵盤楔入 QR 掃描器

在 USB HID 鍵盤模式或 Bluetooth HID 鍵盤模式下,作業系統把掃描器當成鍵盤。解碼之後,掃描器把有效載荷打進目前擁有焦點的控制項。普通的 <input> 或 <textarea> 可以接收它。頁面不會開啟裝置。HID keyboard wedge 說明描述按鍵順序、前綴與後綴。

焦點決定目的地。如果取得焦點的元素是文件 body、按鈕或其他框架,這個欄位的聆聽器看不到這次掃描。

序列埠 QR 掃描器

USB 序列或虛擬 COM 埠掃描器把解碼後的文字當成位元組,送給開啟該埠的處理程序。焦點並不選擇那個處理程序。只聆聽按鍵的欄位保持空白,而該埠上的終端機卻會顯示有效載荷。

以 Chromium 為基礎的瀏覽器,可以在安全內容中、於使用者手勢之後,用 Web Serial API 開啟使用者選定的埠。Firefox 與 Safari 不提供這個 API。楔入掃描器不會顯示為序列埠。埠名、鮑率與訊框格式取決於裝置與驅動程式。USB HID 與序列埠條碼掃描器比較這兩種介面。條碼輸入測試器不能讀取 COM 埠。

以相機為基礎的 QR 掃描

相機整合拍攝影像,並在軟體中解碼 QR 碼。頁面使用相機 API 與解碼器。它不會為有效載荷收到 keydown 事件。手機相機應用程式、頁內相機按鈕,以及向欄位打字的硬體成像器,是三種不同產品。通過楔入測試並不表示相機按鈕可用,相機解碼成功也不表示楔入掃描器會打出同一字串。

用 JavaScript 擷取 QR 掃描器輸入

下面的頁面讀取一個取得焦點的欄位。Enter 送出表單,Accept 按鈕使用同一個送出處理函式,因此一次掃描只處理一次。沒有 ENTER 後綴時,文字會留在欄位裡,直到有人啟用 Accept。擷取的有效載荷用 textContent 寫入,因此 < 這類字元仍作為文字可見。

範例接受三種應用程式格式:類似 QR-INPUT-TEST-12345 的票券 id、http 或 https URL,或一個 JSON 物件。它記錄掃描到的文字。它不會導覽到 QR 碼裡的 URL。不送出 Enter 的掃描器仍可透過按鈕運作。指令碼不攔截 Tab,因此 Tab 照常經過標籤、欄位與按鈕。

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>QR input example</title>
</head>
<body>
  <form id="qr-form">
    <label for="qr">QR payload</label>
    <input id="qr" name="qr" type="text" autocomplete="off" spellcheck="false">
    <button type="submit">Accept</button>
  </form>
  <p id="status" role="status"></p>
  <pre id="captured"></pre>
  <script>
    const form = document.querySelector('#qr-form')
    const field = document.querySelector('#qr')
    const status = document.querySelector('#status')
    const captured = document.querySelector('#captured')

    if (
      !(form instanceof HTMLFormElement) ||
      !(field instanceof HTMLInputElement) ||
      !(status instanceof HTMLElement) ||
      !(captured instanceof HTMLElement)
    ) {
      throw new Error('QR form markup is missing.')
    }

    const accepted = new Set()

    function classify(raw) {
      if (/[\u0000-\u001F\u007F]/.test(raw)) {
        return { status: 'invalid', message: 'Control character in the QR payload.' }
      }

      const value = raw.trim()
      if (!value) {
        return { status: 'empty' }
      }
      if (value.length > 2048) {
        return { status: 'invalid', message: 'QR payload is longer than this form accepts.' }
      }
      if (/^QR-[A-Z0-9-]{1,64}$/.test(value)) {
        return { status: 'ok', value }
      }
      if (value.startsWith('{')) {
        try {
          const data = JSON.parse(value)
          if (!data || typeof data !== 'object' || Array.isArray(data)) {
            return { status: 'invalid', message: 'QR JSON must be an object.' }
          }
          return { status: 'ok', value }
        } catch {
          return { status: 'invalid', message: 'QR text is not valid JSON.' }
        }
      }
      if (value.startsWith('http://') || value.startsWith('https://')) {
        try {
          const url = new URL(value)
          if (url.protocol !== 'http:' && url.protocol !== 'https:') {
            return { status: 'invalid', message: 'Only http and https URLs are accepted.' }
          }
          return { status: 'ok', value }
        } catch {
          return { status: 'invalid', message: 'The QR text is not a valid URL.' }
        }
      }
      return { status: 'invalid', message: 'Unexpected QR payload.' }
    }

    form.addEventListener('submit', (event) => {
      event.preventDefault()
      const outcome = classify(field.value)
      if (outcome.status === 'empty') {
        status.textContent = 'No QR payload received.'
        field.focus()
        return
      }
      if (outcome.status === 'invalid') {
        status.textContent = outcome.message
        captured.textContent = ''
        field.focus()
        return
      }
      if (accepted.has(outcome.value)) {
        status.textContent = 'Already accepted ' + outcome.value
        field.value = ''
        field.focus()
        return
      }
      accepted.add(outcome.value)
      captured.textContent = outcome.value
      status.textContent = 'Accepted ' + outcome.value
      field.value = ''
      field.focus()
    })
  </script>
</body>
</html>

儲存檔案,並在桌面瀏覽器中開啟。掃描前點選欄位。autocomplete="off" 降低已儲存的值取代掃描內容的可能。標籤與按鈕仍然可用,因此沒有掃描器時人也可以鍵入有效載荷。

只在表單的 submit 事件裡處理 Enter。第二個針對 Enter 的 keydown 聆聽器會把同一次掃描記錄兩次。preventDefault() 讓瀏覽器留在本頁。作出決定後清空欄位,這樣下一次掃描不會附加到前一段文字。

QR 有效載荷可以包含換行。楔入掃描器常常把這個換行打成 Enter。在單行輸入裡,表單可能在第一行就送出,並丟掉其餘內容。應用程式必須接受多行文字時,使用 textarea,或使用保留位元組的序列讀取器。用一個有效載荷含換行的 QR 碼確認這一行為。

處理 QR 有效載荷

QR 符號並不保證某種應用程式格式。同一種碼制可以攜帶下面任何一種:

  • 純文字,例如 QR-INPUT-TEST-12345。
  • URL。
  • 應用程式選定的識別碼。
  • 結構化有效載荷,例如票券號碼加上位置代碼。
  • JSON 文字,當應用程式定義了這種編碼時。

掃描器傳輸解碼後的字元。它不檢查這些字元是否符合票券規則、商品目錄或 JSON 綱要。在頁面裡驗證字串,並在伺服器上再驗證一次。送出的值是普通使用者輸入。瀏覽器無法證明它來自掃描器。

驗證 QR 輸入

不要假設 QR 有效載荷是數字。EAN-13 規則並不適用。把文字當作不可信內容:以文字顯示它,不要把它指派給 location、innerHTML 或指令碼 URL。

空值。 單獨的 Enter,或在空白欄位上使用 Accept,不應建立紀錄。trim() 也會拒絕只含空白的有效載荷。

非預期字元。 把收到的字串與已知的 QR 內容比較。鍵盤配置不符常常改變標點,而長度保持不變。拒絕格式不允許的字元,並在狀態文字裡說明原因。

有效載荷長度。 強制執行應用程式所儲存的最大值。輸入上的 maxlength 會截斷更長的掃描且不報錯。只在每個被接受的有效載荷都能放下時才設定它;當值看起來偏短時,把測試器的字元數與欄位比較。

必要前綴。 前綴檢查屬於應用程式。這條票券規則接受 QR- 加上大寫字母、數字與連字號:

function isTicketId(value) {
  return /^QR-[A-Z0-9-]{1,64}$/.test(value)
}

只有當那台掃描器被設定為送出一個精確前綴、並且應用程式不儲存它時,才去掉掃描器前綴。AIM 碼制識別碼在你另作決定之前都是資料。

應用程式特定格式。 把規則放在格式旁邊。票券表單、URL 允許清單與 JSON 物件需要不同的檢查。一個數字模式會拒絕有效的 QR 文字。

重複掃描。 一次實體掃描可能命中兩個聆聽器。像範例那樣只使用一條完成路徑。第二次扣下扳機是單獨的事件。範例拒絕已經接受過的有效載荷。倉庫表單則可能增加數量。測試你的應用程式所寫明的規則。

畸形 JSON。 JSON.parse 會在不完整的文字上擲出例外。剖析成功後再檢查形狀。陣列或一個裸數字可以是有效 JSON,卻仍然是錯誤的類型:

function readJsonObject(value) {
  try {
    const data = JSON.parse(value)
    if (!data || typeof data !== 'object' || Array.isArray(data)) {
      return { ok: false, message: 'QR JSON must be an object.' }
    }
    return { ok: true, data }
  } catch {
    return { ok: false, message: 'QR text is not valid JSON.' }
  }
}

非預期 URL。 剖析 URL 以判斷它是否可用,然後在測試必須與 QR 有效載荷完全一致時保留掃描到的字串。URL.href 可能補上斜線或改變編碼。只接受應用程式打算使用的方案。不要把開啟 URL 當作掃描的副作用:

function readWebUrl(value) {
  let url
  try {
    url = new URL(value)
  } catch {
    return { ok: false, message: 'The QR text is not a valid URL.' }
  }
  if (url.protocol !== 'http:' && url.protocol !== 'https:') {
    return { ok: false, message: 'Only http and https URLs are accepted.' }
  }
  return { ok: true, value }
}

控制字元。 拒絕鍵盤有效載荷中的 ASCII 控制字元,這樣隱藏的前綴仍會顯示在狀態文字裡。CR 與 LF 是控制字元。在楔入掃描器上,Enter 與 Tab 是按鍵。它們不是一般文字輸入裡的字元。序列有效載荷仍可能包含 0x0D 或 0x0A 位元組。在序列訊框邊界去掉它們,不要去掉屬於多行有效載荷中間的 CR。

ENTER 與 TAB 後綴

後綴是可選的掃描器設定。它不是 QR 符號的一部分。條碼掃描器的 ENTER 與 TAB 後綴說明如何區分這些鍵。在輸入測試器裡讀取後綴,然後讓頁面與你部署的掃描器一致。

ENTER 會在目前瀏覽器中送出單行文字欄位的表單。一次掃描應當提交該值時使用它。頁面應當留在原地時,在 submit 上呼叫 preventDefault()。

TAB 把焦點移到下一個控制項。在欄位仍有焦點時於 keydown 中讀取值。下一個欄位應當取得焦點時,保留預設動作。忽略 Shift+Tab,以便鍵盤使用者可以往回移動。

無後綴 把有效載荷留在欄位裡。範例中的 Accept 按鈕就是完成路徑。閒置計時器可以猜測一次停頓意味著掃描結束。這個計時器是啟發式的:一次緩慢的 Bluetooth 突發和打字很快的人,都可能跨過同一個間隔。工作流程需要明確的結束時,優先使用已設定的後綴。

CR 與 LF 是位元組。鍵盤 Enter 是 event.key === "Enter"。二者不能互換。只從輸入值中去掉 \r 的聆聽器看不到楔入的 Enter,因為那個字元從未被插入。只觀察 event.key 的聆聽器不會在 0x0D 上拆分序列緩衝區。有些裝置送出數字鍵盤 Enter。event.key 仍然是 "Enter"。檢查 event.key,不要只檢查 event.code === "Enter"。

有人掃描裝置手冊裡的設定條碼時,後綴可能改變。任何設定變更之後,重新測試 Enter、Tab 與無後綴。不要編造程式設計條碼。使用該型號的手冊。

偵錯鍵盤事件

儲存的文字不對時,按這個順序檢查事件。

keydown。 每個鍵都會觸發,包括 Enter 與 Tab,發生在瀏覽器插入字元或移動焦點之前。在這裡讀取結束字元。

input。 可列印字元改變欄位之後觸發。在文字輸入上,它不會因 Enter 或 Tab 觸發。

event.key。 作業系統套用鍵盤配置之後的字元或鍵名。

event.code。 實體按鍵,例如 Digit1 或 Numpad1。配置不符改變 event.key 時,它仍可能維持不變。

焦點。 掃描前記錄 document.activeElement。如果它不是 QR 欄位,後面的追蹤描述的是錯誤的控制項。iframe 有自己的焦點。

順序。 楔入掃描進入文字欄位時,可列印的 keydown 事件之後是 input 更新,然後在設定了該後綴時,是 Enter 或 Tab 的最後一次 keydown。change 在欄位提交值時觸發,通常是在失焦時。把焦點留在同一欄位的掃描,結束時不會產生 change。不要把 change 當作唯一的完成信號。

時序。 掃描器常常在遠不到一秒內打完一段短有效載荷。輸入測試器把字元之間的平均間隔與 100 ms 閾值比較,並把結果標為時序,而不是硬體辨識。打字很快的人、自動填入或模擬器都可能落到該閾值的掃描器一側。延遲的 Bluetooth 掃描看起來可能像打字。斷言有效載荷與後綴。把時序當作線索。

鍵盤事件測試器列出每一次 keydown 與 keyup,以及 key、code、修飾鍵與時間戳記。這份日誌是瀏覽器事件,不是原始 USB 流量。

沒有實體 QR 掃描器時測試

掃描器還沒放上桌面時,也可以測試應用程式邏輯。

  • 把 QR-INPUT-TEST-12345 鍵入欄位並啟用 Accept。這檢查驗證與顯示。它不檢查解碼或後綴。
  • 像下一節那樣,用瀏覽器自動化工具驅動同一個欄位。
  • 需要掃描器式打字時,使用 Barcode Scanner Emulator。這個桌面應用程式把你輸入的值,連同打字延遲以及無、ENTER 或 TAB 後綴,送到取得焦點的應用程式。它重現鍵盤路徑。它不會拍攝 QR 影像、解碼符號或建立虛擬 COM 埠。

光學與裝置行為仍然需要硬體:那台掃描器能否讀取顯示或列印的碼、QR 碼制是否啟用、鍵盤配置、後綴設定,以及序列或廠商 SDK 模式。模擬器是鍵盤路徑的正確檢查。用它來證明裝置能讀取某一張 QR 碼則不合適。

自動化 QR 輸入測試

下面的 Playwright 測試驅動範例頁面。它們像楔入掃描器那樣向欄位打字,然後斷言應用程式行為。它們不開啟 USB 裝置。@playwright/test 是閱讀者的相依性。本站並不要求它。

把 HTML 範例儲存為測試旁邊的 qr-form.html。

import { readFileSync } from 'node:fs'
import { expect, test } from '@playwright/test'

const html = readFileSync(new URL('./qr-form.html', import.meta.url), 'utf8')

async function openForm(page) {
  await page.setContent(html)
}

test('accepts a known QR payload once', async ({ page }) => {
  await openForm(page)
  const field = page.getByLabel('QR payload')
  await field.pressSequentially('QR-INPUT-TEST-12345')
  await field.press('Enter')
  await expect(page.getByRole('status')).toHaveText('Accepted QR-INPUT-TEST-12345')
  await expect(page.locator('#captured')).toHaveText('QR-INPUT-TEST-12345')
})

test('rejects an unexpected payload', async ({ page }) => {
  await openForm(page)
  const field = page.getByLabel('QR payload')
  await field.pressSequentially('not-a-ticket')
  await field.press('Enter')
  await expect(page.getByRole('status')).toHaveText('Unexpected QR payload.')
  await expect(page.locator('#captured')).toBeEmpty()
})

test('commits on ENTER and rejects a duplicate scan', async ({ page }) => {
  await openForm(page)
  const field = page.getByLabel('QR payload')
  await field.pressSequentially('QR-INPUT-TEST-12345')
  await field.press('Enter')
  await field.pressSequentially('QR-INPUT-TEST-12345')
  await field.press('Enter')
  await expect(page.getByRole('status')).toHaveText('Already accepted QR-INPUT-TEST-12345')
  await expect(page.locator('#captured')).toHaveText('QR-INPUT-TEST-12345')
})

test('does not capture keys while the field is unfocused', async ({ page }) => {
  await openForm(page)
  await page.getByRole('button', { name: 'Accept' }).focus()
  await page.keyboard.type('QR-INPUT-TEST-12345')
  await expect(page.getByLabel('QR payload')).toHaveValue('')
  await expect(page.locator('#captured')).toBeEmpty()
  await expect(page.getByRole('status')).toHaveText('')
})

test('shows unexpected characters as text', async ({ page }) => {
  await openForm(page)
  const payload = '<img src=x onerror=alert(1)>'
  const field = page.getByLabel('QR payload')
  await field.fill(payload)
  await page.getByRole('button', { name: 'Accept' }).click()
  await expect(page.getByRole('status')).toHaveText('Unexpected QR payload.')
  await expect(page.locator('#captured img')).toHaveCount(0)
  await expect(page.locator('img')).toHaveCount(0)
})

pressSequentially 把字元插入取得焦點的欄位。它不是 USB 小工具。非預期字元測試使用 fill,因為目標是驗證訊息,以及沒有被注入的元素。當你出貨的版本包含這些格式時,為檔案補上一個 URL 案例和一個 JSON 案例。URL 斷言應當把擷取的文字與原始 QR 字串比較。

QR 掃描器測試矩陣

針對受測應用程式執行這些情境。上面的範例頁面涵蓋票券、URL、JSON、重複、空值與非預期字元這幾列。只接受數字或多行的應用程式需要自己的預期結果。

情境 預期結果
純文字 QR 收到精確值
URL QR 擷取完整 URL,並且頁面不導覽到它
數字 QR 數字得以保留
特殊字元 收到正確字元
JSON 有效載荷 資料被擷取並驗證
ENTER 後綴 處理只發生一次
TAB 後綴 焦點行為得到處理
無後綴 應用程式使用另一種完成機制
重複掃描 應用程式套用重複處理規則
無效有效載荷 顯示驗證錯誤
缺少焦點 應用程式安全地處理缺少的輸入
長有效載荷 沒有意外截斷

如果產品必須儲存換行,也掃描一個含換行的有效載荷。記錄欄位是否收到每一行。

排除問題

從輸入測試器裡的一段已知有效載荷開始。如果測試器的值已經不對,頁面不是第一處故障。如果測試器的值正確而應用程式不對,故障在焦點、驗證或事件處理。條碼掃描器無法運作是更寬的裝置檢查清單。如何測試條碼掃描器輸入涵蓋本表單之外的焦點、配置與 POS 流程。

掃描器蜂鳴但沒有輸入出現

蜂鳴通常表示掃描器解碼了一個符號。它並不表示頁面收到了文字。確認鍵盤楔入模式。序列與相機模式不會向欄位打字。點選欄位,使 document.activeElement 是該輸入,然後再次掃描。被停用、唯讀或隱藏的欄位可以忽略這些鍵。

QR 掃描器在 Notepad 中可用,在瀏覽器中不可用

裝置正在打字。頁面沒有接受這些鍵。檢查焦點、在可列印鍵上呼叫 preventDefault() 的 keydown 聆聽器,以及只處理 paste 的聆聽器。楔入輸入不會觸發 paste 事件。把測試器結果與應用程式欄位比較。

掃描器能讀條碼但不能讀 QR 碼

裝置可能只支援一維碼,或者 QR 碼制被停用。頁面無法修復這一點。確認二維支援,並按照QR 碼測試:如何測試 QR 掃描器中的檢查,從裝置手冊啟用 QR Code。一次成功的 Code 128 掃描只能證明鍵盤路徑。

字元不正確

先掃描 QR-INPUT-TEST-12345。如果它相符,而 URL 或 JSON 有效載荷不相符,配置正在改變 :、/、{ 或 " 這類標點。在鍵盤事件測試器裡比較 event.key 與 event.code,並參閱條碼掃描器鍵盤配置錯誤。把掃描器的鍵盤配置與作業系統對齊。

ENTER 把表單送出兩次

瀏覽器送出表單,同時一個 keydown 聆聽器也處理 Enter。只保留一條完成路徑,並在那裡呼叫 preventDefault()。第二次實體掃描是另一種故障。範例中的狀態文字說明有效載荷已經被接受。如果第一次掃描本身建立了兩筆紀錄,在改掃描器之前先尋找兩個聆聽器。

QR 輸入被截斷

把輸入測試器中的字元數與欄位裡的值比較。maxlength 屬性、輸入遮罩,或字元鍵上的 preventDefault(),都可能截斷字串。QR 有效載荷內部的換行可能提前送出單行輸入。有些掃描器還會限制自己打出的字元數。當測試器而不只是應用程式顯示偏短的值時,按裝置手冊提高該限制。條碼掃描器缺少 ENTER涵蓋相關情形:有效載荷已經到達,表單卻從不提交。

掃描器讀不了螢幕上的 QR 碼

確認掃描器是二維成像器。提高顯示器亮度,增大碼的尺寸,並讓靜區避開文字與邊框。反光、偏暗的手機螢幕,以及相對工作距離過密的碼,都是光學問題。如果螢幕讀取持續失敗,列印同一有效載荷。一旦任何一次掃描產生文字,應用程式測試仍然使用這段已知字串。