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