Barcode Scanner Emulator
如何在 Web 應用程式中測試 QR 碼掃描器輸入
許多能讀 QR 的外接掃描器使用鍵盤楔入模式,把解碼後的 QR 文字打進取得焦點的欄位。掃描一段已知有效載荷,並把它和頁面收到的值比較,即可測試這條路徑。並非每台 QR 掃描器都像鍵盤那樣打字。序列埠裝置與相機解碼器是另一條整合,瀏覽器鍵盤事件也不能辨識實體掃描器。
QR 碼保存資料。掃描器或相機解碼器把這些資料變成文字。Web 應用程式接著必須收到這段文字,判斷掃描何時結束,並加以驗證。本指南就是這項應用程式測試。產生標籤、檢查對比度,以及確認裝置能解碼 QR Code,見QR 碼測試:如何測試 QR 掃描器。包括 EAN 檢查碼在內的一般條碼表單,見如何在 Web 應用程式中測試條碼掃描器。
在 60 秒內測試 QR 掃描器輸入
使用你自己選定的有效載荷,這樣錯一個字元就很明顯。本演練使用 QR-INPUT-TEST-12345。
- 開啟QR 碼產生器,為
QR-INPUT-TEST-12345產生 QR 碼。產生器在瀏覽器中執行。它不會連絡掃描器。 - 接上一台設為鍵盤楔入模式、能夠讀取 QR 的掃描器。僅支援一維碼的掃描器無法解碼這個符號。
- 開啟條碼輸入測試器。
- 點選開始測試,或點選掃描區域,讓欄位取得焦點。測試器不會自己取得焦點,也不會開啟掃描器。
- 掃描該 QR 碼。
- 讀取擷取的文字與字元數。
- 把這段文字與
QR-INPUT-TEST-12345比較。相符包括大小寫、連字號與長度。 - 讀取後綴。掃描器送出這些鍵之一時,測試器回報 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 碼
確認掃描器是二維成像器。提高顯示器亮度,增大碼的尺寸,並讓靜區避開文字與邊框。反光、偏暗的手機螢幕,以及相對工作距離過密的碼,都是光學問題。如果螢幕讀取持續失敗,列印同一有效載荷。一旦任何一次掃描產生文字,應用程式測試仍然使用這段已知字串。