サーマルプリンターテンプレート

サーマルテンプレートは XML 形式を使用し、同じテンプレートから画面プレビューと ESC/POS プリンターコマンドの両方を生成します。データバインディングには HTML テンプレート と同じ {{variable}} プレースホルダーを使います。

プリンター設定 からレシートプリンターを接続している場合は、このエンジンを選択してください。

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文字が割り当てられます。固定列の幅はどちらでも同じです。

旧 StarPRNT 固定レイアウトアダプターは削除されました

旧 StarPRNT 固定レイアウト出力アダプター は v1.10 で削除されました。これに依存するテンプレートは、現在のサーマルテンプレート（このページで説明する XML エンジン）に切り替えてください。共通のサーマルレイアウトを通じて Star 出力を生成します。 <row>および<col> と width="*" を使って、固定アダプターではなくレイアウトを再作成してください。

テンプレートのプレビュー

テンプレートエディターでは、編集中に サーマルプレビューをリアルタイム表示 します。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"> を避ける

倍幅のテキストは実効文字数が2倍になります。80mmプリンターでは収まる見出しでも、42桁対応の一般的な80mmプリンターでははみ出すことがあり、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="*"（star）列は、固定幅の列の後に残った幅を吸収します。同じテンプレートを変更せずに、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>

数値で幅を固定する場合は、48ではなく 42を基準に してください。合計48になる行は、一般的な42列の80mm プリンターで折り返されます。

<align> ブロック内の中央揃え見出し

配置ブロック <align mode="center"> （または right）では、スタイル付き見出し（ <bold>、 <size>、 <underline>、 <invert> ）を <align> 内に直接置いて次の行を続けると、見出しは自動的に独立した行として閉じられます。中央揃えの拡大店舗名の下に住所を中央揃えで配置すれば、明示的な <text> 折り返しを維持してください。

配置ブロックの外では、 <text> 折り返しを維持してください。

ESC/POS の句読点の正規化

プリンター言語が ESC/POS の場合、エンコーダーは書き込み前に印字用の句読点を安全な ASCII に正規化します。

• en ダッシュ、em ダッシュ、数字幅ダッシュ、Unicode のマイナス記号 → -
• 湾曲した引用符 → まっすぐな引用符
• ノーブレークスペース → 通常のスペース

そのため、Unicode フォントがないプリンターでも Mon–Sat 9:00–18:00 や "open" が正しく印刷されます。Star プリンター（star-line / star-prnt）では元の句読点が 保持される ため、プリンターのフォントでサポートされる文字を使用してください。

非ラテン文字と右から左に書く文字

サーマルプリンターは内蔵フォントとコードページを使って印刷するため、アラビア語、ヘブライ語、ペルシア語、ウルドゥー語などの非ラテン文字を正しく印刷するには、プリンターを対応するコードページ（例: アラビア語の場合は CP864 / Windows-1256）に設定する必要があります。設定しないと、何も印刷されないか、文字化けします。

これらの文字を確実に印刷するには、レシート全体を画像として描画する Full receipt raster が有効です。プリンター内蔵フォントに関係なく、設計どおりに印刷できます。ラスター モードを有効にする方法は プリンター設定 を参照してください。

サーマルプリンターにはサーマルテンプレートが必要です

サーマルプリンターはフルページの HTML テンプレートを印刷できません。ジョブは ESC/POS または Star コマンドに変換される必要があり、HTML ではそれを表現できません。サーマルハードウェアにはサーマルテンプレートを使ってください。A4/Letter のフルページ HTML は、システム/PDF プリンターまたは PrintNode 経由で印刷します。

ロゴと画像

ロゴを埋め込むには <image> を使います。

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

WCPOS はクライアント側で画像をラスター化します。デコードし、透明部分を白で平坦化し、プリンターのドット予算に合わせてリサイズし、モノクロに変換して（ロゴは Atkinson ディザリング、バーコードはしきい値処理）、ESC/POS または Star の画像コマンドを送信します。

• ドット予算: 58mm は幅 384 ドット、80mm は幅 576 ドット。
• 利用可能なソース: data:image/png と data:image/jpeg のデータ URL、絶対 http(s) URL、同一オリジンのルート相対パス。プロトコル相対 //、バックスラッシュ、パーセントエンコードされた .. トラバーサルは拒否されます。
• 推奨形式: 透明または白背景の高コントラスト PNG。JPEG も使えますが、圧縮ノイズが印刷に出ることがあります。
• SVG はまだ raw サーマル出力ではサポートされていません。

ヒント

• ギャラリーテンプレートから始める — ギャラリーのサーマルテンプレートは上記のパターンを使い、実機プリンターで検証されています。
• 店舗で異なるプリンターを使う場合は、両方の用紙サイズをテストするか、width="*" 列を使ってください。
• 通貨には _display フィールドを使ってください。すでにロケール対応済みです。
• シンプルに保つ — サーマル印刷は HTML より書式ツールが少ない設計です。 <row> + <col width="*"> を中心に使い、プリンターに任せてください。