跳至內容

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 時,它仍可能維持不變。這兩個屬性都不標識硬體。

如何在瀏覽器中測試實體條碼掃描器

先做這一步,再去偵錯應用程式。它顯示瀏覽器收到的精確字串與結束字元。

  1. 接上掃描器,等到它表示已通電。Bluetooth 則完成配對,並確認主機使用的是鍵盤設定檔。
  2. 確認輸入模式。鍵盤楔入、USB HID 鍵盤或 Bluetooth HID 鍵盤可以向欄位打字。序列、SPP 與廠商 SDK 模式不會。
  3. 開啟條碼輸入測試器。
  4. 點選開始測試,或點選掃描區域。就緒時它會變成藍色。頁面不會自己取得焦點。
  5. 掃描一張你已經知道有效載荷的條碼。先用短數字,再掃描包含應用程式所儲存標點的值。
  6. 讀取擷取到的值與字元數。把兩者與期望的有效載荷比較,包括掃描器在資料之前插入的任何前綴。
  7. 檢查後綴。測試器回報 ENTER、TAB 或無。自動擷取開啟時,結果會在 Enter、Tab,或按鍵停止後的短暫停頓之後出現。若希望擷取一直保留到你按下停止,請關閉自動擷取。
  8. 把該結果與應用程式應當儲存的字串比較。前綴、被替換的字元或缺少的結束字元,應在掃描器設定裡修正,或在頁面裡刻意處理。在這次比較完成之前,不要把它當成解碼失敗。

測試器記錄瀏覽器看得到的鍵盤事件。它不能辨識 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 後綴。全域快速鍵把這段文字打進取得焦點的應用程式。它重現楔入掃描器使用的鍵盤路徑。它不會照亮標籤、讀取符號或解碼碼制。

使用上面的範例頁面,或你正在建置的頁面:

  1. 在桌面瀏覽器中開啟頁面,並點選條碼欄位。
  2. 在模擬器中輸入已知值,例如 123456789012。
  3. 把後綴設為 ENTER。如果你想讓這一串按鍵接近已經測過的掃描器,就設定打字延遲。
  4. 在瀏覽器欄位仍有焦點時,按下模擬器的全域掃描快速鍵。
  5. 確認狀態文字,並確認該值只被接受了一次。
  6. 用 TAB 再做一遍。焦點應當移動,值應當只被接受一次。
  7. 用不帶後綴再做一遍。在你按下 Look up 之前,文字應當留在欄位裡。
  8. 聚焦條碼輸入測試器,再送出同一個值。把擷取的字串、前綴與後綴與應用程式儲存的內容比較。

安裝與第一個快速鍵見入門。變更設定之後,先向輸入測試器送出一次掃描,再相信應用程式裡的結果。

光學部分與裝置特有的部分仍然需要硬體:

  • 該掃描器能否解碼印出或顯示的符號,包括損壞的標籤、尺寸、對比度與距離。
  • 碼制支援。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 與重新連線這幾列在硬體上跑。這幾列取決於裝置、標籤或作業系統配置,模擬按鍵不會重現它們。