Este guia ensina como gerar um QR Code com Canvas no navegador usando JavaScript, desde a configuração até a exportação e boas práticas de design. Você vai criar códigos QR totalmente personalizáveis e prontos para uso em projetos web.
O que é um QR Code renderizado em Canvas
Canvas é uma superfície de desenho HTML5 que permite renderizar gráficos, incluindo QR Codes, de forma dinâmica. Diferente de bibliotecas que geram imagens estáticas, com Canvas você tem controle total sobre pixels, cores, integridade do código e responsividade, ideal para aplicações modernas e interfaces customizadas.
Configuração inicial do ambiente
- Use um servidor web local (Live Server no VS Code, por exemplo) para evitar restrições de segurança de arquivos locais.
- Inclua um elemento <canvas> no HTML com id único e dimensões adequadas ao layout.
- Carregue uma biblioteca leve para geração de QR Code (como qrcode ou QrCodeStyling) ou use a API nativa com algoritmo personalizado.
Estrutura básica do HTML e do Canvas
- Crie um arquivo index.html com meta tags de charset e viewport para responsividade.
- Insira um elemento <canvas id="qr"></canvas> e controles opcionais como inputs para texto, cores e botão de exportar.
- Referencie no final do body o script JavaScript que conectará Canvas e lógica de QR Code.
Geração do QR Code com JavaScript no Canvas
- Recupere o contexto 2D do Canvas com getContext('2d') e limpe a área antes de desenhar.
- Use a biblioteca ou implementação para codificar o texto de entrada em matriz de módulos QR.
- Itere pelos módulos e desenhe quadrados (ou pixels) no Canvas com fillRect, aplicando cor de fundo e cor do código.
- Ajuste o tamanho dos módulos (tamanho do ponto) e margem (quiet zone) para garantir a legibilidade do QR Code.
Personalização e design do QR Code
Além do preto e branco padrão, você pode aplicar gradientes, imagens centralizadas (como um logo), bordas arredondadas ou mascaramento de módulos. O segredo está em manter a área de dados clara e contrastante, obedecendo aos padrões de correção de erro escolhidos (L, M, Q, H).
Validação e testes de escaneabilidade
- Teste o QR Code com diferentes leitores (celulares Android, iOS, apps de terceiros) em condições de iluminação variadas.
- Use ferramentas de validação online ou scripts que verificam se o código pode ser decodificado e corrige falhas de posicionamento.
- Evite sobrepor elementos críticos aos blocos de posicionamento (quiet zones) e mantenha taxa de erro compatível com o nível de correção selecionado.
Exportação e uso em produção
Converta o Canvas para PNG ou JPEG com toDataURL('image/png') e ofereça botões de download. Em produção, combine cache, responsividade (redimensionar o Canvas para alta densidade) e fallback para navegadores mais antigos sem suporte a Canvas.
Dicas comuns e armadilhas de implementação
- Não redimensione a imagem do Canvas via CSS sem ajustar a resolução interna; isso desfoca os pixels e prejudica a leitura.
- Evite codificar textos muito longos sem ajustar o nível de correção de erro; isso aumenta a densidade e pode travar leitores simples.
- Sempre valide a entrada do usuário para evitar caracteres inválidos e ataques de injeção ao montar a matriz de dados.
- Considere acessibilidade: forneça o texto codificado próximo ao QR Code e use contraste alto para garantir inclusão.
Perguntas frequentes
Posso gerar QR Code com Canvas apenas com JavaScript puro, sem bibliotecas?
Sim, é possível codificar os dados e desenhar no Canvas manualmente, mas bibliotecas aceleram o processo, cuidam da estrutura de dados e evitam erros de formatação.
Como garantir que o QR Code fique nítido em telas de alta densidade (Retina)?
Dimensione o Canvas internamente com scale(context, devicePixelRatio) e ajuste largura e altura para manter a mesma apresentação visual com mais pixels.
Qual nível de correção de erro devo usar ao gerar QR Code com Canvas?
Use 'M' para uso geral, 'H' para máxima resistência a danos ou 'Q' para ambientes com interferência moderada, sempre testando a leitura antes de colocar em produção.
Como posso centralizar um logo sem quebrar a leitura do QR Code feito em Canvas?
Desenhe o código primeiro, copie regiões de dados seguros e centralize um logo pequeno apenas nas áreas brancas, garantindo quiet zone e contraste ao seu redor.
