قوالب الطابعات الحرارية

تستخدم القوالب الحرارية تنسيق XML ينتج معاينة على الشاشة وأوامر طابعة ESC/POS من القالب نفسه. وهي تستخدم العناصر النائبة نفسها {{variable}} مثل قوالب HTML لربط البيانات.

اختر هذا المحرك إذا كانت لديك طابعة إيصالات متصلة عبر إعداد الطابعة.

عناصر XML

العنصر الجذر

يبدأ كل قالب حراري بـ <receipt> كجذر:

<receipt paper-width="48">
  <!-- 48 characters = 80mm paper -->
  <!-- 32 characters = 58mm paper -->
</receipt>

النص والتنسيق

<text>Plain text</text>
<bold>Bold text</bold>
<underline>Underlined text</underline>
<invert>Inverted (white on black)</invert>

المحاذاة

<align mode="left">Left aligned</align>
<align mode="center">Centered</align>
<align mode="right">Right aligned</align>

حجم النص

عدّل مقياس عرض النص وارتفاعه بشكل مستقل:

<size width="2" height="2">Double-size text</size>
<size width="2" height="1">Wide text</size>
<size width="1" height="2">Tall text</size>

تخطيط جدولي

استخدم <row> و <col> للأعمدة المتراصفة:

<row>
  <col width="24">Item name</col>
  <col width="8" align="right">Qty</col>
  <col width="16" align="right">Price</col>
</row>

تُقاس عروض الأعمدة بعدد الأحرف. استخدم width="*" لعمود مرن يمتص المساحة المتبقية — وهذا يجعل القوالب تعمل عبر عروض ورق مختلفة دون تعديل:

<row>
  <col width="*">{{name}}</col>
  <col width="12" align="right">{{line_total_display}}</col>
</row>

الفواصل والتباعد

<line />                       <!-- Default single rule -->
<line style="double" />        <!-- Printer-native double rule -->
<line style="dashed" />        <!-- Character dashes across the width -->
<line style="dotted" />        <!-- Character dots across the width -->
<feed lines="2" />             <!-- Blank lines -->

<line/> (أو style="single") و style="double" يطبعان خط الفصل الأصلي للطابعة. dashed و dotted تطبع فواصل قائمة على الأحرف عبر عرض العمود النشط — وهي مفيدة عندما تحتاج إلى فاصل مرئي يبقى واضحًا في لقطة شاشة لمعاينة حرارية.

أوامر الطابعة

<cut />              <!-- Full paper cut -->
<cut mode="partial" /> <!-- Partial cut (leaves a tab) -->
<drawer />           <!-- Open cash drawer -->

الرموز الشريطية ورموز QR

<barcode type="code128" height="40">{{order.number}}</barcode>
<barcode type="qrcode" scale="3">{{fiscal.qr_payload}}</barcode>

مثال: إيصال بسيط بعرض 80mm

<receipt paper-width="48">
  <align mode="center">
    <size width="2" height="2">{{store.name}}</size>
  </align>
  <feed lines="1" />
  <align mode="center">
    <text>{{store.address_1}}</text>
    <text>{{store.city}} {{store.state}} {{store.postcode}}</text>
    {{#store.phone}}<text>{{store.phone}}</text>{{/store.phone}}
  </align>
  <line />

  <text>Order: #{{order.number}}</text>
  <text>Date: {{order.created.datetime}}</text>
  {{#cashier.name}}<text>Cashier: {{cashier.name}}</text>{{/cashier.name}}
  <line />

  <!-- Column headers -->
  <row>
    <col width="*"><bold>Item</bold></col>
    <col width="4" align="right"><bold>Qty</bold></col>
    <col width="12" align="right"><bold>Total</bold></col>
  </row>
  <line />

  <!-- Line items -->
  {{#lines}}
  <row>
    <col width="*">{{name}}</col>
    <col width="4" align="right">{{qty}}</col>
    <col width="12" align="right">{{line_total_display}}</col>
  </row>
  {{/lines}}

  <line />

  <!-- Totals -->
  <row>
    <col width="*">Subtotal</col>
    <col width="16" align="right">{{totals.subtotal_display}}</col>
  </row>
  {{#totals.tax_total}}
  <row>
    <col width="*">Tax</col>
    <col width="16" align="right">{{totals.tax_total_display}}</col>
  </row>
  {{/totals.tax_total}}
  <row>
    <col width="*"><bold>TOTAL</bold></col>
    <col width="16" align="right"><bold>{{totals.total_display}}</bold></col>
  </row>

  <line />

  {{#payments}}
  <row>
    <col width="*">{{method_title}}</col>
    <col width="16" align="right">{{amount_display}}</col>
  </row>
  {{#tendered}}
  <row>
    <col width="*">Tendered</col>
    <col width="16" align="right">{{tendered_display}}</col>
  </row>
  <row>
    <col width="*">Change</col>
    <col width="16" align="right">{{change_display}}</col>
  </row>
  {{/tendered}}
  {{/payments}}

  <feed lines="2" />
  <align mode="center">
    <text>Thank you for your purchase!</text>
  </align>
  <feed lines="3" />
  <cut />
</receipt>

أعمدة بعرض النجمة

تجعل ميزة width="*" القوالب غير مرتبطة بعرض ورق محدد. بدلا من تثبيت عروض الأعمدة لحجم ورق معين، استخدم * للعمود الذي ينبغي أن يتمدد:

<!-- Works on 58mm (32 char) AND 80mm (48 char) printers -->
<row>
  <col width="*">{{name}}</col>
  <col width="10" align="right">{{line_total_display}}</col>
</row>

على طابعة 80mm (48 حرفا)، يحصل اسم العنصر على 38 حرفا. وعلى طابعة 58mm (32 حرفا)، يحصل على 22 حرفا. تبقى الأعمدة الثابتة بالحجم نفسه على كلتيهما.

معاينة القالب

يعرض محرر القوالب معاينة حرارية مباشرة أثناء التحرير. تعرض المعاينة XML الخاص بك كـ HTML أحادي المسافة ومنسق، بما يحاكي شكل الإيصال على الورق. يتم تحديث التغييرات بعد تأخير قصير (مع تأجيل التنفيذ إلى 300ms).

ينتج القالب نفسه كلا من المعاينة ومخرجات طابعة ESC/POS، ولا يوجد قالب "طباعة" منفصل. تظهر الرموز الشريطية ورموز QR كرسومات SVG مضمنة في المعاينة، وكأوامر ESC/POS أصلية (أو صور نقطية) على الطابعة.

نصائح التأليف والمزالق

للطباعة الحرارية بعض المزالق التي لا توجد في HTML. هذه هي أكثر المزالق التي يواجهها مؤلفو القوالب.

لفّ العناوين المنسقة داخل <text> لإدراج فاصل أسطر

حاويات منسقة — <bold>, <size>, <underline>, <align> — لا تُنتج فاصل سطر بمفردها. فقط <text> والعناصر الكتلية (<line/>, <row>, <feed>) تفعل ذلك.

<!-- ❌ Bug: the heading runs together with whatever follows -->
<bold>{{i18n.bill_to}}</bold>
{{customer.name}}

<!-- ✅ Fix: wrap the inner content in <text> -->
<bold><text>{{i18n.bill_to}}</text></bold>
<text>{{customer.name}}</text>

تستخدم قوالب المعرض المرفقة بحجم 80mm هذا النمط لكل عنوان.

تجنب استخدام <size width="2"> داخل الصفوف الضيقة

النص مزدوج العرض يضاعف عدد الأحرف الفعلي. قد يتجاوز عنوان يتناسب مع طابعة 80mm السطر على طابعة 80mm عامة بعرض 42 عمودًا، وعلى ورق 58mm لا يترك سوى 16 حرفًا.

بالنسبة إلى القيم البارزة (الإجماليات الكبيرة، أرقام طلبات المطبخ)، أخرِج سطرًا مستقلًا بمقياس مكبّر بدلًا من التفافه داخل تخطيط متعدد الأعمدة <row>:

<!-- For store names, prefer normal-width, double-height -->
<bold><size height="2"><text>{{store.name}}</text></size></bold>

<!-- For a bold total, put it on its own line above the row -->
<align mode="right">
  <bold><size height="2"><text>{{totals.total_display}}</text></size></bold>
</align>

استخدم width="*" للتخطيطات غير المرتبطة بعرض ورق محدد

يمتص عمود width="*" (النجمة) العرض المتبقي بعد الأعمدة ذات العرض الثابت. وبذلك يُعرَض القالب نفسه بشكل صحيح على طابعات 32 عمودًا (58mm)، و42 عمودًا (قياسي 80mm)، و48 عمودًا (80mm عريض) بدون تعديل:

<!-- Works on 58mm AND 80mm without changes -->
<row>
  <col width="*">{{name}}</col>
  <col width="10" align="right">{{line_total_display}}</col>
</row>

إذا استخدمت عروضًا رقمية ثابتة، فاجعل ميزانيتها 42، وليس 48. الصفوف التي يبلغ مجموعها 48 ستلتف على طابعات 80mm الشائعة ذات 42 عمودًا.

عناوين منسقة ومتمركزة داخل كتل <align>

داخل <align mode="center"> (أو right)، عنوان منسق مباشر — <bold>, <size>, <underline>, <invert> موضوعًا مباشرةً داخل <align> — متبوعًا بسطر آخر، يُغلق تلقائيًا في سطر مستقل. يُطبع اسم المتجر المحاذى في الوسط والمكبّر فوق سطر العنوان المحاذى في الوسط بشكل واضح حتى من دون <text> الالتفاف.

خارج كتلة المحاذاة، أبقِ <text> الالتفاف.

توحيد علامات الترقيم في ESC/POS

عندما تكون لغة الطابعة ESC/POS، يقوم المُرمِّز بتوحيد علامات الترقيم الطباعية إلى ASCII آمن قبل الكتابة:

• الشرطة القصيرة، والشرطة الطويلة، وشرطة الأرقام، وعلامة الناقص في Unicode → -
• علامات الاقتباس المنحنية → علامات اقتباس مستقيمة
• المسافة غير الفاصلة → مسافة عادية

لذلك تُطبع Mon–Sat 9:00–18:00 وتُطبع "open" بشكل صحيح حتى على الطابعات التي لا تحتوي على خط Unicode. طابعات Star (star-line / star-prnt) تحافظ على التنسيق الطباعي الأصلي، لذا استخدم أحرفًا يدعمها خط الطابعة.

الخطوط غير اللاتينية ومن اليمين إلى اليسار

تطبع الطابعات الحرارية النص باستخدام خط وصفحة رموز مدمجين، لذلك لا تُطبع العربية والعبرية والفارسية والأردية وغيرها من النصوص غير اللاتينية بشكل صحيح إلا إذا ضُبطت الطابعة على صفحة رموز مطابقة (مثل CP864 / Windows-1256 للعربية) — وإلا فستظهر فراغات أو أحرف مشوهة.

النهج الموثوق لهذه النصوص هو تنقيط الإيصال بالكامل، إذ يعرض الإيصال كاملا كصورة بحيث يُطبع تماما كما صُمم، بغض النظر عن الخطوط المدمجة في الطابعة. راجع إعداد الطابعة لتفعيل وضع التنقيط.

تحتاج الأجهزة الحرارية إلى قالب حراري

لا تستطيع الطابعة الحرارية طباعة قالب HTML بصفحة كاملة — يجب تحويل المهمة إلى أوامر ESC/POS أو Star، وهو ما لا يستطيع HTML التعبير عنه. استخدم قالبا حراريا للأجهزة الحرارية؛ أما لطباعة HTML بصفحة كاملة بحجم A4/Letter، فاطبع إلى طابعة النظام/PDF أو عبر PrintNode.

الشعارات والصور

استخدم <image> لتضمين شعار:

<align mode="center">
  <image src="data:image/png;base64,..." />
</align>

يحوّل WCPOS الصور إلى صور نقطية على العميل — من فك الترميز، وتسطيح الشفافية إلى الأبيض، وتغيير الحجم ليناسب ميزانية نقاط الطابعة، والتحويل إلى أحادي اللون (تدرج Atkinson النقطي للشعارات، والعتبة للرموز الشريطية) — ثم يرسل أوامر صور ESC/POS أو Star.

• ميزانيات النقاط: عرض 384 نقطة لـ 58mm، وعرض 576 نقطة لـ 80mm.
• المصادر المقبولة: عناوين URL للبيانات data:image/png و data:image/jpeg، وعناوين URL مطلقة بتنسيق http(s)، ومسارات نسبية إلى الجذر من نفس المصدر. تُرفض // النسبية إلى البروتوكول، والشرطات المائلة العكسية، واجتياز المسار .. المرمز بنسبة مئوية.
• التنسيق الموصى به: PNG عالي التباين بخلفية شفافة أو بيضاء. يعمل JPEG، لكن آثار الضغط قد تُطبع كتشويش.
• SVG غير مدعوم بعد للإخراج الحراري الخام.

نصائح

• ابدأ بقالب من المعرض — تستخدم القوالب الحرارية في المعرض جميع الأنماط المذكورة أعلاه، وقد تم التحقق منها مع طابعات حقيقية.
• اختبر مقاسي الورق كليهما إذا كانت متاجرك تستخدم طابعات مختلفة، أو التزم بأعمدة width="*".
• استخدم حقول _display للعملة — فهي تراعي الإعدادات المحلية بالفعل.
• أبقِه بسيطًا — تحتوي القوالب الحرارية على أدوات تنسيق أقل من HTML بحكم التصميم. اعتمد على <row> + <col width="*"> ودع الطابعة تؤدي عملها.