帳票テンプレート

ここでは、帳票テンプレートの基本について解説します。あらかじめ、開発を始めるに従って開発環境のセットアップを完了させていることを推奨します。

帳票テンプレートの構成

帳票テンプレートは、以下の要素で構成されます。

レイアウトXML（必須 : 1個以上）
- 帳票のレイアウトや表示内容を定義するXMLです。
- 表紙・明細・裏表紙のように異なる複数のレイアウトを持たせることができます。
スタイルXML（任意 : 最大1個）
- スタイル定義を外部化・共通化するXMLです。
アセット（任意 : 0個以上）
- 帳票に埋め込む画像データ（ロゴ、印影など）と背景用のPDFです。
- 対応形式: PNG、JPEG、PDF

これらを1つのファイルにまとめたものが「帳票テンプレートファイル」です。このファイルの拡張子は .yrt としてください。

「帳票テンプレートファイル」のことを、文脈に応じて「帳票テンプレート」「YRTファイル」と記述することがありますが、基本的にはすべて同じものを指します。

レイアウトルール

yagisan-reportsには2つのレイアウトルールがあり、描画時は必ずどちらかルールに従ってレイアウトを行います。

リニアルール
- 上から下へずらしながら、順番に描画していきます。
スタックルール
- X/Y座標と幅/高さを指定して、絶対位置に描画します（いわゆる絶対配置）。
- 描画要素が重なった場合は、後から描画した要素が前面に表示されます（スタックの命名由来です）。

レイアウトの単位系

帳票テンプレートのレイアウト単位は、ミリメートル（mm） を基本としています。ただし、フォントサイズに限り、ポイント（pt） 指定となっています。

yagisan-reportsの内部的には、 1pt を 25.4 / 72 mm として扱っています。よって、 1mm ≒ 2.83pt、1pt ≒ 0.353mm となります。

XMLの構文

XMLはyagisan-reportsの帳票テンプレートを構成する中核要素です。開発作業でもXMLファイルの編集が中心となるため、yagisan-reportsにおけるXMLの取り扱いについて理解が必要です。

備考

yagisan-reportsのXML仕様は、W3CのXML 1.0勧告 (Fifth Edition) に準拠しています。ただし、日本語帳票に特化するため、一部を独自拡張をしたり、不要な仕様をサポート外にしたりしています。

文字エンコーディング

XMLファイルの文字エンコーディングは、UTF-8 でなくてはなりません。

XML 宣言

XMLファイルの先頭には、以下のようにXML宣言を記述しても構いません。ただし、yagisan-reportsはXML宣言を無視するため、基本的には記述不要です。

<?xml version="1.0" encoding="UTF-8"?>

以下の形式で、XMLファイル内にコメントを記述できます。

<!-- これはコメントです -->

実体参照

以下の実体参照をサポートしています。

実体参照	表示される文字
`&`	&
`<`	<
`>`	>
`"`	"
`'`	'

文字参照

以下のように、「10進数」または「16進数」で文字コードを指定する文字参照をサポートしています。

¥ （10進数指定）
¥ （16進数指定）

テキストコンテンツ

テキストコンテンツ（テキストノード）は、XML標準を拡張した独自仕様で取り扱います。

XML標準と同様に、以下のようにテキストコンテンツを記述できます。

<Text>Hello, yagisan-reports!</Text>

途中で改行を含むことも可能です。帳票エンジンは、改行はそのまま改行として認識します。

<Text>Hello,
yagisan-reports!</Text>

yagisan-reportsで特異な点は、マルチラインモードとインデントをサポートしているところです。

以下のように、「開始タグの後ろ」と「終了タグの前」で改行をして、複数行で記述することもできます。タグ内の文字列にインデントを付けて記述しても構いません。

<Text>
  Hello,
  yagisan-reports!
</Text>

帳票エンジンは、インデントを除去してテキストコンテンツを認識します。

Hello,
yagisan-reports!

インデントは一番左にある文字列の位置に合わせて認識されます。以下の例では4行目のテキストが一番左にあるため、これがインデントの基準位置として認識されています。

<Text>
    〒460-0012
      愛知県名古屋市中区
        千代田2-24-34
  デンキヤギ株式会社
</Text>

  〒460-0012
    愛知県名古屋市中区
      千代田2-24-34
デンキヤギ株式会社

4値を指定する属性

罫線や余白を設定する属性では、（上/下/左/右）の値を指定します。記述方法はCSSと同様で、1-4個の値をスペース区切りで指定します。

1値を指定 : 全四辺に同じ値を適用
2値を指定 : 1つ目は上下、2つ目は左右の辺に適用
3値を指定 : 1つ目は上、2つ目は左右、3つ目は下の辺に適用
4値を指定 : それぞれ上、右、下、左の順 (時計回り) に適用

<!-- 四辺すべてに適用 -->
<LinearBlock borderThickness="1" />

<!-- 上下、左右の順で適用 -->
<LinearBlock borderThickness="1 2" />

<!-- 上、左右、下の順で適用 -->
<LinearBlock borderThickness="1 2 3" />

<!-- 上、右、下、左の順で適用 -->
<LinearBlock borderThickness="1 2 3 4" />

値に _ を指定すると、値の指定を省略した（未指定とした）ことになります。

<!-- 下の値の指定を省略 -->
<LinearBlock borderThickness="1 2 _ 4" />

また、borderRadius などの四隅（左上/右上/右下/左下）を指定する属性も、CSSの記述方法と同様です。値に _ を記述して、指定の省略をすることもできます。

1値を指定 : 全四隅に同じ値を適用
2値を指定 : 1つ目は左上/右下、2つ目は右上/左下に適用
3値を指定 : 1つ目は左上、2つ目は右上/左下、3つ目は右下に適用
4値を指定 : それぞれ左上、右上、右下、左下の順 (時計回り) に適用

サポートしていないXML仕様

以下のXML仕様はサポートしていません。

CDATAセクション
処理命令 (processing instruction)