Saltar al contenido

Barcode Scanner Emulator

Cómo probar la entrada de un lector de códigos QR en aplicaciones web

Muchos lectores externos capaces de leer QR usan el modo de cuña de teclado y escriben el texto QR descodificado en el campo con el foco. Prueba esa ruta escaneando una carga conocida y comparándola con el valor que recibió la página. No todos los lectores de códigos QR escriben como un teclado. Los dispositivos serie y los descodificadores de cámara son integraciones distintas, y los eventos de teclado del navegador no identifican el lector físico.

Un código QR guarda datos. El lector, o un descodificador de cámara, convierte esos datos en texto. La aplicación web tiene que recibir ese texto, decidir cuándo termina la lectura y validarlo. Esta guía es esa prueba de la aplicación. Generar etiquetas, comprobar el contraste y confirmar que un dispositivo puede descodificar QR Code se trata en Pruebas de códigos QR: cómo probar lectores de códigos QR. Los formularios de códigos de barras en general, incluidos los dígitos de control EAN, se tratan en Cómo probar lectores de códigos de barras en aplicaciones web.

Prueba la entrada del lector de QR en 60 segundos

Usa una carga que hayas elegido, para que un carácter erróneo se note. Este recorrido usa QR-INPUT-TEST-12345.

  1. Abre el Generador de códigos QR y genera un código QR para QR-INPUT-TEST-12345. El generador se ejecuta en el navegador. No contacta con el lector.
  2. Conecta un lector capaz de leer QR, puesto en modo de cuña de teclado. Un lector solo 1D no puede descodificar este símbolo.
  3. Abre el Probador de entrada de códigos de barras.
  4. Haz clic en Iniciar prueba, o haz clic en el área de lectura, para que el campo tenga el foco. El probador no toma el foco por su cuenta y no abre el lector.
  5. Escanea el código QR.
  6. Lee el texto capturado y el número de caracteres.
  7. Compara ese texto con QR-INPUT-TEST-12345. La coincidencia incluye mayúsculas y minúsculas, guiones y longitud.
  8. Lee el sufijo. El probador informa ENTER, TAB o Ninguno cuando el lector envía una de esas teclas.

El probador registra los eventos de teclado que el navegador puede ver. No identifica el dispositivo USB, no lee un puerto serie y no descodifica la imagen QR.

Modos de entrada del lector de QR

El mismo código QR impreso puede llegar por tres integraciones distintas. La prueba de un modo no ejercita los demás.

Lectores de QR en cuña de teclado

En modo teclado HID USB, o en modo teclado HID Bluetooth, el sistema operativo trata al lector como un teclado. Tras una descodificación, el lector escribe la carga en el control que tiene el foco. Un <input> o un <textarea> normal puede recibirla. La página no abre el dispositivo. La guía Cuña de teclado HID describe la secuencia de pulsaciones, los prefijos y los sufijos.

El foco decide el destino. Si el elemento con el foco es el cuerpo del documento, un botón u otro marco, los manejadores de este campo no ven la lectura.

Lectores de QR serie

Un lector serie USB o de puerto COM virtual envía el texto descodificado como octetos al proceso que abrió el puerto. El foco no elige ese proceso. Un campo que solo escucha pulsaciones permanece vacío mientras un terminal en ese puerto muestra la carga.

Los navegadores basados en Chromium pueden abrir un puerto elegido por el usuario con la Web Serial API, en un contexto seguro, tras un gesto del usuario. Firefox y Safari no ofrecen esa API. Un lector en cuña no aparece como puerto serie. Los nombres de puerto, la velocidad en baudios y el encuadre dependen del dispositivo y del controlador. Lectores de códigos de barras USB HID y serie compara las dos interfaces. El Probador de entrada de códigos de barras no puede leer un puerto COM.

Lectura de QR con cámara

Una integración de cámara captura una imagen y descodifica el código QR en software. La página usa una API de cámara y un descodificador. No recibe eventos keydown para la carga. Las apps de cámara del teléfono, los botones de cámara en la página y un lector de imagen de hardware que escribe en un campo son tres productos distintos. Superar una prueba de cuña no significa que el botón de cámara funcione, y una descodificación de cámara correcta no significa que un lector en cuña escriba la misma cadena.

Capturar la entrada del lector de QR con JavaScript

La página de abajo lee un solo campo con el foco. Enter envía el formulario, y el botón Accept usa ese mismo manejador de submit, así que una lectura se procesa una vez. Sin sufijo ENTER, el texto permanece en el campo hasta que alguien activa Accept. La carga capturada se escribe con textContent, de modo que caracteres como < siguen visibles como texto.

El ejemplo acepta tres formatos de aplicación: un identificador de ticket como QR-INPUT-TEST-12345, una URL http o https, o un objeto JSON. Registra el texto escaneado. No navega a una URL encontrada en el código QR. Un lector que no envía Enter sigue funcionando mediante el botón. Tab recorre la etiqueta, el campo y el botón como siempre, porque el script no lo atrapa.

<!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>

Guarda el archivo y ábrelo en un navegador de escritorio. Haz clic en el campo antes de escanear. autocomplete="off" reduce la posibilidad de que un valor guardado sustituya la lectura. La etiqueta y el botón siguen disponibles, así que una persona puede escribir una carga sin lector.

Trata Enter solo en el evento submit del formulario. Un segundo manejador keydown para Enter registra la misma lectura dos veces. preventDefault() mantiene el navegador en esta página. Vacía el campo después de una decisión para que la lectura siguiente no se añada al texto anterior.

Una carga QR puede contener un salto de línea. Un lector en cuña suele escribir ese salto como Enter. En un input de una línea, el formulario puede enviarse en la primera línea y perder el resto. Usa un textarea, o un programa que lee el puerto serie y conserva los octetos, cuando la aplicación deba aceptar texto de varias líneas. Confirma ese comportamiento con un código QR cuya carga incluya un salto de línea.

Tratar las cargas QR

Un símbolo QR no promete un formato de aplicación. La misma simbología puede llevar cualquiera de estos:

  • Texto simple, como QR-INPUT-TEST-12345.
  • Una URL.
  • Un identificador elegido por la aplicación.
  • Una carga estructurada, como un número de ticket más un código de ubicación.
  • Texto JSON, cuando la aplicación definió esa codificación.

El lector transmite los caracteres descodificados. No comprueba que coincidan con una regla de ticket, un catálogo de productos o un esquema JSON. Valida la cadena en la página y valídala otra vez en el servidor. El valor enviado es entrada de usuario ordinaria. El navegador no puede demostrar que lo produjo un lector.

Validar la entrada QR

No des por hecho que una carga QR es numérica. Las reglas EAN-13 no se aplican. Trata el texto como no fiable: muéstralo como texto y no lo asignes a location, innerHTML o una URL de script.

Valores vacíos. Un Enter a solas, o Accept en un campo en blanco, no debe crear un registro. trim() también rechaza una carga que solo son espacios.

Caracteres inesperados. Compara la cadena recibida con el contenido QR conocido. Un desajuste de distribución de teclado suele cambiar la puntuación mientras la longitud se mantiene. Rechaza los caracteres que el formato no permite y muestra el motivo en el texto de estado.

Longitud de la carga. Aplica el máximo que almacena tu aplicación. maxlength en el input trunca una lectura más larga sin error. Ponlo solo cuando cada carga aceptada cabe, y compara el número de caracteres del probador con el campo cuando un valor parece corto.

Prefijos obligatorios. Una comprobación de prefijo pertenece a la aplicación. Esta regla de ticket acepta QR- más letras mayúsculas, dígitos y guiones:

function isTicketId(value) {
  return /^QR-[A-Z0-9-]{1,64}$/.test(value)
}

Quita un prefijo del lector solo cuando ese lector está configurado para enviar un prefijo exacto y la aplicación no lo almacena. Un identificador de simbología AIM es un dato hasta que decidas lo contrario.

Formatos propios de la aplicación. Mantén la regla junto al formato. Un formulario de ticket, una lista de URL permitidas y un objeto JSON necesitan comprobaciones distintas. Un solo patrón numérico rechazará texto QR válido.

Lecturas duplicadas. Una lectura física puede llegar a dos manejadores. Usa un solo camino de finalización, como hace el ejemplo. Un segundo apriete del gatillo es un evento aparte. El ejemplo rechaza una carga que ya ha aceptado. Un formulario de almacén podría incrementar una cantidad en su lugar. Prueba la regla que documenta tu aplicación.

JSON mal formado. JSON.parse lanza un error con texto incompleto. Comprueba la forma después de un análisis correcto. Un array o un número suelto pueden ser JSON válido y seguir siendo el tipo incorrecto:

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 inesperadas. Analiza la URL para ver si es utilizable y conserva la cadena escaneada si la prueba debe coincidir exactamente con la carga QR. URL.href puede añadir una barra o cambiar la codificación. Acepta solo los esquemas que la aplicación pretende. No abras la URL como efecto secundario de la lectura:

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 }
}

Caracteres de control. Rechaza los caracteres de control ASCII en una carga de teclado para que un prefijo oculto siga visible en el texto de estado. CR y LF son caracteres de control. En un lector en cuña, Enter y Tab son teclas. No son caracteres dentro de un input de texto normal. Una carga serie puede contener aun así octetos 0x0D o 0x0A. Quítalos en el límite de encuadre serie y no quites un CR que pertenece al medio de una carga de varias líneas.

Sufijos ENTER y TAB

Un sufijo es configuración opcional del lector. No forma parte del símbolo QR. Sufijos ENTER y TAB en los lectores de códigos de barras muestra cómo distinguir las teclas. Lee el sufijo en el probador de entrada y haz que la página coincida con los lectores que despliegas.

ENTER envía el formulario de un campo de texto de una línea en los navegadores actuales. Úsalo cuando una lectura deba confirmar el valor. Llama a preventDefault() en submit cuando la página deba quedarse en su sitio.

TAB mueve el foco al control siguiente. Lee el valor en keydown mientras el campo todavía tiene el foco. Deja la acción predeterminada en su sitio cuando el campo siguiente deba recibir el foco. Ignora Shift+Tab para que quien usa el teclado pueda retroceder.

Sin sufijo deja la carga en el campo. El botón Accept del ejemplo es el camino de finalización. Un temporizador de inactividad puede suponer que una pausa significa que la lectura terminó. Ese temporizador es una heurística: una ráfaga Bluetooth lenta y quien teclea rápido pueden cruzar el mismo hueco. Prefiere un sufijo configurado cuando el flujo necesita un final firme.

CR y LF son octetos. Un Enter de teclado es event.key === "Enter". No son intercambiables. Un manejador que solo quita \r de un valor de input no verá un Enter de cuña, porque el carácter nunca se insertó. Un manejador que solo observa event.key no partirá un búfer serie en 0x0D. Algunos dispositivos envían NumPad Enter. event.key sigue siendo "Enter". Comprueba event.key, no solo event.code === "Enter".

El sufijo puede cambiar cuando alguien escanea un código de barras de configuración del manual del dispositivo. Vuelve a probar Enter, Tab y la ausencia de sufijo después de cualquier cambio de configuración. No inventes un código de barras de programación. Usa el manual de ese modelo.

Depurar eventos de teclado

Cuando el texto almacenado es incorrecto, inspecciona los eventos en este orden.

keydown. Se dispara para cada tecla, incluidas Enter y Tab, antes de que el navegador inserte un carácter o mueva el foco. Lee el terminador aquí.

input. Se dispara después de que un carácter imprimible cambia el campo. No se dispara para Enter o Tab en un input de texto.

event.key. El carácter o el nombre de tecla después de que el sistema operativo aplica la distribución de teclado.

event.code. La tecla física, como Digit1 o Numpad1. Puede seguir igual cuando un desajuste de distribución cambia event.key.

Foco. Registra document.activeElement antes de la lectura. Si no es el campo QR, el resto del rastro describe el control equivocado. Un iframe tiene su propio foco.

Orden. En una lectura de cuña hacia un campo de texto, a los eventos keydown imprimibles les siguen actualizaciones input y luego un keydown final para Enter o Tab cuando ese sufijo está configurado. change se dispara cuando el campo confirma el valor, normalmente al perder el foco. Una lectura que deja el foco en el mismo campo no produce change al final. No uses change como única señal de finalización.

Tiempo. Los lectores suelen terminar una carga corta bastante por debajo de un segundo. El probador de entrada compara el hueco medio entre caracteres con un umbral de 100 ms y etiqueta el resultado como tiempo, no como identificación del hardware. Quien teclea rápido, el autocompletado o el emulador pueden caer del lado del lector de ese umbral. Una lectura Bluetooth retrasada puede parecer tecleo. Comprueba la carga y el sufijo. Trata el tiempo como una pista.

El Probador de eventos de teclado enumera cada keydown y keyup con key, code, modificadores y marcas de tiempo. El registro son eventos del navegador. No es tráfico USB en bruto.

Probar sin un lector de QR físico

La lógica de la aplicación se puede probar antes de que haya un lector sobre la mesa.

  • Escribe QR-INPUT-TEST-12345 en el campo y activa Accept. Eso comprueba la validación y la presentación. No comprueba la descodificación ni los sufijos.
  • Conduce el mismo campo desde una herramienta de automatización del navegador, como hace la sección siguiente.
  • Usa Barcode Scanner Emulator cuando necesites una escritura al estilo del lector. La aplicación de escritorio envía un valor que introduces, con un retraso de escritura y un sufijo de ninguno, ENTER o TAB, a la aplicación con el foco. Reproduce la ruta de teclado. No fotografía una imagen QR, no descodifica un símbolo y no crea un puerto COM virtual.

El hardware sigue haciendo falta para el comportamiento óptico y del dispositivo: si ese lector puede leer el código mostrado o impreso, si la simbología QR está activada, la distribución de teclado, la configuración del sufijo y los modos serie o SDK del fabricante. El emulador es la comprobación correcta para la ruta de teclado. Es la comprobación incorrecta para demostrar que un dispositivo lee un código QR concreto.

Automatizar las pruebas de entrada QR

Las pruebas de Playwright siguientes conducen la página de ejemplo. Escriben en el campo como lo haría un lector en cuña y luego comprueban el comportamiento de la aplicación. No abren dispositivos USB. @playwright/test es una dependencia de quien ejecuta la prueba. Este sitio no la exige.

Guarda el ejemplo HTML como qr-form.html junto a esta prueba.

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 inserta caracteres en el campo con el foco. No es un dispositivo USB. La prueba de caracteres inesperados usa fill porque el objetivo es el mensaje de validación y la ausencia de un elemento inyectado. Amplía el archivo con un caso de URL y un caso de JSON cuando esos formatos estén en la compilación que publicas. Una aserción de URL debe comparar el texto capturado con la cadena QR original.

Matriz de prueba del lector de QR

Ejecútalas contra la aplicación bajo prueba. La página de ejemplo de arriba cubre las filas de ticket, URL, JSON, duplicado, vacío y caracteres inesperados. Una aplicación solo numérica o de varias líneas necesita su propio resultado esperado.

Escenario Resultado esperado
QR de texto simple Valor exacto recibido
QR de URL URL completa capturada, y la página no navega hasta ella
QR numérico Dígitos conservados
Caracteres especiales Caracteres correctos recibidos
Carga JSON Datos capturados y validados
Sufijo ENTER El procesamiento ocurre una vez
Sufijo TAB Comportamiento del foco resuelto
Sin sufijo La aplicación usa un mecanismo de finalización alternativo
Lectura duplicada La aplicación aplica las reglas de duplicados
Carga no válida Error de validación mostrado
Foco ausente La aplicación trata la entrada ausente de forma segura
Carga larga Sin truncamiento no deseado

Escanea también una carga que contenga un salto de línea si el producto debe almacenar uno. Anota si el campo recibió cada línea.

Resolución de problemas

Empieza con una carga conocida en el probador de entrada. Si el valor del probador ya es incorrecto, la página no es el primer fallo. Si el valor del probador es correcto y la aplicación no, el fallo es el foco, la validación o el manejo de eventos. El lector de códigos de barras no funciona es la lista de comprobación más amplia del dispositivo. Cómo probar la entrada de un lector de códigos de barras cubre el foco, la distribución y los flujos de POS más allá de este formulario.

El lector emite un pitido, pero no aparece ninguna entrada

Un pitido suele significar que el lector descodificó un símbolo. No significa que la página recibió el texto. Confirma el modo de cuña de teclado. Los modos serie y de cámara no escriben en el campo. Haz clic en el campo para que document.activeElement sea ese input y escanea otra vez. Un campo desactivado, de solo lectura u oculto puede ignorar las teclas.

El lector de QR funciona en Notepad, pero no en el navegador

El dispositivo está escribiendo. La página no acepta esas teclas. Revisa el foco, un manejador keydown que llama a preventDefault() en teclas imprimibles y un manejador que solo trata paste. La entrada de cuña no dispara un evento paste. Compara el resultado del probador con el campo de la aplicación.

El lector lee códigos de barras, pero no códigos QR

El dispositivo puede ser solo 1D, o la simbología QR puede estar desactivada. La página no puede arreglar eso. Confirma la compatibilidad 2D y activa QR Code desde el manual del dispositivo, con las comprobaciones de Pruebas de códigos QR: cómo probar lectores de códigos QR. Una lectura correcta de Code 128 solo demuestra la ruta de teclado.

Caracteres incorrectos

Escanea primero QR-INPUT-TEST-12345. Si coincide y una carga URL o JSON no, la distribución está cambiando puntuación como :, /, { o ". Compara event.key con event.code en el Probador de eventos de teclado y consulta Distribución de teclado incorrecta en el lector de códigos de barras. Iguala la distribución de teclado del lector con la del sistema operativo.

ENTER envía el formulario dos veces

El navegador envía el formulario y un manejador keydown también trata Enter. Quédate con un camino de finalización y llama ahí a preventDefault(). Una segunda lectura física es un fallo distinto. El texto de estado del ejemplo dice que la carga ya fue aceptada. Si la primera lectura en sí crea dos registros, busca dos manejadores antes de cambiar el lector.

La entrada QR se trunca

Compara el número de caracteres del probador de entrada con el valor del campo. Un atributo maxlength, una máscara de entrada o preventDefault() en teclas de caracteres puede cortar la cadena. Un salto de línea dentro de la carga QR puede enviar pronto un input de una línea. Algunos lectores también limitan cuántos caracteres escriben. Sube ese límite desde el manual del dispositivo cuando el probador, no solo la aplicación, muestre un valor corto. Al lector de códigos de barras le falta ENTER cubre el caso relacionado en el que la carga llega y el formulario nunca confirma.

El lector no puede leer un código QR en pantalla

Confirma que se trata de un lector de imagen 2D. Sube el brillo de la pantalla, aumenta el tamaño del código y mantén la zona muda libre de texto y bordes. El reflejo, una pantalla de teléfono tenue y un código demasiado denso para la distancia de trabajo son problemas ópticos. Imprime la misma carga si la lectura en pantalla sigue fallando. La prueba de la aplicación sigue usando la cadena conocida en cuanto cualquier lectura produce texto.