Ir para o conteúdo

Barcode Scanner Emulator

Prefixo e sufixo no leitor de código de barras: guia completo

Um prefixo é um dado ou uma sequência de controle que um leitor de código de barras envia antes do código de barras decodificado. Um sufixo é o que ele envia depois desse valor. O mesmo modelo pode ser ajustado com prefixos e sufixos diferentes, e um leitor serial não os entrega do mesmo jeito que um leitor em cunha de teclado.

Um prefixo de leitor de código de barras é enviado antes do valor decodificado. Um sufixo é enviado depois. Um leitor pode produzir esta sequência:

Prefixo: STX

Código de barras: 123456789

Sufixo: ENTER

No manual, STX em geral significa o caractere de controle, não as três letras S, T e X. Num leitor em cunha de teclado, ENTER costuma ser a tecla Enter, não os dois caracteres CR e LF inseridos num campo de texto. O que você recebe depende do modelo, da interface e do aplicativo. Nenhum ajuste vale para todos os aparelhos.

O guia Sufixos ENTER e TAB em leitores de código de barras fica na escolha e na solução desses dois terminadores. Este guia trata do quadro em volta do código de barras: o que vem antes, o que vem depois e como um aplicativo web deve ler os dois.

O que é um prefixo de leitor de código de barras?

Um prefixo é uma sequência configurada que o leitor transmite antes da carga. A carga é o texto que a simbologia decodificou, como 123456789. O prefixo não faz parte dessa decodificação, a menos que o leitor tenha sido ajustado para acrescentá-lo.

Usos comuns:

  • Marcar o começo de uma mensagem. Protocolos seriais e de terminal às vezes enviam um caractere de controle, muitas vezes chamado STX, para o host saber que um quadro novo começou.
  • Nomear a simbologia. Com o identificador de simbologia AIM ativado, um leitor pode enviar um prefixo imprimível curto, como ]C1 para Code 128 ou ]E0 para EAN, antes dos dígitos. O aplicativo pode ramificar com base nesse identificador.
  • Encaminhar a entrada em software antigo de POS ou de terminal. Um código fixo antes dos dados dizia ao host a qual campo ou dispositivo a leitura pertencia.
  • Marcar uma estação específica. Dois leitores podem receber prefixos imprimíveis diferentes para um registro mostrar qual faixa enviou o código.

Um prefixo imprimível são caracteres comuns. Eles aparecem num campo de texto no começo da string. Um prefixo de caractere de controle, como STX (0x02), não são as letras S, T e X. Um leitor em cunha de teclado pode ser incapaz de digitar esse caractere de controle. Um leitor serial pode enviá-lo como um byte. Leia o manual do modelo que você tem antes de escrever código que espera um ou outro.

Um prefixo não prova que um leitor produziu a entrada. Uma pessoa, uma macro ou o Barcode Scanner Emulator podem digitar os mesmos caracteres. Trate um prefixo como o enquadramento que você configurou e valide a carga como qualquer outra entrada de usuário.

O que é um sufixo de leitor de código de barras?

Um sufixo é uma sequência configurada enviada depois da carga. O trabalho habitual é avisar o aplicativo de que a leitura terminou, ou mover o foco. Os leitores diferem. Alguns oferecem Enter, Tab, CR, LF, CR+LF, uma string personalizada ou nada. Alguns oferecem só uma ou duas dessas opções.

ENTER. A tecla Enter. Num navegador isso é um evento de teclado, event.key === "Enter". Não é inserido num campo de texto comum.

TAB. A tecla Tab, event.key === "Tab". O navegador move o foco para o próximo controle. A tecla não é inserida no campo.

CR. Retorno de carro, ASCII 0x0D. Numa interface serial ou de terminal isso pode ser um byte real depois da carga. Numa cunha de teclado, um ajuste com o nome CR ou retorno de carro em geral significa a tecla Enter. O navegador continua relatando Enter. O valor do campo não ganha um caractere CR.

LF. Avanço de linha, ASCII 0x0A. É um caractere de controle diferente de CR. Num fluxo serial ele pode ser o próprio byte. Uma cunha de teclado não tem uma tecla padrão de avanço de linha como tem Enter e Tab. Não suponha que um item de menu chamado LF digita um caractere visível ou um segundo Enter.

CRLF. CR seguido de LF, os dois bytes 0x0D 0x0A. Alguns hosts seriais e de terminal esperam esse par como fim de linha. Um campo de texto do navegador não guarda esse par quando alguém pressiona Enter.

Caracteres personalizados. Um sufixo imprimível como # ou um código curto é digitado depois do código de barras, então passa a fazer parte da string, a menos que o aplicativo o remova. Um caractere de controle personalizado segue a mesma divisão de STX: bytes numa porta serial, pressionamentos numa cunha e só os pressionamentos que a interface de teclado consegue enviar de fato.

ENTER, CR e LF são nomes aparentados de fim de linha nos manuais. Eles não são intercambiáveis em todo aplicativo. Um leitor em cunha, um leitor serial, o Notepad e um formulário web podem mostrar cada um um resultado diferente para um ajuste com o mesmo nome.

Prefixo e sufixo

Característica Prefixo Sufixo
Posição Antes dos dados do código de barras Depois dos dados do código de barras
Finalidade Marcar o começo ou rotular a entrada Marcar a conclusão ou disparar uma ação
Exemplo STX, ou um identificador AIM imprimível como ]C1 ENTER, TAB ou um caractere imprimível como #
Uso comum Enquadrar ou identificar a leitura Enviar um formulário ou mover o foco
Num campo de texto Caracteres imprimíveis ficam no início do valor Caracteres imprimíveis ficam no fim. Enter e Tab, não
Identidade Um marcador configurado que qualquer pessoa pode digitar Um marcador configurado que qualquer pessoa pode digitar

Remova um prefixo ou um sufixo personalizado só quando você configurou exatamente essa sequência e o registro gravado não deve incluí-la. Deixe um identificador AIM no lugar até o aplicativo ter uma regra para ele.

ENTER, TAB, CR e LF

Esses nomes aparecem nas folhas de configuração. Quem recebe vê pressionamentos ou bytes, conforme a interface. O guia Cunha de teclado HID descreve o caminho dos pressionamentos. Uma porta serial é outro caminho: o aplicativo lê bytes, e o foco não escolhe para onde eles vão.

ENTER

Num leitor em cunha de teclado, ENTER é a tecla Enter. Dentro de um campo de texto de uma linha, os navegadores atuais usam essa tecla para enviar o formulário que o contém. Uma caixa de busca pode confirmar a leitura nesse evento. Um formulário de vários campos pode ser enviado antes de os campos seguintes serem preenchidos. Chame preventDefault() no evento submit, ou no keydown de Enter, quando a página deve manter o valor e ficar onde está. Trate Enter num só lugar. Um listener de keydown e um listener de submit que aceitam a leitura registram ela duas vezes.

Alguns leitores enviam NumPad Enter. event.key continua "Enter". event.code pode ser "NumpadEnter" em vez de "Enter". Teste event.key se as duas teclas devem confirmar o campo.

O guia Sufixos ENTER e TAB em leitores de código de barras compara essas duas escolhas para POS e formulários web. Leitor de código de barras sem ENTER cobre um leitor que digita o código de barras e depois para.

TAB

TAB é a tecla Tab. O navegador move o foco depois de keydown. Leia o campo nesse handler de keydown, enquanto ele ainda tem o foco, e deixe a ação padrão no lugar quando o próximo controle deve receber o cursor. preventDefault() mantém o foco no campo atual.

Shift+Tab é a mesma tecla com Shift pressionado. Um sufixo Tab do leitor é Tab sem Shift. Ignore event.shiftKey se quem usa o teclado precisar voltar pelo formulário.

CR

O retorno de carro leva o cursor ao início da linha num terminal. O byte é 0x0D. Um leitor serial pode acrescentar esse byte à carga. Um ajuste de cunha de teclado chamado CR normalmente envia a tecla Enter em vez de inserir 0x0D no texto. Pressionar Enter num campo do navegador não escreve um caractere CR em input.value.

Se o host for um terminal ou um programa à escuta de uma porta COM, procure o byte. Se o host for uma página web, procure event.key === "Enter".

LF

O avanço de linha desce o cursor do terminal uma linha. O byte é 0x0A. Alguns hosts tratam LF sozinho como a quebra de linha. Outros o ignoram, a menos que CR tenha vindo antes. Um leitor em cunha que lista LF como sufixo pode enviar uma tecla que o sistema operacional não transforma em quebra de linha, ou não enviar nada que um campo de texto guarde. Capture a tecla no testador de eventos de teclado antes de tratar um suposto LF no código do aplicativo.

CRLF

CRLF é a sequência de dois controles, CR e depois LF. Arquivos de texto no estilo do Windows e muitos dispositivos seriais usam isso como uma quebra de linha. Uma página de configuração que diz sufixo CRLF significa que o leitor vai tentar enviar esse par depois da carga na interface que estiver usando.

Num navegador, pressionar Enter não produz uma sequência CRLF literal dentro de um campo de texto. O formulário recebe um evento de teclado. Um <textarea> pode inserir uma quebra de linha quando o usuário pressiona Enter, e essa quebra é o comportamento de edição do próprio navegador, não uma prova de que o leitor emitiu os bytes 0x0D 0x0A. Um leitor serial pode receber esses dois bytes e só deve tratá-los como terminador se aquele leitor foi configurado para enviá-los. Não remova CR ou LF do meio de uma carga que pode contê-los.

Como prefixos e sufixos afetam aplicativos web

Uma leitura em cunha de teclado é uma rajada de pressionamentos no controle em foco. A página não abre o leitor. Se o foco estiver em outro campo, o prefixo, o código de barras e o sufixo vão todos para lá.

keydown dispara para cada tecla, inclusive Enter e Tab, antes de o navegador inserir um caractere ou mover o foco. event.key é o caractere ou o nome da tecla depois que o sistema operacional aplica o layout do teclado. Caracteres imprimíveis de prefixo e sufixo aparecem no campo pelo evento input. Enter e Tab não aparecem.

O listener abaixo confirma o campo quando Enter chega. Ele não acrescenta um sufixo que o leitor omitiu. Se o leitor não envia Enter, o valor fica no campo até outra coisa lê-lo.

const field = document.querySelector('#barcode')

if (!(field instanceof HTMLInputElement)) {
  throw new Error('Barcode field was not found.')
}

field.addEventListener('keydown', (event) => {
  if (event.key !== 'Enter') {
    return
  }

  event.preventDefault()
  const value = field.value.trim()
  if (!value) {
    return
  }

  console.log(value)
  field.value = ''
})

Foque #barcode antes da leitura. preventDefault() impede que um formulário ancestral envie uma segunda vez. Se o campo não estiver dentro de um formulário e você quiser o envio nativo, omita preventDefault().

Sem sufixo, espere uma ação explícita: um botão, um Enter posterior de quem opera ou o passo seguinte do fluxo. Um temporizador de inatividade pode tratar uma pausa como o fim da leitura. Esse temporizador é uma heurística. Um leitor lento, um atraso de Bluetooth ou alguém que digita rápido podem cair do lado errado. Prefira um sufixo configurado quando o fluxo precisa de um fim definido.

Um prefixo imprimível conhecido pode ser removido depois que você lê o valor:

function withoutConfiguredPrefix(value, prefix) {
  if (prefix && value.startsWith(prefix)) {
    return value.slice(prefix.length)
  }
  return value
}

Passe só o prefixo que você configurou, como ']C1'. Não remova um número arbitrário de caracteres de cada leitura.

Para um formulário completo que também trata Tab, entrada vazia e uma segunda leitura, veja Como testar leitores de código de barras em aplicativos web.

Como configurar prefixos e sufixos

Os ajustes de prefixo e sufixo ficam no leitor. Os nomes das teclas e o jeito de mudá-los dependem do fabricante. Não existe um código de barras de configuração que funcione em todas as marcas, e este guia não imprime um.

Métodos típicos:

  • Leia um código de barras de configuração do manual daquele modelo exato. A folha é agrupada por ajuste: sufixo, prefixo, layout de teclado, simbologia.
  • Use o programa de configuração do fabricante e depois grave o resultado no leitor por USB.
  • Use o utilitário de gerenciamento de dispositivos daquela linha quando estiver atualizando muitas unidades.

Depois de uma mudança, leia um código de barras conhecido e compare o resultado com a descrição do ajuste escolhido no manual. Uma redefinição de fábrica de outra marca pode deixar o leitor igual ou colocá-lo num modo inesperado. O Guia de configuração do leitor de código de barras resume os ajustes que costumam importar. Ele não substitui o manual.

O Barcode Scanner Emulator pode digitar um valor que você escolhe e depois enviar ENTER, TAB ou nenhum sufixo. Coloque um prefixo imprimível nesse valor quando precisar exercitar o tratamento do prefixo sem hardware. O emulador não emite um par de bytes CR/LF serial e não lê uma etiqueta.

Como testar o comportamento de prefixo e sufixo

Use um leitor em modo teclado, teclado HID USB ou teclado HID Bluetooth.

  1. Conecte-o e espere até ele mostrar que está ligado.
  2. Abra o testador de entrada de código de barras.
  3. Clique em Start Test ou na área de leitura. Ela fica azul quando está pronta. A página não toma o foco sozinha.
  4. Leia um código de barras cuja carga você já conhece.
  5. Leia o valor capturado e a contagem de caracteres. Caracteres imprimíveis de prefixo ou sufixo estão dentro dessa string. A linha Prefix é para teclas nomeadas que chegam antes do primeiro caractere, como um modificador. Ela não tira um prefixo digitado como ]C1 do texto do código de barras.
  6. Confira o sufixo. O testador informa ENTER, TAB ou None. Com Auto capture ligado, o resultado aparece depois de Enter, Tab ou uma pausa curta quando as teclas param. Desligue Auto capture para segurar a captura até você pressionar Stop. Enter e Tab não fazem parte da string do código de barras.
  7. Compare esse resultado com a configuração que você pretendia. Depois abra o testador de eventos de teclado e leia de novo quando precisar de cada keydown em ordem, incluindo key, code e o tempo.

O testador de entrada registra eventos de teclado que o navegador consegue ver. Ele não lê uma porta serial, então não mostra CR ou LF como bytes brutos. Um teste em cunha não prova o que um ajuste serial vai enviar.

Solução de problemas

O leitor não envia ENTER. O código de barras aparece e o cursor fica no campo. O testador de entrada informa None. O sufixo está desligado ou está ajustado para algo que não é Enter. Veja Leitor de código de barras sem ENTER.

TAB move o foco sem você esperar. O leitor está enviando a tecla Tab. Esse é o sufijo configurado. Use Enter quando o formulário deve ser enviado, ou leia o valor no keydown de Tab quando o fluxo deve avançar. Os detalhes estão no guia Sufixos ENTER e TAB em leitores de código de barras.

O formulário é enviado duas vezes. O navegador envia no Enter, e um listener de keydown também aceita a leitura. Mantenha um só caminho de conclusão e chame preventDefault() no outro.

Um prefixo aparece dentro do código de barras. Um prefixo imprimível faz parte da string capturada. Desative-o no leitor ou remova essa sequência exata no aplicativo. Um identificador de simbologia ativado é uma fonte comum de um ] na frente e mais dois caracteres. Um prefixo de controle que a cunha não consegue digitar vai faltar em vez de aparecer.

Os caracteres estão errados. O layout do leitor e o do sistema operacional podem divergir, o que muda caracteres do prefixo e a pontuação enquanto o comprimento continua o mesmo. Veja Layout de teclado errado no leitor de código de barras.

O aplicativo nunca vê o fim da leitura. Não há sufixo, e a página espera Enter. Acrescente um sufixo que combine com o formulário, ou complete o valor numa ação explícita. Um palpite de tempo vai perder algumas leituras reais e aceitar alguma digitação.

CR/LF difere entre aplicativos. O Notepad insere uma linha nova quando recebe Enter. Um campo de texto web guarda o código de barras e dispara um evento de tecla. Um programa serial pode receber 0x0D, 0x0A ou os dois. Compare a interface antes de mudar o leitor. Se nenhum aplicativo recebe caracteres, comece por Leitor de código de barras não funciona.

Uma passagem mais ampla por foco, leituras repetidas e fluxos de POS está em Como testar a entrada do leitor de código de barras.

Matriz de teste

A coluna de configuração é o que você ajusta no leitor, ou o que você digita com o emulador quando o caso é um sufixo de teclado. O comportamento esperado é o que o aplicativo deve fazer. Um caso CRLF serial não é o mesmo teste que uma tecla Enter num navegador.

Configuração Comportamento esperado do aplicativo
Sem prefixo, sem sufixo O valor do código de barras é recebido e nenhuma tecla de conclusão chega. O valor fica disponível até o aplicativo lê-lo.
Sem prefixo, sufixo ENTER O aplicativo recebe a tecla de conclusão uma vez e grava a carga sem um caractere terminador.
Sem prefixo, sufixo TAB O foco pode ir para o próximo controle. O aplicativo lê o valor antes desse movimento.
Prefixo imprimível personalizado Os caracteres do prefixo aparecem antes dos dados decodificados. O aplicativo mantém ou remove esse prefixo exato de propósito.
Sufixo imprimível personalizado Os caracteres do sufixo aparecem depois dos dados decodificados. Enter e Tab são teclas, então não aparecem na string.
Sequência CRLF Um host serial ou de terminal processa os bytes CR e LF configurados. Um campo de texto do navegador não ganha esses bytes a partir de um pressionamento de Enter.

Execute as linhas de teclado no leitor em cunha e, quando não houver hardware, com os ajustes ENTER, TAB e sem sufixo do emulador. Execute a linha CRLF na interface que deve carregar esses bytes. Os resultados reais ainda dependem dessa interface e do aplicativo.