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 码
确认扫描器是二维成像器。提高显示器亮度,增大码的尺寸,并让静区避开文字和边框。反光、偏暗的手机屏幕,以及相对工作距离过密的码,都是光学问题。如果屏幕读取持续失败,打印同一载荷。一旦任何一次扫描产生文本,应用测试仍然使用这段已知字符串。