跳到内容

Barcode Scanner Emulator

如何在 Web 应用中测试 QR 码扫描器输入

许多能读 QR 的外接扫描器使用键盘楔入模式,把解码后的 QR 文本打进获得焦点的字段。扫描一段已知载荷,并把它和页面收到的值比较,即可测试这条路径。并非每台 QR 扫描器都像键盘那样打字。串口设备和摄像头解码器是另一路集成,浏览器键盘事件也不能识别实物扫描器。

QR 码保存数据。扫描器或摄像头解码器把这些数据变成文本。Web 应用随后必须收到这段文本,判断扫描何时结束,并加以校验。本指南就是这项应用测试。生成标签、检查对比度,以及确认设备能解码 QR Code,见QR 码测试:如何测试 QR 扫描器。包括 EAN 校验位在内的一般条码表单,见如何在 Web 应用中测试条码扫描器。

在 60 秒内测试 QR 扫描器输入

使用你自己选定的载荷,这样错一个字符就很明显。本演练使用 QR-INPUT-TEST-12345。

  1. 打开QR 码生成器,为 QR-INPUT-TEST-12345 生成 QR 码。生成器在浏览器中运行。它不会联系扫描器。
  2. 连接一台设为键盘楔入模式、能够读取 QR 的扫描器。仅支持一维码的扫描器无法解码这个符号。
  3. 打开条码输入测试器。
  4. 点击开始测试,或点击扫描区域,让字段获得焦点。测试器不会自己取得焦点,也不会打开扫描器。
  5. 扫描该 QR 码。
  6. 读取捕获的文本和字符数。
  7. 把这段文本与 QR-INPUT-TEST-12345 比较。相符包括大小写、连字符和长度。
  8. 读取后缀。扫描器发送这些键之一时,测试器报告 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 码

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