# Struk ESC/POS 58mm di Flutter dengan esc_pos_utils

> Receipt builder yang bisa diuji untuk printer termal 58 mm di Dart: anggaran 32 kolom, grid 12 unit, lebar rupiah, kode QR, dan golden test.

URL: https://www.matthewswong.com/id/blog/flutter-escpos-receipt-builder-58mm/

- Author: Matthews Wong (https://www.matthewswong.com/id/about/)
- Published: 2026-08-18
- Updated: 2026-08-18
- Category: Software Development

> **Key takeaway:** Pada kertas 58 mm Anda mendapat sekitar 32 kolom Font A, dan esc_pos_utils_plus menyatakan tata letak sebagai baris berisi PosColumn dengan lebar yang totalnya 12. Membangun struk lewat kelas yang mengembalikan byte — dan tidak pernah menyentuh printer — membuat seluruh tata letak bisa diuji unit dengan golden byte fixture.

Bagian sulit dari pencetakan struk di Flutter bukan Bluetooth-nya. Yang sulit adalah struk merupakan masalah tata letak yang diselesaikan dengan aritmetika, di atas kanvas selebar sepertiga printer meja, dalam bahasa kolom alih-alih piksel. Salah aritmetika, dan setiap struk di toko itu miring secara halus.

Artikel ini membahas separuh pekerjaan yang berurusan dengan konten: bagaimana menyusun receipt builder di Dart agar mudah dibaca, dipakai ulang lintas ukuran kertas, dan bisa diuji tanpa perangkat keras terpasang.

## Anggaran kolom yang sebenarnya Anda belanjakan

Semuanya bermula dari lebar kertas. Gulungan 58 mm memberi sekitar 48 mm area cetak, yang pada sel karakter biasa menghasilkan sekitar 32 kolom di Font A dan sekitar 42 di Font B. Gulungan 80 mm memberi 72 mm, 48 kolom, dan 64 kolom. Angka-angka itu bukan saran gaya; itu ukuran kanvas Anda.

Generator meminta ukuran kertas alih-alih jumlah kolom lalu menurunkan sisanya, dan itu nyaman sampai ada yang memasukkan nilai keliru. Struk yang dibangun untuk 80 mm lalu dicetak di 58 mm tidak terpotong dengan cara yang kentara — ia diam-diam menjadi tidak sejajar, dengan nominal yang tidak lagi mendarat di margin kanan.

*Kanvas Anda, dalam satuan karakter. Panel ketiga adalah mode kegagalan yang layak dihafal: ukuran kertas yang salah tidak memotong apa pun, ia hanya menggeser setiap nominal menjauh dari margin kanan.*

## Builder yang mengembalikan byte dan tidak lebih

Refactor paling berguna dalam sebuah POS Flutter adalah memisahkan hal yang membangun struk dari hal yang mengirimkannya. Begitu builder-nya menjadi fungsi murni dari sebuah penjualan ke daftar bilangan bulat, Anda bisa mencetak ke berkas, membandingkannya dengan fixture, dan menjalankan seluruh tata letak di CI.

Perhatikan API baris. Lebar PosColumn selalu berjumlah dua belas, jadi baris nama-jumlah-nominal adalah pembagian 7-1-4 terlepas dari ukuran kertas, dan generator mengubah proporsi itu menjadi jumlah kolom sesungguhnya. Berpikir dalam per-dua-belas itulah yang membuat satu builder bisa melayani perangkat 58 mm dan 80 mm secara jujur.

> Berikan ukuran kertas sebagai argumen konstruktor builder dan buat instansnya per printer, bukan per aplikasi. Toko mencampur perangkat keras — unit 80 mm di meja dan portabel 58 mm untuk pengantaran — dan satu generator global adalah cara struk pengantaran berakhir tidak sejajar.

## Empat aturan menata struk 32 kolom

Bekerja di dalam 32 kolom benar-benar sempit. Empat aturan berikut bertahan di setiap tata letak yang pernah saya rilis.

- Pesan tempat untuk nominal lebih dulu. Hitung lebar angka yang sudah diformat, kurangi bersama satu spasi pemisah, lalu berikan sisanya untuk nama.
- Taruh kuantitas dan harga satuan di baris tersendiri di bawah nama ketika namanya panjang. Dua baris yang bersih lebih baik daripada satu baris terpotong.
- Jangan pernah merata-tengahkan teks badan. Rata tengah memakan kolom dan merusak kesejajaran vertikal yang membuat kolom nominal mudah dipindai.
- Gunakan garis selebar kertas untuk memisahkan blok, bukan baris kosong. Ia terbaca lebih jelas di kertas sempit dengan biaya tiga milimeter yang sama.

Satu-satunya pengecualian adalah header. Nama toko yang dirata-tengah dan berukuran ganda pantas memakan kolom karena itulah satu-satunya baris yang harus terbaca dari kejauhan.

## Format rupiah adalah fungsi tata letak

Format mata uang tampak seperti urusan tampilan padahal sebenarnya batasan pencetakan: lebar string-nya menentukan berapa banyak ruang yang tersisa untuk nama barang. Simpan satu fungsi, pakai untuk struk dan layar, dan perlakukan lebar keluarannya sebagai masukan bagi tata letak Anda.

Memformat di perangkat juga menghindari kegagalan halus yang sudah dua kali saya temui: server mengirim string nominal yang sudah diformat dengan spasi non-breaking atau simbol mata uang yang tidak bisa dirender code page printer. Kirim angka lewat jaringan, format di tepian.

> Jangan pernah membiarkan formatter yang sadar-locale memilih pemisah saat mencetak. Perangkat yang diatur ke bahasa Inggris menghasilkan pengelompokan berbeda dari yang diatur ke bahasa Indonesia, dan transaksi yang sama akan mencetak dua total yang tampak berbeda di dua kasir dalam satu toko. Kunci formatnya secara eksplisit.

*Apa yang menjadi keluaran builder Anda: pulsa di sepanjang sebaris resistor, satu baris sekali jalan. Setiap karakter adalah blok titik berukuran tetap, dan justru itulah sebabnya tata letak di sini adalah aritmetika kolom. Foto:*

## Kode QR, barcode, dan pertanyaan soal logo

Generator menyediakan kode QR dan barcode sebagai perintah printer native alih-alih gambar, dan itu penting di printer 58 mm bertenaga baterai: QR native cepat dan tajam, sementara kode yang sama dikirim sebagai bitmap menjadi lambat dan bergantung pada dithering Anda.

Logo raster adalah satu hal yang layak diperdebatkan dengan klien. Ia operasi paling lambat yang dilakukan printer, menguras baterai secara terukur, dan di kertas termal memudar lebih cepat daripada teks. Kalau toko bersikeras, cetak sekali di bagian atas, dalam gambar monokrom yang sudah disiapkan tepat pada lebar target, jangan pernah diskalakan saat runtime.

## Golden test: alasan menjaga byte tetap murni

Begitu builder mengembalikan byte, mengujinya menjadi sepele sekaligus sangat berharga. Fixture berisi daftar byte persis yang di-commit mengubah setiap perubahan tata letak yang tidak disengaja menjadi tes yang gagal, bukan keluhan dari toko tiga minggu kemudian.

Pasangkan golden test dengan beberapa pemeriksaan bergaya properti: nama produk terpanjang yang masuk akal tetap menyisakan nominal utuh, dan setiap baris tetap berada di dalam anggaran kolom. Dua tes itu menangkap lebih banyak cacat nyata bagi saya daripada sebanyak apa pun pencetakan manual.

Receipt builder adalah potongan kode yang kecil, murni, dan tersepesifikasi baik, dan memperlakukannya demikian yang membuat pencetakan termal jadi membosankan dalam arti positif. Jauhkan dari lapisan Bluetooth, berpikirlah dalam per-dua-belas, kunci format mata uang Anda, dan biarkan golden fixture menjaga tata letak yang Anda susun susah payah selama satu sore.

## Sumber dan bacaan lanjutan

- esc_pos_utils_plus di pub.dev (Generator, PosStyles, PosColumn)
- Epson ESC/POS Command Reference
- Dokumentasi python-escpos tentang code page dan magic encode
- print_bluetooth_thermal di pub.dev

## Source links

- https://pub.dev/packages/esc_pos_utils_plus
- https://reference.epson-biz.com/modules/ref_escpos/index.php
- https://python-escpos.readthedocs.io/en/latest/api/magicencode.html
- https://pub.dev/packages/print_bluetooth_thermal

## FAQ

### Berapa karakter yang muat di struk termal 58 mm?

Sekitar 32 kolom di Font A dan kira-kira 42 di Font B, karena gulungan 58 mm memberi sekitar 48 mm area cetak. Gulungan 80 mm memberi 72 mm, yaitu 48 dan 64 kolom. Angka-angka itu adalah ukuran kanvas Anda, dan setiap keputusan tata letak adalah aritmetika di dalamnya.

### Apa arti lebar PosColumn di esc_pos_utils_plus?

Lebar baris dinyatakan dalam per-dua-belas, jadi lebar kolom dalam satu baris harus berjumlah 12. Baris nama-jumlah-nominal biasanya berupa pembagian 7-1-4. Generator mengubah proporsi itu menjadi jumlah kolom sesungguhnya yang tersirat dari ukuran kertas, dan itulah yang membuat satu builder bisa melayani printer 58 mm dan 80 mm.

### Format mata uang sebaiknya di server atau di perangkat?

Kirim angka lewat jaringan dan format di perangkat, dengan format yang dikunci alih-alih formatter yang sadar-locale. Kalau tidak, perangkat berbahasa Inggris akan mengelompokkan digit berbeda dari perangkat berbahasa Indonesia sehingga mencetak dua total yang tampak berbeda untuk transaksi yang sama, dan string terformat dari server sering membawa karakter yang tidak bisa dirender code page printer.

### Kode QR di printer termal itu gambar atau perintah?

Keduanya mungkin, dan perintah native jauh lebih baik. esc_pos_utils_plus menyediakan helper qrcode dan barcode yang memancarkan perintah ESC/POS native, yang mencetak cepat dan tajam. Kode yang sama dikirim sebagai bitmap raster menjadi lambat, menguras printer baterai, dan bergantung pada dithering Anda.

### Bagaimana menguji tata letak struk tanpa printer?

Jadikan builder sebagai fungsi murni dari sebuah penjualan ke daftar byte, lalu commit daftar byte yang diharapkan sebagai golden fixture. Setiap perubahan tata letak atau encoding yang tidak disengaja menggagalkan tes alih-alih mengejutkan sebuah toko. Tambahkan pemeriksaan bergaya properti bahwa nama produk terpanjang yang masuk akal tetap menyisakan nominal utuh di dalam anggaran kolom.

---

- HTML version: https://www.matthewswong.com/id/blog/flutter-escpos-receipt-builder-58mm/
- English: https://www.matthewswong.com/en/blog/flutter-escpos-receipt-builder-58mm/
- Site index for agents: https://www.matthewswong.com/llms.txt
- Sitemap: https://www.matthewswong.com/sitemap.xml
- API description (OpenAPI): https://www.matthewswong.com/openapi.json
