Definir modos de codificação de QR Code em Python

Todo gerador de QR escolhe um modo de codificação para você por padrão, e na maioria das vezes esse padrão é suficiente. Ele deixa de ser suficiente no momento em que você precisa de controle sobre ele — um ID numérico ao lado de um código de produto, um bloco de texto japonês que você não quer armazenar como UTF-8, ou uma carga útil onde você precisa dos mesmos bytes a cada geração. Este guia mostra como definir modos de codificação de QR code em Python explicitamente, usando Aspose.BarCode for Python via .NET, de modo que um único símbolo QR possa transportar um segmento numérico, um segmento alfanumérico, um segmento de bytes e um segmento Kanji — cada um armazenado no modo que melhor se adequa.

Aspose.BarCode chama esses modos de compactação em seus próprios nomes de API (QrExtCompactionMode) e a especificação QR chama‑os de modos de codificação. São os mesmos quatro modos sob dois nomes, e este guia usa “modo de codificação” ao longo do texto, pois esse é o termo que a especificação e a maioria das bibliotecas QR Python utilizam.

Por que os modos de codificação QR afetam o tamanho do símbolo e a confiabilidade da leitura

O tamanho físico de um código QR é determinado pela quantidade de bits que sua carga útil necessita, e os bits por caractere dependem inteiramente do modo de codificação usado para esse segmento. A especificação define quatro modos de dados com densidades marcadamente diferentes:

Um identificador de 30 dígitos custa aproximadamente 100 bits no modo numérico e 240 bits no modo byte. Essa diferença costuma ser suficiente para elevar o símbolo a várias versões de QR, e uma versão mais alta significa mais módulos na mesma área impressa — módulos menores e uma taxa de leitura mais baixa em câmeras de baixa resolução, embalagens curvas e etiquetas desgastadas.

A seleção automática de modo lida bem com a maioria das cargas úteis. Ela se torna limitadora quando você conhece a forma dos seus dados e o analisador não: uma longa sequência numérica interrompida por uma única letra, texto japonês que o modo byte gastaria três bytes UTF‑8 por caractere, ou um identificador de formato fixo onde você deseja saída determinística entre versões da biblioteca.

Quando Configurar o Modo Manualmente Vale a Pena

A troca de modo não é gratuita. Cada limite de segmento grava um indicador de modo de quatro bits mais um campo de contagem de caracteres de oito a dezesseis bits, dependendo da versão do QR. Segmentar excessivamente uma carga útil pode gerar um símbolo maior do que deixar o gerador decidir.

Definir o modo explicitamente compensa quando:

• O payload contém execuções longas e homogêneas — um número de série de 40 dígitos, um parágrafo de Kanji.
• Você está codificando texto japonês e deseja o modo Kanji a 13 bits por caractere em vez do modo byte a 24.
• Você precisa de saída reproduzível, byte a byte idêntica para testes de regressão ou validação de checksum.

Normalmente, não vale a pena a complexidade adicional para cargas úteis curtas, dados que alternam o tipo a cada poucos caracteres ou URLs, que a análise automática já trata bem. A subseção de medição abaixo mostra como verificar em qual caso você está.

Duas maneiras de definir modos de codificação QR em Python

Aspose.BarCode oferece duas rotas para o mesmo resultado codificado, e vale a pena saber por que ambas existem antes de escrever o código.

O construtor é a melhor opção padrão. QrExtCompactionMode.NUMERIC ou existe ou gera um AttributeError imediatamente, enquanto um \numm digitado incorretamente em uma string silenciosamente se torna dados de carga útil e só aparece quando alguém escaneia o rótulo. Ambas as abordagens alimentam a mesma configuração de gerador QREncodeMode.EXTENDED, de modo que você pode alternar entre elas sem mudar nada a jusante.

Definir modos de codificação de QR Code em Python: passo a passo

1. Instalar e Preparar o Ambiente de Desenvolvimento

Aspose.BarCode for Python via .NET é uma biblioteca multiplataforma que oferece suporte à geração, reconhecimento e manipulação de mais de 50 simbologias, incluindo QR. Instale a partir do PyPI:

pip install aspose-barcode-for-python-via-net

Confirme a versão, pois essas APIs requerem 26.6 ou superior:

pip show aspose-barcode

Em seguida, verifique se a importação é resolvida. O pacote se vincula a um runtime .NET, portanto, uma importação bem‑sucedida indica mais do que apenas a presença de arquivos no disco:

from aspose.barcode.generation import QREncodeMode, QrExtCompactionMode

print("Aspose.BarCode imported successfully.")
print("EXTENDED mode available:", hasattr(QREncodeMode, "EXTENDED"))
print("Encoding modes:", [m for m in dir(QrExtCompactionMode) if m.isupper()])

Output:

Aspose.BarCode imported successfully.
EXTENDED mode available: True
Encoding modes: ['ALPHA_NUMERIC', 'AUTO', 'BYTES', 'KANJI', 'NUMERIC']

Se EXTENDED estiver ausente, você está em uma versão anterior a 26.6 e precisa atualizar antes de continuar.

Se você tem um arquivo de licença, aplique‑o uma vez na inicialização da aplicação, antes de qualquer chamada de geração ou reconhecimento:

from aspose.barcode import License

license = License()
license.set_license("Aspose.BarCode.Python.NET.lic")

2. Defina o modo de codificação para cada segmento com QrExtCodetextBuilder

QrExtCodetextBuilder mantém uma lista ordenada de segmentos. Cada chamada adiciona dados junto com o modo de codificação que deve armazená‑los, e get_extended_codetext() os reúne em uma string de formato estendido que o gerador entende.

1. Importe as classes de geração.
2. Crie um QrExtCodetextBuilder.
3. Adicione um segmento numérico com QrExtCompactionMode.NUMERIC.
4. Adicione um segmento alfanumérico com QrExtCompactionMode.ALPHA_NUMERIC.
5. Adicione um segmento de bytes com QrExtCompactionMode.BYTES.
6. Adicione um segmento Kanji com QrExtCompactionMode.KANJI.
7. Recupere o codetext estendido combinado.

from aspose.barcode.barcoderecognition import BarCodeReader, DecodeType
from aspose.barcode.generation import (
    BarcodeGenerator,
    EncodeTypes,
    QREncodeMode,
    QrExtCodetextBuilder,
    QrExtCompactionMode,
)

# Instantiate the Builder.
text_builder = QrExtCodetextBuilder()

# Numeric Segment — 3 Digits per 10 Bits.
text_builder.add_codetext_with_compaction_mode(
    QrExtCompactionMode.NUMERIC, "1234567"
)

# Alphanumeric Segment — Uppercase and Digits Only, 2 Characters per 11 Bits.
text_builder.add_codetext_with_compaction_mode(
    QrExtCompactionMode.ALPHA_NUMERIC, "ASPOSE2026"
)

# Byte Segment — Lowercase Forces Byte Mode, 8 Bits per Character.
text_builder.add_codetext_with_compaction_mode(
    QrExtCompactionMode.BYTES, "aspose2026"
)

# Kanji Segment — Shift-JIS Double-Byte Characters, 13 Bits Each.
text_builder.add_codetext_with_compaction_mode(
    QrExtCompactionMode.KANJI,
    "\u3062\u3063\u3064\u3065\u3066\u3067\u3068\u3069\u306A",
)

# Assemble the Final Extended Codetext.
codetext = text_builder.get_extended_codetext()
print("Extended codetext:", repr(codetext))

Explicação

• Cada chamada add_codetext_with_compaction_mode define o modo de codificação para um segmento. A ordem importa — o decodificador retorna os segmentos concatenados na sequência em que você os adicionou.
• O conjunto alfanumérico é deliberadamente restrito: dígitos, letras maiúsculas A‑Z, espaço e $%*+-./:. É por isso que ASPOSE2026 se encaixa no modo alfanumérico, mas aspose2026 não. Letras minúsculas estão fora do conjunto, portanto esse segmento deve usar BYTES. Passar minúsculas para ALPHA_NUMERIC é o erro mais comum ao definir modos dessa forma.
• O segmento Kanji usa \u3062 em diante, que são hiragana em vez de kanji propriamente dito. O modo Kanji cobre o intervalo de bytes duplos Shift‑JIS, que inclui kana, portanto esses são codificados em 13 bits cada, em vez dos 24 bits que o modo byte gastaria em cada um como UTF‑8.
• get_extended_codetext() produz a string que o gerador analisa no modo EXTENDED. Imprimi‑la com repr() vale a pena fazer uma vez — ela mostra a sintaxe do seletor que o construtor emite, que é exatamente o que a próxima subseção escreve manualmente.

3. Definir o modo de codificação inline, sem o Builder

Quando o texto do código se origina fora do seu código Python, você pode definir o modo de cada segmento diretamente com um seletor. Cada marcador prefixado por barra invertida controla cada caractere até que o próximo marcador apareça:

# Equivalent to the Builder Output Above, Written Directly.
codetext = (
    r"\num1234567"
    r"\alnumASPOSE2026"
    r"\byteaspose2026"
    "\\kanji\u3062\u3063\u3064\u3065\u3066\u3067\u3068\u3069\u306A"
)

Observe a fuga de caracteres. Em uma string Python normal, "\num" não é um seletor — é uma nova linha seguida de um. Strings brutas (r"...") evitam o problema, mas uma string bruta também bloqueia escapes \u, o que explica por que a linha Kanji acima usa uma string convencional com \\kanji em vez disso. Essa armadilha de escape é o argumento prático para preferir o construtor na seção 2.

4. Gerar o Código de Barras QR no Modo EXTENDED

Definir modos por segmento não tem efeito até que o gerador seja instruído a lê‑los. Sem QREncodeMode.EXTENDED, as informações de segmento são ignoradas e os marcadores de seleção são codificados como texto de carga útil literal.

1. Crie um BarcodeGenerator com EncodeTypes.QR e o codetext estendido.
2. Defina encode_mode como QREncodeMode.EXTENDED.
3. Configure a resolução e, opcionalmente, o nível de correção de erro e a margem.
4. Salve o código de barras em um PNG sem perdas.

# Create the QR Generator with the Extended Codetext.
gen = BarcodeGenerator(EncodeTypes.QR, codetext)

# Switch to EXTENDED Mode So the Per-Segment Modes Are Respected.
gen.parameters.barcode.qr.encode_mode = QREncodeMode.EXTENDED

# Render at Print Resolution Rather Than Upscaling Later.
gen.parameters.resolution = 300

# Save the Generated QR Code.
gen.save("extended_qr.png")

print("QR code generated and saved as extended_qr.png")

Explicação

• gen.parameters.barcode.qr.encode_mode = QREncodeMode.EXTENDED é a linha que ativa a análise de segmentos. Omiti‑la e o gerador produz um QR code válido e escaneável contendo o texto literal \num1234567... — por isso a próxima subseção verifica em vez de assumir.
• gen.parameters.resolution = 300 renderiza na resolução de impressão. Símbolos destinados a impressoras de etiquetas ou arte de embalagem devem ser gerados no tamanho final, não ampliados depois, o que suaviza as bordas dos módulos.
• save grava um PNG sem perdas. Evite JPEG para qualquer simbologia 2D — seus artefatos de compressão desfocam a grade de módulos que o decodificador amostra.

5. Verifique se o modo de codificação foi aplicado

A geração bem-sucedida não prova nada sobre se os modos por segmento entraram em vigor. A etapa de decodificação é o que separa um símbolo codificado corretamente de um que carrega marcadores de seletor como dados.

1. Inicialize um BarCodeReader com o caminho do arquivo e DecodeType.QR.
2. Materialize os resultados para que uma leitura falha seja visível.
3. Compare o texto decodificado com a concatenação esperada.

EXPECTED = (
    "1234567"
    "ASPOSE2026"
    "aspose2026"
    "\u3062\u3063\u3064\u3065\u3066\u3067\u3068\u3069\u306A"
)

# Initialise the QR Code Reader.
reader = BarCodeReader("extended_qr.png", DecodeType.QR)
results = list(reader.read_bar_codes())

if not results:
    raise ValueError("No QR code was detected in extended_qr.png.")

for result in results:
    decoded = result.code_text
    print("BarCode CodeText:", decoded)

if "\\num" in decoded or "\\alnum" in decoded:
        print("Selectors were encoded literally — check that encode_mode is EXTENDED.")
    elif decoded == EXPECTED:
        print("Verified: all four segments decoded and concatenated as expected.")
    else:
        print("Mismatch. Expected:", EXPECTED)

Explicação

• DecodeType.QR restringe o reconhecimento a símbolos QR, o que é mais rápido do que escanear todas as simbologias suportadas e impede que um símbolo malformado seja decodificado como outra coisa.
• list(...) torna o caso de falha explícito. Uma falha de reconhecimento retorna um iterável vazio ao invés de lançar exceção, portanto um loop for sem proteção sobre uma leitura falhada termina silenciosamente e é interpretado como sucesso.
• Verificar um literal \num captura o erro mais comum neste fluxo de trabalho: definir os segmentos corretamente e esquecer de definir encode_mode.
• A carga útil decodificada é a concatenação dos segmentos brutos, com todas as informações de modo consumidas durante a codificação. Os modos de codificação são instruções para o codificador, não fazem parte dos dados.

6. Meça se definir o modo manualmente ajudou

Definir o modo de codificação manualmente é uma otimização, portanto meça‑o em vez de presumir. Gere a mesma carga útil de ambas as maneiras e compare:

RAW = "1234567ASPOSE2026aspose2026"

# Automatic Mode Selection.
auto = BarcodeGenerator(EncodeTypes.QR, RAW)
auto.save("qr_auto.png")

# Manually Set Modes per Segment.
builder = QrExtCodetextBuilder()
builder.add_codetext_with_compaction_mode(QrExtCompactionMode.NUMERIC, "1234567")
builder.add_codetext_with_compaction_mode(QrExtCompactionMode.ALPHA_NUMERIC, "ASPOSE2026")
builder.add_codetext_with_compaction_mode(QrExtCompactionMode.BYTES, "aspose2026")

manual = BarcodeGenerator(EncodeTypes.QR, builder.get_extended_codetext())
manual.parameters.barcode.qr.encode_mode = QREncodeMode.EXTENDED
manual.save("qr_manual.png")

print("Compare qr_auto.png and qr_manual.png — count modules along one edge.")

Conte os módulos ao longo de uma borda de cada imagem. Um símbolo QR da versão n tem 17 + 4n módulos quadrados, portanto a versão 2 é 25×25 e a versão 3 é 29×29. Se ambos caírem na mesma versão, a análise automática já encontrou a segmentação ideal e definir o modo manualmente era um fardo de manutenção sem ganho. Descobrir isso antes do envio é um resultado útil, não um passo desperdiçado.

Obtenha uma Licença Gratuita

Aspose oferece uma licença temporária gratuita que remove as restrições de avaliação e desbloqueia toda a funcionalidade para testes. Solicite uma na página de licença temporária da Aspose e aplique‑a antes de qualquer chamada de geração ou reconhecimento.

Recursos Adicionais Gratuitos

• Documentação do Produto
• Referência da API
• Aplicativos Online Gratuitos de Código de Barras

Conclusão

Configurar os modos de codificação de QR code em Python se resume a duas perguntas: qual segmento recebe qual modo e como você informa ao gerador para respeitar essa escolha. QrExtCodetextBuilder e QrExtCompactionMode respondem à primeira pergunta no código da aplicação; QREncodeMode.EXTENDED responde à segunda no gerador. Este guia abordou tanto a API do builder quanto a sintaxe do seletor inline que ele produz, gerando um símbolo QR de quatro segmentos, verificando a carga útil decodificada e medindo a diferença de tamanho em relação ao modo automático.

Prefira o construtor para o código da aplicação — ele captura erros de modo no local de chamada em vez de no scanner. E mantenha a etapa de medição. Definir o modo manualmente é uma verdadeira vantagem em cargas úteis homogêneas longas e uma perda líquida em curtas e misturadas, onde a sobrecarga de troca de modo supera a economia. Gere ambos, compare as contagens de módulos e deixe o resultado decidir qual código você mantém.

Perguntas Frequentes

1. O que é um modo de codificação de QR code e por que eu usaria um? Um modo de codificação informa ao gerador de QR como tratar um segmento de dados — numérico, alfanumérico, byte ou Kanji. Cada modo tem uma densidade de dados diferente, portanto escolher o correto por segmento mantém a versão do QR, e assim o símbolo, o menor possível. Aspose.BarCode chama esses modos de compactação; a especificação QR os chama de modos de codificação.

2. Quais modos de codificação o QrExtCompactionMode suporta? QrExtCompactionMode fornece NUMERIC, ALPHA_NUMERIC, BYTES e KANJI, correspondendo aos quatro modos de dados QR definidos na ISO/IEC 18004.

3. Devo usar QrExtCodetextBuilder ou seletores EXTENDED inline para definir o modo?
   Use o builder para código de aplicação. Ele é verificado em tempo de compilação, evita erros de escape de barra invertida e monta o codetext estendido para você. Seletores inline são úteis quando o codetext vem de configuração, de um banco de dados ou de outro sistema que não pode chamar o builder.

4. Como o modo de codificação EXTENDED difere do modo de codificação QR padrão? O modo EXTENDED faz com que o gerador leia o texto do código como uma série de segmentos pré-definidos, cada um com seu próprio modo de codificação, em vez de executar a detecção automática de modo em toda a string.

5. Posso definir diferentes modos de codificação para diferentes partes de um QR code? Sim. Adicione vários segmentos ao QrExtCodetextBuilder, cada um com um QrExtCompactionMode diferente, e o construtor produz um único codetexto estendido que cobre todos eles.

6. Um código QR gerado com modos de codificação mistos é compatível com leitores padrão? Sim. A codificação de múltiplos segmentos faz parte da especificação QR, portanto qualquer scanner compatível decodifica a carga útil corretamente e retorna os dados concatenados.

7. Definir o modo de codificação manualmente sempre produz um QR code menor? Não. Cada limite de segmento custa um indicador de modo e um campo de contagem de caracteres, portanto dividir os dados em muitos segmentos curtos pode tornar o símbolo maior. A seleção manual do modo compensa em sequências longas e homogêneas de dados numéricos ou Kanji.

8. Preciso de uma licença para definir modos de codificação QR com QrExtCodetextBuilder? Você pode avaliar a API sem uma licença, sujeito a restrições de avaliação. Uma licença temporária gratuita do site da Aspose remove essas restrições durante os testes, e o uso em produção requer uma licença completa.

9. Qual versão do Aspose.BarCode for python-net suporta essas APIs?
   QrExtCodetextBuilder, QrExtCompactionMode e QREncodeMode.EXTENDED estão disponíveis no Aspose.BarCode for Python via .NET 26.6 e posteriores.

Leia Mais

• Gerar código de barras MaxiCode em Python
• Construir gerador de código de barras Code 93 em Python
• Gerar código de barras e QR Code com logotipo em Python