Guida introduttiva a ZPL
Guida introduttiva a ZPL
Cos'è ZPL
ZPL (Zebra Programming Language) è un linguaggio testuale per controllare stampanti termiche Zebra e compatibili. Un'etichetta ZPL non è altro che un blocco di testo: si apre con ^XA, si chiude con ^XZ, e in mezzo si dichiarano elementi grafici, testo, codici a barre.
Il vantaggio è che il "file" è leggibile, versionabile e modificabile a mano. Niente formato proprietario: basta un editor di testo per produrre un'etichetta pronta a stampare.
Hello world
^XA
^FO50,50^A0N,40,40^FDCiao Mondo^FS
^XZ
Questo è tutto. Inviato a una stampante Zebra (o a un viewer come Labelary), produce un'etichetta con la scritta "Ciao Mondo" in alto a sinistra.
Anatomia di un'etichetta
Riga per riga, l'esempio sopra significa:
^XA— start format: segnala l'inizio dell'etichetta. Tutto ciò che viene dopo fa parte dell'etichetta corrente.^FO50,50— field origin: posiziona l'elemento successivo a 50 dot dal margine sinistro e 50 dot dall'alto.^A0N,40,40— font: seleziona il font 0, orientamentoN(normale, non ruotato), altezza 40 dot, larghezza 40 dot.^FD— field data: introduce il contenuto del campo. Tutto ciò che segue fino a^FSè il testo da stampare.^FS— field separator: chiude il campo. Dimenticarlo è uno degli errori più comuni: il parser interpreta i comandi successivi come parte del dato.^XZ— end format: chiude l'etichetta.
Comandi essenziali
| Comando | Cosa fa |
|---|---|
^XA / ^XZ |
Apre / chiude il formato dell'etichetta |
^PW |
Larghezza area di stampa (dot) |
^LL |
Lunghezza etichetta (dot) |
^LH |
Sposta l'origine logica dell'etichetta |
^CI28 |
Imposta la codifica UTF-8 (indispensabile per accenti) |
^FO x,y |
Posiziona il prossimo elemento |
^A0N,h,w |
Font scalabile 0, altezza/larghezza in dot |
^FD ... ^FS |
Delimita il campo dati |
^BC |
Barcode Code 128 |
^BQ |
QR code |
^GB w,h,t |
Rettangolo o linea (width, height, thickness) |
^GF |
Bitmap in scala di grigi |
^FX |
Commento (ignorato dalla stampante) |
Sistema di coordinate
ZPL ragiona in dot (singoli punti di stampa), non in millimetri. La conversione dipende dalla risoluzione della stampante:
dot = mm * DPI / 25.4
Esempi pratici:
- 50 mm a 203 dpi ≈ 400 dot
- 50 mm a 300 dpi ≈ 591 dot
- 100 mm a 203 dpi ≈ 800 dot
L'origine (0,0) è l'angolo in alto a sinistra. Una stampante a 203 dpi con etichette da 4 pollici ha tipicamente ^PW812.
Placeholder dinamici
In ZPL Archive usiamo la notazione {{nome}} per i campi sostituibili al volo. Esempio di un'etichetta di spedizione parametrica:
^XA
^CI28
^FO30,30^A0N,28,28^FDDestinatario:^FS
^FO30,70^A0N,36,36^FD{{customer_name}}^FS
^FO30,120^A0N,28,28^FDTracking:^FS
^FO30,160^BCN,80,Y,N,N^FD{{tracking_number}}^FS
^XZ
L'editor di personalizzazione legge i {{...}}, mostra un form con un campo per ciascuno e produce il ZPL finale con i valori sostituiti, prima di inviarlo alla stampante o all'anteprima.
Errori comuni
Capita a tutti, almeno una volta. Conviene impararli a riconoscere subito.
^FSdimenticato: i comandi successivi vengono "mangiati" dal campo precedente e l'etichetta esce vuota o disallineata.- Coordinate fuori dall'area di stampa: con
^PW812ma^FO900,...l'elemento non viene stampato. Verifica sempre i valori contro^PWe^LL. - Font non disponibile sulla stampante: il font
0è sempre presente, gli altri dipendono dal firmware. In caso di dubbio resta su^A0N. - Accenti che diventano
?o caratteri strani: manca^CI28all'inizio dell'etichetta. Aggiungilo subito dopo^XA. - Barcode che non scansiona: spesso la quiet zone (margine bianco intorno) è insufficiente. Aumenta il
^FOo riduci la larghezza modulo.
Risorse esterne
- Zebra ZPL Programming Guide (PDF ufficiale) — il manuale di riferimento completo.
- Labelary Viewer — renderizza ZPL in PNG/PDF online, comodissimo per iterare senza stampare.
- Zebra Developer Portal — documentazione, SDK, esempi.