Kod QR, który się zeskanuje: długość linku, margines, kontrast i test przed drukiem

Kod QR to siatka małych kwadratów, zwanych modułami. Skaner musi odróżnić każdy z nich od sąsiada. Wszystko, co zmniejsza moduły (długi link, wysoka korekcja błędów, mały wydruk) albo zaciera różnicę między jasnym a ciemnym (słabe kolory, brak marginesu), utrudnia odczyt. Poniżej kolejność, w jakiej warto to ustawić w generatorze kodów QR, razem z pomiarami na kodach wygenerowanych w tym narzędziu.

Jak przeprowadziliśmy pomiary

Kody generowaliśmy w prawdziwym generatorze (Chromium, pobrane pliki PNG i SVG) z syntetycznymi danymi: adresami w domenie example.com i fikcyjną wizytówką. Odczytywały je trzy czytniki: biblioteka jsQR w Node, czytnik kodów QR z natywnym detektorem przeglądarki (BarcodeDetector) i ten sam czytnik z wyłączonym detektorem, czyli wyłącznie na jsQR. Uszkodzenia (zasłonięty środek, tło plakatu, zmniejszenie, rozmycie z szumem) nakładaliśmy na pobrane pliki w programie sharp. To odczyt programowy z plików w Chromium na macOS, a nie test telefonów z aparatem i papierem.

1. Skróć treść, zanim zaczniesz ustawiać wygląd

Liczba modułów zależy od ilości danych. Więcej znaków oznacza gęstszy kod, a przy tym samym rozmiarze na papierze każdy moduł jest mniejszy. Tabela pokazuje, ile modułów na bok ma kod przy poziomie korekcji M (domyślnym w generatorze) i jak wygląda wielkość jednego modułu, gdy cały obraz kodu z marginesem 4 modułów ma na papierze 3 cm:

Treść kodu	Znaki	Moduły na bok	Moduł przy szerokości 3 cm
Link https://example.com/m	21	25	0,91 mm
Wi-Fi z nazwą i hasłem ze znakami specjalnymi	50	33	0,73 mm
Link https://example.com/sklep/kategoria/promocja-jesienna	53	33	0,73 mm
Ten sam link z parametrami UTM (utm_source, utm_medium, utm_campaign)	113	45	0,57 mm
Wizytówka vCard: imię i nazwisko, telefon, e-mail	119	45	0,57 mm
Wizytówka vCard z firmą, stanowiskiem, stroną i adresem	266	65	0,41 mm

Szerokość modułu to szerokość obrazu podzielona przez liczbę modułów z marginesem. W pierwszym wierszu jest to 25 + 2 × 4 = 33 moduły, czyli 30 mm : 33 = 0,91 mm. Przy tej samej szerokości 3 cm moduły pełnej wizytówki są ponad połowę mniejsze niż moduły krótkiego linku.

Co z tego wynika w praktyce:

• Kod na ulotkę niech prowadzi do jednej strony. Parametry UTM i ścieżki kilkupoziomowe skróć albo ustaw przekierowanie ze zwięzłego adresu, który kontrolujesz.
• Kody z generatora są statyczne: treść jest zapisana w obrazku, więc nie wygasają, ale też nie da się zmienić celu już wydrukowanego kodu. Link musi działać tak długo jak ulotka.
• Wizytówkę ogranicz do danych, których ktoś naprawdę potrzebuje przy pierwszym kontakcie. Resztę zostaw na stronie.

2. Korekcja błędów: kompromis między odpornością a gęstością

Generator oferuje cztery poziomy: L (7%), M (15%), Q (25%) i H (30%). Procenty oznaczają, jaką część słów kodowych kod potrafi odtworzyć, gdy jest zabrudzony lub uszkodzony (Denso Wave, opis korekcji błędów, sprawdzone w październiku 2026). Wyższy poziom dopisuje więcej danych nadmiarowych, więc ten sam tekst zajmuje więcej modułów:

Treść	L	M	Q	H
Link z 21 znaków	25	25	29	29
Link z 53 znaków	29	33	37	41
Link ze 113 znakami	41	45	53	57

(liczba modułów na bok)

Na wydruku w dobrych warunkach wystarczy L albo M. Wyższy poziom ma sens, gdy kod będzie się brudził, trzeba go będzie zaklejać fragmentami albo chcesz umieścić w nim logo. Generator HNarzędzi nie dodaje logo: musiałbyś nałożyć je w programie graficznym, więc zasłonięcie środka kodu to Twoja decyzja i Twoja odpowiedzialność.

Jak duże logo przeszło w teście

Na kodach z linkiem 53-znakowym (każdy poziom osobno, 1024 px, margines 4) zasłanialiśmy środek jednolitym kwadratem o boku podanym jako procent szerokości samego kodu i sprawdzaliśmy, czy czytniki dalej go odczytują. Kroki były co 5 punktów procentowych, a zasłonięty był jeden kwadrat w środku, nie prawdziwe logo.

Poziom	Największy kwadrat odczytany przez wszystkie trzy czytniki	Powierzchnia kodu	Pierwszy kwadrat, którego nie odczytano
L	20% boku	4%	25% boku
M	30% boku	9%	35% boku
Q	35% boku	12%	40% boku (natywny detektor jeszcze czytał)
H	40% boku	16%	45% boku (natywny detektor jeszcze czytał)

Granice wypadły niżej niż deklarowane 7, 15, 25 i 30%. Dlatego logo na środku zrób wyraźnie mniejsze niż wynik z tabeli, na przykład o boku 15-20% szerokości kodu, użyj poziomu Q albo H i sprawdź gotowy plik w czytniku (rozdział 7). Przy L granica wypadła już przy kwadracie o boku 25%.

3. Kontrast i kolory

Generator przelicza kontrast między kolorem kodu a tłem i pokazuje ostrzeżenie, gdy wynosi on mniej niż 3:1 albo oba kolory są takie same. Zmierzyliśmy kilka par na kodzie z linkiem 53-znakowym (512 px, margines 4, poziom M). „Pogorszony” plik to nasza symulacja słabego zdjęcia: obraz zmniejszony do 220 px, rozmyty, o obniżonym kontraście i z szumem.

Kolor kodu na tle	Kontrast	Ostrzeżenie generatora	Czytniki, które odczytały plik (z 3)	Po pogorszeniu (z 3)
czarny na białym	21:1	nie	3	3
granat #1e3a8a na białym	10,4:1	nie	3	3
szary #6b7280 na białym	4,8:1	nie	3	3
szary #9ca3af na białym	2,5:1	tak	2	3
jasnoszary #d1d5db na białym	1,5:1	tak	1	1
czerwony #dc2626 na zielonym #16a34a	1,5:1	tak	1	0
czarny na żółtym #fde047	15,9:1	nie	3	3
biały na czarnym (odwrócony)	21:1	tak (odwrócone kolory)	3	3

Kolorowy kod jest w porządku, jeśli jest wyraźnie ciemniejszy od tła. Przy kontraście 1,5:1 plik czytał najwyżej jeden czytnik. Przy 2,5:1 wynik zależał od czytnika i skali: ten sam plik jsQR w Node pominął, a po zmniejszeniu odczytał. Taki kod jest na granicy i nie warto drukować go na papierze.

Odwrócony kod (jasny na ciemnym) odczytały wszystkie trzy czytniki, bo czytnik w narzędziu próbuje obu polaryzacji. Tego, czy zrobi to każdy telefon i każdy skaner, nie sprawdzaliśmy. Generator ostrzega przy odwróconych kolorach. Trzymaj się ciemnego kodu na jasnym tle.

4. Margines (strefa ciszy)

Wokół kodu musi być wolne pole, na którym nic nie jest wydrukowane. Twórca formatu, firma Denso Wave, podaje szerokość czterech modułów z każdej strony (Denso Wave, zasady wyznaczania obszaru kodu, sprawdzone w październiku 2026). Jako typowy problem opisuje też napisy i obrazki zbyt blisko kodu (Denso Wave, przykłady problemów z odczytem).

Suwak „Margines” w generatorze liczy w modułach (0-10). Domyślnie jest ustawiony na 4, czyli wartość zalecaną przez Denso Wave, więc do druku możesz go zostawić.

W teście umieściliśmy kod (link 53-znakowy, M, 512 px) na plakacie z ciemnym tłem oraz na jasnym tle z czarnymi „linijkami tekstu” 0,5 modułu od krawędzi obrazu kodu:

Margines	Ciemne tło	Jasne tło z tekstem przy kodzie
0	odczytał tylko natywny detektor, oba warianty jsQR nie	wszystkie trzy
1	wszystkie trzy	wszystkie trzy
2	wszystkie trzy	wszystkie trzy
4	wszystkie trzy	wszystkie trzy

Czytniki są więc bardziej tolerancyjne niż standard, ale margines 0 na ciemnym tle już zawodził. Nie licz na tolerancję telefonu klienta. Biały margines zostaw jako część obrazka, nawet gdy plakat ma ciemne tło, i nie przycinaj go w programie graficznym.

5. Rozmiar wydruku i odległość

Skaner nie widzi całego kodu, tylko jego moduły, więc rozmiar modułu ma największe znaczenie. Denso Wave radzi drukować kod tak duży, jak pozwala miejsce, a drukarce dawać co najmniej 4 punkty na moduł (Denso Wave, dobór wielkości modułu, sprawdzone w październiku 2026). Przy 300 dpi 4 punkty to około 0,34 mm, więc granicą jest raczej aparat skanującego niż drukarka. Strona Denso Wave nie podaje odległości odczytu ani minimalnego rozmiaru kodu. Przy kamerach granica zależy od obiektywu i urządzenia.

Często powtarza się praktyczną zasadę 10:1 (kod o szerokości 1 cm ma być czytelny z ok. 10 cm) i minimum 2 × 2 cm (Bitly, artykuł o minimalnym rozmiarze kodu QR, sprawdzone w październiku 2026). Bitly podaje obie liczby jako orientacyjne i nie opisuje, na czym je oparł, więc traktuj je tylko jako punkt wyjścia. Według niej kod o szerokości 3 cm odpowiadałby odległości około 30 cm, a kod na plakacie oglądanym z 2 m powinien mieć około 20 cm.

Zasada nie uwzględnia gęstości kodu. Kod o szerokości 3 cm ma moduły 0,91 mm przy 25 modułach na bok i 0,41 mm przy 65 (tabela w rozdziale 1), a skaner czyta moduły. Dlatego najpierw skracaj treść, a rozmiar dobieraj do najgęstszego kodu, który naprawdę wydrukujesz. Ostateczny sprawdzian to skan z odległości, z której będą go robić Twoi odbiorcy.

6. PNG czy SVG do druku

Generator pobiera kod w PNG i SVG. Rozmiar ustawiony suwakiem „Rozmiar” (128-2048 px) dotyczy tylko PNG. Plik SVG zawiera wyłącznie viewBox, bez szerokości i wysokości, więc skaluje się do ramki w programie do składu. W naszym teście ten sam kod (link 53-znakowy, margines 4) miał w SVG 1976 B, a w PNG 512 px 9386 B.

• SVG po narysowaniu w 200 i 1200 px miał 0% pikseli w pośrednich odcieniach szarości i został odczytany przez wszystkie trzy czytniki.
• PNG 128 px rozciągnięty do 1200 px miał 16% pikseli w odcieniach szarości, czyli miękkie krawędzie modułów. Wszystkie trzy czytniki nadal go odczytały, ale krawędzie są już rozmyte, a w SVG ich nie ma.
• Zmniejszanie PNG w programie graficznym wypadło gorzej. Kod zmniejszony do 1,25 piksela na moduł (obraz 51 px) nie odczytał żaden czytnik, a przy 1,5 piksela (62 px) tylko natywny detektor. Przy 2 pikselach na moduł i więcej czytały wszystkie trzy czytniki, a 1 piksel na moduł zadziałał, bo obraz miał dokładnie tyle pikseli co modułów. Denso Wave również ostrzega, że powiększanie i zmniejszanie kodu w programie graficznym zniekształca moduły (Denso Wave, przykłady problemów z odczytem).

Do druku bierz więc SVG, a gdy program wymaga rastra, pobierz PNG o docelowej wielkości z generatora zamiast skalować go w edytorze. 3 cm przy 300 dpi to około 354 px, więc PNG 512 px daje zapas. Jeśli potrzebujesz konkretnej szerokości PNG, zamień SVG w narzędziu SVG na PNG i podaj „Szerokość (px)” będącą wielokrotnością liczby modułów z marginesem. Dla kodu z viewBox 41 × 41 to na przykład 820 px, czyli 20 pikseli na moduł.

7. Test przed drukiem

1. Wygeneruj kod z ostateczną treścią, marginesem 4 i poziomem korekcji dobranym do przypadku.

2. Pobierz plik i wczytaj go w czytniku kodów QR (zakładka „Z obrazu”). Czytnik pokazuje, co jest w kodzie, a przy linku też domenę. Porównaj tekst znak po znaku z zamierzonym.

   

3. Wydrukuj próbkę na tej samej drukarce i tym papierze, w rozmiarze docelowym. Zeskanuj ją co najmniej dwoma telefonami, z odległości, z jakiej będzie czytana na ulotce czy plakacie, i przy takim oświetleniu jak na miejscu. Sprawdź też, czy po wydruku nie zmienił się kontrast, czyli czy jasne pola nie zrobiły się szare od koloru papieru.

4. Otwórz adres z kodu na telefonie poza siecią Wi-Fi i sprawdź, czy strona się ładuje.

Wynik czytnika w przeglądarce zależy od przeglądarki: jeśli ma ona natywny detektor, narzędzie go używa, a w przeciwnym razie czyta biblioteką jsQR w kilku skalach. W naszym teście natywny detektor odczytał kilka plików, których jsQR nie odczytał: margines 0 na ciemnym tle, kontrast 1,5:1 i kod zmniejszony do 1,5 piksela na moduł. Plik, który odczytuje się tylko w jednej przeglądarce, uprość (krótszy link, większy margines i kontrast) i sprawdź ponownie.

8. Wi-Fi i wizytówka: znaki specjalne

Generator buduje poprawny tekst dla Wi-Fi i vCard, poprzedzając znaki specjalne ukośnikiem. W Wi-Fi to \ ; , : ", w vCard \ ; , i nowe linie. Przetestowaliśmy to na danych z takimi znakami:

• Sieć „Kawiarnia;Rynek:2” z hasłem ha;sło,"1\2 trafia do kodu jako WIFI:T:WPA;S:Kawiarnia\;Rynek\:2;P:ha\;sło\,\"1\\2;;. Czytnik pokazał nazwę i hasło dokładnie tak, jak je wpisaliśmy.
• Firma „Pracownia Nowak; Wspólnicy, Sp. z o.o.” trafia do pola ORG jako Pracownia Nowak\; Wspólnicy\, Sp. z o.o.. Czytnik odczytał ją z powrotem ze średnikiem i przecinkiem, a polskie litery w adresie (Łódź, Przykładowa) też były poprawne.

Bez ucieczki średnik w polu ORG byłby odczytany jako separator części pola, dlatego nie buduj takich tekstów ręcznie w polu „Tekst lub adres URL”. Wizytówka z pełnym zestawem pól ma 266 znaków i 65 modułów na bok. Ten kod w najmniejszej wielkości suwaka (128 px, około 1,75 piksela na moduł) odczytały oba warianty czytnika z narzędzia, ale pojedynczego przebiegu jsQR w Node już nie. Dla gęstej wizytówki wybierz więc większy plik.

Czego nie załatwi generator

• Nie dodaje logo ani nie zmienia kształtu modułów.
• Tworzy kody statyczne: bez liczenia skanów i bez zmiany celu po wydruku.
• Test w czytniku odczytuje plik, a nie obraz z aparatu telefonu. Nie zastępuje próby z wydrukiem.
• Kody kreskowe EAN do produktów w sklepach to inny format. Opisuje go poradnik Kod kreskowy EAN dla produktu.