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, orientamento N (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.

  • ^FS dimenticato: i comandi successivi vengono "mangiati" dal campo precedente e l'etichetta esce vuota o disallineata.
  • Coordinate fuori dall'area di stampa: con ^PW812 ma ^FO900,... l'elemento non viene stampato. Verifica sempre i valori contro ^PW e ^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 ^CI28 all'inizio dell'etichetta. Aggiungilo subito dopo ^XA.
  • Barcode che non scansiona: spesso la quiet zone (margine bianco intorno) è insufficiente. Aumenta il ^FO o riduci la larghezza modulo.

Risorse esterne