Как генерировать и встраивать QR-коды

Вам нужно добавить QR-код в ваше веб-приложение. Возможно, это для процесса оплаты, ссылки для совместного доступа или электронных билетов на мероприятие. Вопрос не в том, использовать ли QR-код, а в том, как надёжно сгенерировать его в браузере, не создавая проблем со сканированием или безопасностью.

В этой статье рассматривается клиентская генерация QR-кодов на JavaScript, объясняется, когда использовать вывод в формате SVG, а когда Canvas, и рассматриваются практические ограничения, влияющие на надёжность сканирования.

Понимание разницы между генерацией и сканированием QR-кодов

Прежде чем писать код, различайте две отдельные задачи: генерацию и сканирование.

Генерация происходит полностью под вашим контролем. Вы кодируете данные в изображение QR-кода с помощью JavaScript-библиотек. Это работает надёжно во всех современных браузерах.

Сканирование — другое дело. Нативные браузерные API для чтения QR-кодов (например, Barcode Detection API) остаются экспериментальными и не имеют универсальной поддержки. Если вашему приложению требуется сканирование, планируйте запасные варианты — обычно это JavaScript-библиотека на основе камеры или поля для ручного ввода.

Эта статья посвящена генерации. Не смешивайте эти две задачи при планировании реализации.

Как генерировать QR-коды на JavaScript

Несколько JavaScript-библиотек обрабатывают генерацию QR-кодов для фронтенд-разработки. Распространённые варианты включают qrcode, которая поддерживает генерацию как на клиенте, так и на сервере, qrcode-generator — лёгкий кодировщик на чистом JavaScript, и более старую, но всё ещё широко используемую QRCode.js для простого вывода в Canvas или DOM. Ни одна из них не является “стандартом” — каждая имеет компромиссы в размере бандла, форматах вывода и опциях кастомизации.

Общий паттерн выглядит так:

1. Импортируйте выбранную библиотеку
2. Передайте данные, которые хотите закодировать (URL, текст, данные vCard)
3. Укажите формат вывода и размеры
4. Отрендерите в DOM-элемент или извлеките как data URL

Большинство библиотек принимают настройки для уровней коррекции ошибок (L, M, Q, H). Более высокие уровни позволяют большей части кода быть повреждённой, оставаясь при этом сканируемой — полезно, если вы планируете наложить логотипы или печатать на текстурированных поверхностях.

QR-коды: SVG против Canvas

При встраивании QR-кодов в веб вы обычно выбираете между тремя форматами вывода: SVG, Canvas или PNG/data URL.

Вывод в SVG

SVG обычно является лучшим выбором для веб-встраивания. Векторный формат масштабируется бесконечно без пикселизации, что делает его идеальным для адаптивных макетов и печатных приложений. Размеры файлов остаются небольшими независимо от размеров отображения. CSS-стилизация работает естественно.

Используйте SVG, когда:

• QR-код отображается в разных размерах
• Важно качество печати
• Вам нужна стилизация или анимация на основе CSS

Вывод в Canvas

Canvas рендерит в растровое изображение с определённым разрешением. Это хорошо работает, когда вам нужен контроль на уровне пикселей или вы планируете программно компоновать QR-код с другой графикой.

Используйте Canvas, когда:

• Вы генерируете изображения для скачивания
• Вам нужно напрямую манипулировать пикселями
• Вы интегрируетесь с другой графикой на основе Canvas

PNG/Data URL

Data URL позволяют встраивать QR-код как строку изображения в кодировке base64. Это устраняет дополнительные HTTP-запросы, но увеличивает размер HTML-полезной нагрузки. Полезно для email-шаблонов или контекстов, где внешние ресурсы ненадёжны.

Практические ограничения, влияющие на надёжность сканирования

QR-код, который выглядит правильно, всё равно может не сканироваться. Обратите внимание на эти проблемы:

Тихие зоны: QR-кодам требуется пустое пространство вокруг границ — обычно шириной в четыре модуля. Обрезка этого поля нарушает сканирование.

Контраст: Спецификация предполагает тёмные модули на светлом фоне. Инвертированные цвета или комбинации с низким контрастом снижают надёжность. Стремитесь к соотношению контрастности не менее 4:1.

Размер: Минимальный сканируемый размер зависит от расстояния просмотра и качества камеры. Для отображения на экране меньшие размеры могут работать на современных устройствах, но результаты зависят от расстояния просмотра и качества камеры. Для печати рассчитывайте на основе ожидаемого расстояния сканирования.

Наложение логотипов и сильная стилизация: Добавление логотипов в центр использует коррекцию ошибок — сканер воспринимает логотип как повреждение и восстанавливает данные. Это работает только с более высокими уровнями коррекции ошибок (Q или H), и агрессивная стилизация может превысить восстанавливаемые пределы. Тщательно тестируйте.

Соображения безопасности и UX

QR-коды, кодирующие URL, создают возможности для фишинга. Пользователи не могут проверить назначение перед сканированием. Если ваше приложение генерирует QR-коды из пользовательского ввода, валидируйте и санитизируйте этот ввод. Рассмотрите возможность отображения закодированного URL в виде видимого текста рядом с кодом.

Для доступности всегда предоставляйте закодированную информацию в альтернативном формате. Видимая ссылка рядом с QR-кодом обслуживает пользователей, которые не могут или не хотят сканировать.

Серверная генерация

Хотя эта статья фокусируется на клиентских подходах, серверная генерация имеет законные применения: уменьшение размера клиентского бандла, кэширование сгенерированных кодов или генерация кодов в средах без JavaScript. Библиотеки существуют для Node.js, Python, Go и большинства других бэкенд-языков. Соображения по формату вывода остаются теми же.

Заключение

Техническая реализация генерации QR-кодов проста. Используйте проверенные JavaScript-библиотеки, а не создавайте логику кодирования с нуля. Выбирайте SVG для масштабируемого веб-встраивания и Canvas для программной обработки изображений. Надёжность ваших QR-кодов зависит от соблюдения ограничений: поддерживайте тихие зоны, обеспечивайте правильный контраст и тестируйте на реальных устройствах сканирования. Всегда предоставляйте видимые альтернативы как для доступности, так и для целей безопасности.

Часто задаваемые вопросы

Understand every bug

Uncover frustrations, understand bugs and fix slowdowns like never before with OpenReplay — the open-source session replay tool for developers. Self-host it in minutes, and have complete control over your customer data. Check our GitHub repo and join the thousands of developers in our community.