Barcode Scanner Emulator
如何在 Web 應用程式中測試條碼掃描器
許多 USB 與 Bluetooth 條碼掃描器把解碼後的資料當成鍵盤輸入送出,因此 Web 應用程式裡取得焦點的欄位不必靠掃描器專用的瀏覽器 API,也能收到一次掃描。序列埠與廠商 SDK 是另一條整合。鍵盤這條路徑可以用實體掃描器測試,也可以用模擬的按鍵測試。
Web 應用程式通常把條碼掃描器看成鍵盤。要測的是:取得焦點的控制項有沒有收到應用程式期望的有效載荷,以及頁面有沒有處理掃描器設定要送出的結束字元。這個結束字元可能是 Enter、Tab,也可能沒有。
實體掃描器已經接上時,開一次條碼輸入測試器工作階段。開發時需要同一條鍵盤路徑、而硬體不在桌上時,用 Barcode Scanner Emulator。焦點、配置與 POS 流程的較寬檢查在如何測試條碼掃描器輸入。本指南停在瀏覽器應用程式:擷取、後綴、驗證,以及你實際觀察得到的事件。
條碼掃描器如何與 Web 應用程式通訊
介面模式決定頁面收得到什麼。改表單程式之前先確認模式。掃描器常常可以掃一下製造商手冊裡的設定條碼,就能切換模式。
USB HID 鍵盤楔入
在 USB HID 鍵盤模式下,掃描器會列舉成鍵盤。作業系統載入它的一般鍵盤驅動程式。掃描器解碼符號之後,把字元當成按鍵送給目前擁有鍵盤焦點的控制項。頁面聆聽這些按鍵,或讀取它們插入的文字。頁面不會對裝置開啟連線。
正因為這條路徑,結帳欄位、搜尋方塊或其他文字輸入都能用普通 HTML 接受掃描。按鍵順序、前綴與後綴的細節見 HID keyboard wedge 說明。
Bluetooth HID
配對成鍵盤的 Bluetooth 掃描器走同一條應用程式路徑。主機會把它當成 HID 鍵盤,取得焦點的欄位收到按鍵。配對、電池與無線電是裝置端的事。字元一進入瀏覽器,頁面就用處理 USB 楔入輸入的方式處理它們。
序列埠與虛擬 COM 埠
序列掃描器,包括許多 USB 虛擬 COM 埠模式,把解碼後的文字當成埠上的位元組送出。焦點並不決定目的地。開啟埠的處理程序才決定。只聆聽按鍵的文字欄位看不到這條串流。
以 Chromium 為基礎的瀏覽器,可以在使用者選好埠並授予權限之後,透過 Web Serial API 開啟序列埠。Firefox 與 Safari 不提供這個 API。楔入測試不會涵蓋序列整合,序列測試也無法告訴你楔入掃描器會打出什麼字。
廠商專用介面
有些裝置使用廠商 SDK、OPOS、JPOS,或 USB HID POS 這類非鍵盤 HID 介面。這些介面不會對取得焦點的欄位打字。一般網頁無法載入原生 SDK。Chromium 可以在使用者手勢之後,透過 WebHID 要求部分非鍵盤 HID 裝置。鍵盤類 HID 裝置仍然被擋住,所以楔入掃描器與鍵盤無法區分。把廠商介面當成獨立整合,並用真正開啟該介面的軟體來測試。
瀏覽器看得到什麼
一次楔入掃描以 keydown 與 keyup 事件到達,可列印字元會更新取得焦點的欄位。瀏覽器收不到裝置名稱、USB 序號,也收不到標明這是掃描器的旗標。實作了 WebHID 的瀏覽器仍然拒絕鍵盤介面,因此頁面指令碼也讀不到楔入掃描器的原始 HID 報告。
event.key 是作業系統套用目前鍵盤配置之後的字元或鍵名。event.code 為實體按鍵命名,例如 Digit1 或 Numpad1;配置不符改變 event.key 時,它仍可能維持不變。這兩個屬性都不標識硬體。
如何在瀏覽器中測試實體條碼掃描器
先做這一步,再去偵錯應用程式。它顯示瀏覽器收到的精確字串與結束字元。
- 接上掃描器,等到它表示已通電。Bluetooth 則完成配對,並確認主機使用的是鍵盤設定檔。
- 確認輸入模式。鍵盤楔入、USB HID 鍵盤或 Bluetooth HID 鍵盤可以向欄位打字。序列、SPP 與廠商 SDK 模式不會。
- 開啟條碼輸入測試器。
- 點選開始測試,或點選掃描區域。就緒時它會變成藍色。頁面不會自己取得焦點。
- 掃描一張你已經知道有效載荷的條碼。先用短數字,再掃描包含應用程式所儲存標點的值。
- 讀取擷取到的值與字元數。把兩者與期望的有效載荷比較,包括掃描器在資料之前插入的任何前綴。
- 檢查後綴。測試器回報 ENTER、TAB 或無。自動擷取開啟時,結果會在 Enter、Tab,或按鍵停止後的短暫停頓之後出現。若希望擷取一直保留到你按下停止,請關閉自動擷取。
- 把該結果與應用程式應當儲存的字串比較。前綴、被替換的字元或缺少的結束字元,應在掃描器設定裡修正,或在頁面裡刻意處理。在這次比較完成之前,不要把它當成解碼失敗。
測試器記錄瀏覽器看得到的鍵盤事件。它不能辨識 USB 裝置,也不能讀取序列埠。文字編輯器收到掃描而瀏覽器沒有時,接著看掃描器在 Notepad 中可用但在 POS 中不可用。
用 JavaScript 擷取條碼掃描器輸入
掃描器向擁有焦點的元素打字。給欄位一個看得到的標籤,讓它維持為一般文字輸入,以便鍵盤使用者也能鍵入代碼,並在流程認為輸入完成時讀取值。下面的頁面就是這樣做的。Enter 送出表單一次。Tab 完成一個非空白值,然後讓瀏覽器移動焦點。沒有結束字元的掃描會留在欄位裡,直到有人按下 Look up。
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Barcode input example</title>
</head>
<body>
<form id="barcode-form">
<label for="barcode">Barcode</label>
<input id="barcode" name="barcode" type="text" autocomplete="off" spellcheck="false">
<button type="submit">Look up</button>
</form>
<p id="message" role="status"></p>
<ul id="accepted"></ul>
<script>
const form = document.querySelector('#barcode-form')
const field = document.querySelector('#barcode')
const message = document.querySelector('#message')
const list = document.querySelector('#accepted')
if (
!(form instanceof HTMLFormElement) ||
!(field instanceof HTMLInputElement) ||
!(message instanceof HTMLElement) ||
!(list instanceof HTMLUListElement)
) {
throw new Error('Barcode form markup is missing.')
}
function payload(raw) {
return raw.replace(/[\r\n]/g, '').trim()
}
function classify(raw) {
const value = payload(raw)
if (!value) {
return { status: 'empty' }
}
if (/[\u0000-\u001F\u007F]/.test(value)) {
return {
status: 'invalid',
message: 'Control character in the barcode. Check the prefix, suffix, and symbology identifier.',
}
}
return { status: 'ok', value }
}
function accept(value) {
const item = document.createElement('li')
item.textContent = value
list.append(item)
message.textContent = 'Accepted ' + value
field.value = ''
}
function reject(text) {
message.textContent = text
}
form.addEventListener('submit', (event) => {
event.preventDefault()
const outcome = classify(field.value)
if (outcome.status === 'empty') {
reject('No barcode received.')
field.focus()
return
}
if (outcome.status === 'invalid') {
reject(outcome.message)
field.focus()
return
}
accept(outcome.value)
field.focus()
})
field.addEventListener('keydown', (event) => {
if (event.key !== 'Tab' || event.shiftKey) {
return
}
const outcome = classify(field.value)
if (outcome.status === 'empty') {
return
}
if (outcome.status === 'invalid') {
event.preventDefault()
reject(outcome.message)
return
}
accept(outcome.value)
})
field.focus()
</script>
</body>
</html>
儲存該檔案,並在桌面瀏覽器中開啟。如果焦點已經移開,點選欄位。楔入掃描器,或下一節的模擬器,隨後會向 #barcode 打字。
焦點是必要的。如果 document.activeElement 是文件 body、某個按鈕或其他輸入框,這個欄位的聆聽器就看不到這次掃描。字元會進入取得焦點的控制項,或是遺失。當流程準備好接受掃描時呼叫 field.focus(),包括對話方塊關閉之後。
空白輸入會被忽略。表單留在原地,狀態文字說明什麼都沒收到。只有空白字元的輸入在 trim() 之後是空的。
這個範例不會加上 Enter 或 Tab。如果掃描器沒有設定為送出它們,值就留在欄位裡,Look up 是完成路徑。autocomplete="off" 降低已儲存的值取代本次掃描的機會。標籤、按鈕與 Shift+Tab 仍然可用,因此沒有掃描器的人也能輸入代碼。
Enter 只在一處處理。這個範例使用表單的 submit 事件,它同時涵蓋 Look up 按鈕與鍵盤上的 Enter。再為 Enter 加一個 keydown 聆聽器,會把同一次掃描記錄兩次。如果輸入框不在表單內,就在 keydown 上聆聽 Enter,並呼叫 preventDefault(),以免上層表單也送出:
field.addEventListener('keydown', (event) => {
if (event.key !== 'Enter') {
return
}
event.preventDefault()
const value = field.value.trim()
if (!value) {
return
}
console.log(value)
field.value = ''
})
成功接受之後清空欄位,這樣下一次掃描不會接在上一次有效載荷後面。Enter 之後,範例再次聚焦同一欄位,因為該流程期望在同一個框裡進行下一次掃描。Tab 之後,它不動焦點,以便瀏覽器移到下一個控制項。
處理 ENTER 與 TAB 後綴
後綴是掃描器可能在有效載荷之後送出的一個鍵。它是裝置設定。Enter 很常見,也是選用的。如何區分這些結束字元,見條碼掃描器的 ENTER 與 TAB 後綴。先確認正在測試的掃描器上的設定,再讓頁面符合該流程。
ENTER
在目前的瀏覽器中,單行文字欄位裡的 Enter 會送出所在表單。當一次掃描就應當提交該值時使用它,例如查詢框。在 submit 事件上呼叫 preventDefault() 可以阻止瀏覽器離開目前頁面。如果整頁導覽就是你想要的行為,就不要呼叫它。
如果條碼出現了而表單沒有任何動作,掃描器可能沒有送出後綴。條碼掃描器缺少 ENTER會逐步說明該設定。有些裝置送出 NumPad Enter。event.key 仍然是 "Enter"。檢查 event.key,不要只檢查 event.code === "Enter",否則那台掃描器會看起來像故障。
TAB
Tab 把焦點移到下一個可取得焦點的控制項。這適合商品代碼、然後數量這樣的順序。對期望 Enter 來送出的表單,這會出乎意料。
在欄位仍有焦點時,於 keydown 中讀取值。瀏覽器在該事件之後移動焦點。下一個控制項應當取得焦點時,保留預設動作。preventDefault() 把焦點留在原地,這在值無效、希望操作員看到它時有用。忽略 Shift+Tab,以便鍵盤使用者能在表單中向後移動。掃描器的 Tab 後綴是不帶 Shift 的 Tab。
如果聆聽器掛在 blur 或 change 上,並且別的邏輯清空了控制項,Tab 後綴也可能在程式讀到欄位之前就把焦點移走。從 keydown 事件的 target 讀取值。
沒有後綴
沒有後綴時,有效載荷停在欄位裡。應用程式必須決定掃描何時結束。明確的按鈕、操作員稍後按下的 Enter,或進入下一步,都是可靠的完成點。閒置計時器可以把打字中的停頓當成掃描結束。這個計時器是啟發式的。速度慢的掃描器、Bluetooth 延遲,或打字很快的人,都可能落在閾值的錯誤一側。流程需要明確的掃描結束信號時,優先使用已設定的後綴。
設定差異
同一品牌的掃描器出廠後綴可能不同,設定條碼可以在不改 JavaScript 的情況下改變後綴。有些裝置送出前綴、]C1 這類碼制識別碼,或 CR 與 LF。測試使用者實際能選擇的三種結束字元設定:Enter、Tab 與無。記錄已部署的掃描器使用哪一種,並針對該設定測試頁面。
條碼掃描器輸入驗證
驗證欄位收到的字串。不要假定每條條碼的長度、字元集或檢查和都相同。Code 128 與 QR 的有效載荷會變化。EAN-13 是 13 位數字。同時儲存這兩種碼的應用程式需要兩套規則。
空白輸入。 拒絕或忽略它。沒有有效載荷的後綴,或在空白欄位上點選 Look up,都不應該建立紀錄。
非預期字元。 把收到的字串與已知標籤比較。配置不符常常表現為符號變了,例如錯位的數字或標點,而長度不變。控制字元可能來自前綴,或來自 GS1 群組分隔符。允許你的格式所定義的字元。上面的範例拒絕 ASCII 控制字元,使它們留在狀態文字裡可見。期望群組分隔符的 GS1 剖析器應當允許該字元,並拒絕其餘控制字元。
長度。 強制應用程式接受的長度。表單會收到不止一種碼制時,整體最小值與最大值比單一必需長度更安全。輸入上的 maxlength 會靜默截斷更長的有效載荷,因此只在每個被接受的代碼都能放下時才設定它。
前綴。 只有當你設定掃描器送出那個精確前綴、並且應用程式不儲存它時,才去掉前綴。
function withoutConfiguredPrefix(value, prefix) {
if (prefix && value.startsWith(prefix)) {
return value.slice(prefix.length)
}
return value
}
如果掃描器被設定為傳輸 AIM 碼制識別碼,它就是資料。在決定應用程式是否儲存它之前,先留著。
後綴。 不要把結束字元放進儲存的值。Enter 與 Tab 是按鍵。它們不會插入一般文字輸入。序列有效載荷仍可能包含 CR 或 LF 位元組。在剖析序列串流的邊界去掉它們,並測試你沒有從合法包含它們的有效載荷中間去掉它們。
重複送出。 同一次 Enter 如果同時走了 keydown 與 submit,一次掃描可能被處理兩次。只使用一條完成路徑。第二次掃描同一代碼是另一個問題。倉庫表單可能會增加數量。票券表單可能會拒絕已經兌換的代碼。把這條規則放在應用程式裡,並刻意測試它。瀏覽器分不清第二次扣下扳機與第二個聆聽器。
應用程式規則。 檢查和屬於特定碼制。EAN-13 用最後一位作為檢查碼。下面這個函式只接受該格式:
function isEan13(value) {
if (!/^\d{13}$/.test(value)) {
return false
}
let sum = 0
for (let index = 0; index < 12; index += 1) {
const digit = Number(value[index])
sum += index % 2 === 0 ? digit : digit * 3
}
const check = (10 - (sum % 10)) % 10
return check === Number(value[12])
}
Code 128、Code 39 與 QR 不用這個計算。掃描器可能已經檢查過自己的碼制,並傳輸了人可讀的資料。驗證你所儲存的格式,並在伺服器上再檢查一次。送上來的字串是一般使用者輸入。瀏覽器無法證明它來自掃描器。
沒有實體硬體時測試條碼掃描器輸入
Barcode Scanner Emulator 是適用於 Windows、macOS 與 Linux 的桌面應用程式。你輸入要送出的文字,選擇打字延遲,並選擇無、ENTER 或 TAB 後綴。全域快速鍵把這段文字打進取得焦點的應用程式。它重現楔入掃描器使用的鍵盤路徑。它不會照亮標籤、讀取符號或解碼碼制。
使用上面的範例頁面,或你正在建置的頁面:
- 在桌面瀏覽器中開啟頁面,並點選條碼欄位。
- 在模擬器中輸入已知值,例如
123456789012。 - 把後綴設為 ENTER。如果你想讓這一串按鍵接近已經測過的掃描器,就設定打字延遲。
- 在瀏覽器欄位仍有焦點時,按下模擬器的全域掃描快速鍵。
- 確認狀態文字,並確認該值只被接受了一次。
- 用 TAB 再做一遍。焦點應當移動,值應當只被接受一次。
- 用不帶後綴再做一遍。在你按下 Look up 之前,文字應當留在欄位裡。
- 聚焦條碼輸入測試器,再送出同一個值。把擷取的字串、前綴與後綴與應用程式儲存的內容比較。
安裝與第一個快速鍵見入門。變更設定之後,先向輸入測試器送出一次掃描,再相信應用程式裡的結果。
光學部分與裝置特有的部分仍然需要硬體:
- 該掃描器能否解碼印出或顯示的符號,包括損壞的標籤、尺寸、對比度與距離。
- 碼制支援。1D 雷射掃描器讀不了 QR 碼。見QR 碼測試:如何測試 QR 掃描器。
- USB 列舉、Bluetooth 配對,以及掃描器自己的鍵盤配置與後綴設定。
- 序列、HID POS 與廠商 SDK 整合。
模擬器適合鍵盤路徑上的應用程式邏輯。它不適合證明某一台掃描器能讀某一張標籤。
偵錯條碼掃描器的鍵盤事件
儲存的值不對時,按這個順序看事件。
keydown。 每個鍵都會觸發,包括 Enter 與 Tab,發生在瀏覽器插入字元或移動焦點之前。在這裡讀取結束字元。按鍵按住不放時 event.repeat 為 true。楔入掃描器通常為每個字元送出一次獨立的按下。
input。 可列印字元改變欄位值之後在欄位上觸發。如果你需要文字增長過程中的內容,這是該看的事件。Enter 或 Tab 不會觸發它,因為這些鍵不會向文字輸入插入字元。
change。 值確定之後觸發,通常是欄位失去焦點時。把焦點留在同一欄位的掃描器,不會在掃描結束時產生 change。不要把 change 當作唯一的完成信號。
event.key 與 event.code。 字元不對時把兩者都記下來。掃描器配置與作業系統配置不符會改變 event.key,而 event.code 仍像掃描器想按的那個鍵。數字鍵盤上的數字使用 Numpad1 及類似代碼。有些輸入遮罩對它們的處理與 Digit1 不同。條碼掃描器鍵盤配置錯誤解釋這種配置不符。
焦點。 掃描之前立刻記錄 document.activeElement。如果它不是條碼欄位,後面的追蹤解釋的是錯誤的控制項。iframe 有自己的焦點。掃進嵌入框架的內容,只有該框架內的指令碼看得到。
時序。 掃描器常常在遠不到一秒內打完一段短有效載荷。輸入測試器把字元之間的平均間隔與 100 ms 閾值比較,並把結果標為時序,而不是硬體辨識。間隔閾值可能把打字很快的人、自動填入或模擬器當成掃描器。帶字元間延遲的掃描器、Bluetooth 連線或長有效載荷,看起來可能像打字。使用擷取的值與後綴。把時序當作線索。
鍵盤事件測試器列出每一次 keydown 與 keyup,以及 key、code、修飾鍵與時間戳記。當拼好的字串藏住了前綴鍵或數字鍵盤代碼時使用它。這份日誌是瀏覽器事件,不是原始 USB 流量。
Web 應用程式中的常見問題
掃描進了錯誤的欄位。 楔入輸入跟隨焦點。每次會移動焦點的導覽、對話方塊或驗證訊息之後,點選目標欄位。沒有文字欄位的強制回應視窗可能把掃描當成快速鍵吞掉。
掃描器在文字編輯器裡可用,在瀏覽器裡不可用。 裝置正在打字。頁面沒有接受這些鍵。檢查焦點、被停用或唯讀的輸入,以及在可列印鍵上呼叫 preventDefault() 的 keydown 聆聽器。只處理 paste 的聆聽器永遠看不到楔入輸入。如果沒有任何應用程式收到字元,從條碼掃描器無法運作開始。
Enter 把表單送出了兩次,或離開了頁面。 瀏覽器送出了表單,你的聆聽器也處理了 Enter。在其中一條路徑上呼叫 preventDefault(),並且只處理一次值。多欄位表單在掃描器送出 Enter 時,可能在後面的欄位填完之前就送出。該流程改用 Tab,或在表單完成之前阻止送出。
Tab 改變了焦點。 那就是 Tab 鍵。要麼在掃描器上設定 Enter,要麼在 keydown 中讀取值並允許焦點移動。見上面的後綴一節。
鍵盤配置不對。 數字可能在改變標點的配置不符中保留下來。在工作站實際使用的配置上,掃描一個包含你所儲存符號的已知值。
同一次掃描建立了兩筆紀錄。 在懷疑兩次實體掃描之前,先找同一個 Enter 上的兩個聆聽器。然後再刻意做第二次掃描,並確認應用程式所寫的數量或重複規則。
值遺失或被截斷。 maxlength 屬性、輸入遮罩,或在字元鍵上呼叫 preventDefault(),都可能丟掉或截斷有效載荷。把輸入測試器裡的字元數與欄位中的值比較。前綴也會讓正確的有效載荷看起來過長。
QR 碼從不出現。 掃描器可能只支援 1D,或者 QR 碼制被關掉了。應用程式無法修復這一點。先用QR 碼測試:如何測試 QR 掃描器確認硬體,再回到欄位測試。
Web 應用程式測試清單
在你打算發行的組建上、在你支援的每個瀏覽器裡使用這份清單。也檢查一份全新設定檔,以及裝了密碼管理員與自動填入擴充功能的設定檔,因為這些擴充功能會移動焦點。
- 掃描器已連線或已配對,並且主機顯示它已就緒。
- 掃描器處於鍵盤楔入模式,不是序列或廠商 SDK 模式。
- 掃描之前條碼欄位立即取得焦點。
document.activeElement就是該欄位。 - 已知條碼逐字元到達,長度也一致。
- ENTER 後綴送出或接受該值一次,並且不把結束字元留在儲存的字串裡。
- TAB 後綴把焦點移到你打算的下一個控制項,並且在移動之前讀到了值。
- 無後綴設定把值留到應用程式完成處理為止。
- 空白送出被拒絕或忽略。
- 一次掃描不會建立兩筆紀錄。第二次真實掃描遵循應用程式的重複規則。
- 標點、符號,以及你的格式所使用的任何 GS1 分隔符,在往返之後仍然存在。
- 掃描器鍵盤配置與作業系統配置產生標籤上印出的字元。
- 拔除再接上之後,或 Bluetooth 連線中斷之後,下一次掃描仍然到達該欄位。
- 連續幾次掃描保持為各自獨立的值。欄位不會把它們串在一起。
- 在你支援的瀏覽器中,有無常見自動填入擴充功能,同樣的檢查都能通過。
對話方塊、整段結帳的 Tab 順序,以及 POS 數量流程,繼續看如何測試條碼掃描器輸入。
測試案例矩陣
掃描器這一欄是裝置與瀏覽器所做的事。預期行為這一欄是應用程式應當如何回應。業務規則,例如重複的商品代碼是否增加數量,屬於應用程式。把它們寫進測試,不要假定每一種產品都用同一條規則。
| 情境 | 預期行為 |
|---|---|
| 有效條碼 | 應用程式接受該值,並儲存不含結束字元的有效載荷。 |
| 空白輸入 | 應用程式拒絕或忽略它,並且不建立紀錄。 |
| ENTER 後綴 | 應用程式送出或接受該值一次。 |
| TAB 後綴 | 焦點移到預定的下一個控制項,並且值被保留。 |
| 無後綴 | 輸入一直可用,直到應用程式處理它。 |
| 快速連續掃描 | 每個值單獨處理,不與前一個值串接。 |
| 錯誤的鍵盤配置 | 非預期字元在擷取的值中可見,並且驗證失敗。 |
| 重複掃描 | 應用程式遵循自己的重複規則,例如增加數量或拒絕重放。 |
| 無效條碼格式 | 應用程式顯示該格式的驗證錯誤,並且不儲存該值。 |
| 失去輸入焦點 | 應用程式不會編造一條條碼。掃描不存在,或落在取得焦點的控制項裡,頁面保持在安全狀態。 |
有效、空白輸入、ENTER、TAB 與無後綴這幾列,用實體掃描器跑一遍,再用模擬器跑一遍。鍵盤配置、QR 與重新連線這幾列在硬體上跑。這幾列取決於裝置、標籤或作業系統配置,模擬按鍵不會重現它們。