跳到内容

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 和重新连接这几行在硬件上跑。这几行取决于设备、标签或操作系统布局,模拟按键不会复现它们。