帳票を作る

請求書や納品書のような帳票を、テンプレートとデータから BDF として作れます。テンプレートは、文字のところにタグ（{{名前}}）を書いた Excel のブック、Word の文書、PowerPoint のプレゼンテーション、入力欄のある PDF、pdfme のテンプレートです。データは JSON・YAML・CSV・Excel のファイルで、bdf fill がタグをデータに置き換え（または入力欄を埋め）、組版して .bdf を書き出します。Office のファイルは書き出しません。できた帳票は bdf pdf で PDF にできます。タグ付き PDF と PDF/A も選べます。

bdf fill -data order.yaml -data items=lines.csv invoice.xlsx invoice.bdf
bdf pdf invoice.bdf invoice.pdf

タグの書き方とデータは、Office の 3 つの形式に共通です。同じデータを、形式の違うテンプレートに流し込めます。PDF フォームと pdfme のテンプレートにはタグの代わりにフィールドがあり、その名前で同じ形のデータを受け取ります。

インストールせずに試すなら、フォームのページにテンプレートをドロップしてください。タグを読んで入力フォームを作り、入力した値で穴埋めした帳票を表示して、PDF で保存できます。処理はすべてブラウザの中で行われ、ファイルはアップロードされません。

テンプレートを書く

普段どおりに帳票を作り、値を入れたいところにタグを書きます。まず Excel のブックで説明します。Word と PowerPoint は、同じタグが何を繰り返すかだけが違います（Word のテンプレート、PowerPoint のテンプレート）。

Excel では、用紙・余白・印刷範囲・印刷タイトル・改ページ・ヘッダーとフッターは、ブックのページ設定がそのまま使われます（Excel の印刷ビュー）。

• 波括弧・記号・引用符は、日本語入力や Word が置き換えた全角や曲がった引用符（｛｛、＃、“ ”）でもかまいません。
• \{{ と書くと、タグではなく文字の {{ になります。
• セルがタグ 1 つだけなら、値はそのままセルの値になります。数値は数値（セルの表示形式で表示され、数式から読める）、日付は日付です。文字列の "2026-10-13" は、セルかタグの表示形式が日付のときだけ日付として読みます。
• ほかの文字と一緒に書いたタグは、文字に置き換わります（{{customer}} 御中）。
• タグは名前を引くだけで、計算はしません。合計・税・繰越とその端数処理はデータの側で済ませてください（ブックの数式は別で、後述のとおり計算し直します）。

行を繰り返す

区間の開始と終了のタグを別々のセルに書くと、行の繰り返しになります。繰り返す行のセルからは、その項目の値が見えます。

行を増やす（開始と終了が同じ行）: 項目ごとに行が 1 つ増え、下の行は押し下げられ、用紙に入らなければページが増えます。印刷タイトルの行は各ページで繰り返されます。

決まった行数に入れる（開始と終了が別の行）: 開始のタグの行から終了のタグの行までが、項目を 1 つずつ入れる枠になります。行は増えず、項目のない行は罫線だけの空行として残ります。1 行目のタグと数式が、自分のタグを持たない残りの行にも使われます。項目が枠より多いとエラーになります。

ページとして繰り返す（| pages）: 開始から終了までの行のまとまりを項目ごとに複製し、それぞれを新しいページにします。10 行の伝票を 25 行分のデータで 3 枚にする、という帳票はこの形です。データは、ページごとの行と繰越をあらかじめ分けて渡します。

{ "pages": [
    { "rows": [ … 10 行 … ], "carry_in": 0,     "carry_out": 55000 },
    { "rows": [ … 10 行 … ], "carry_in": 55000, "carry_out": 210000 },
    { "rows": [ … 4 行 … ],  "carry_in": 210000, "carry_out": 300000 } ],
  "total": 300000 }

{{#pages | pages}} … {{/pages}} の中に {{#rows}} … {{/rows}} の枠を置きます。ページ番号は {{_page}} / {{_pages}}、最後のページだけに出す合計は {{#_last}}合計 {{total}}{{/_last}} と書けます。

{{#groups | rows}} と書けば、別の行にまたがるまとまりを、行を増やしながら繰り返します（グループの見出し・明細・小計）。区間は入れ子にできます。

開始と終了のタグを同じセルに書いた区間は、セルの中の文字を繰り返します（{{#tags}}{{.}} {{/tags}}）。同じセルでも | rows を付ければ行の繰り返しになるので、1 列だけの表でも行を増やせます（{{#items | rows}}{{name}}{{/items}}）。繰り返し方を書いた区間は、文字ではなく行（Word では段落、PowerPoint ではスライドなど）を繰り返す、という規則は 3 つの形式に共通です。逆の区間にも書けます（{{^items | rows}}明細なし{{/items}} は、項目がないときだけその行を出します）。

区間の中で使える変数

行に追随するもの

行が増えたり複製されたりすると、Excel で行を挿入したときと同じように、行を指しているものが付いてきます。結合セル、条件付き書式、リンク、印刷範囲と印刷タイトル、改ページ、図形、そして数式の参照です。複製された行の中の数式は自分の行（自分のページ）を指し、繰り返す行を含む範囲はすべての複製を含みます（=SUM(E4:E4) は全明細の合計になります）。

数式は穴埋めのあとで計算し直します。条件付き書式の評価器が知っている関数（四則、SUM、AVERAGE、COUNT、COUNTIF、IF、ROUND、文字列、日付 など）が対象で、それ以外の数式のセルは空にして警告を出します。

Excel の表見出しとセクションの改ページ

請求書では、Excel の「印刷タイトル」の「タイトル行」を表の見出しだけ （例: $15:$15）にします。帳票タイトルや宛名はこの範囲に含めません。 通常の印刷タイトルは後続の全ページに繰り返されますが、「数式 → 名前の管理」で 次の名前をシートのスコープに定義すると、BDF の改ページを調整できます。

範囲はテンプレートの行の増減に追従します。繰り返す項目の中に置いた範囲は 各項目に適用されます。重なった範囲は一つのまとまりになり、隣接するだけの 範囲は別々に扱います。1 ページより高いまとまりは分割でき、手動の改ページは 優先されます。この名前は BDF の出力を制御するもので、Excel 自体の印刷プレビューは Excel の規則に従います。公開している Excel の請求書サンプルには両方を設定済みです。

Word のテンプレート

Word の文書では、本文・表のセル・テキストボックス・ヘッダーとフッターの文字にタグを書きます。穴埋めのあと文書を組み直すので、値が長くなれば行が増え、表の行が増えれば次のページへ流れます。表の見出し行（「タイトル行の繰り返し」）は、流れた先のページでも繰り返されます。帳票はページのビューだけになります。

区間が繰り返すものは、開始と終了のタグを両方含むいちばん小さいまとまりで決まります。

• タグだけの段落（{{#items}} や {{/items}} だけを書いた段落）は、帳票には出ません。
• | rows を付けた区間は、タグが同じ段落にあっても、表の中ならその行を、表の外ならその段落を繰り返します。箇条書きの 1 段落に {{#items | rows}}{{name}}{{/items}} と書けば、項目ごとの箇条書きになります。
• | pages を付けた区間は、開始から終了までの段落と表を項目ごとに繰り返し、2 つ目からは新しいページで始めます。1 ページの帳票を人数分作る、10 行の伝票をページごとのデータで複数枚にする、という形です。
• 画像は、文書に置いた画像の代替テキストに {{%photo}} と書きます。その画像が、データの画像に置き換わります。代替テキストの残りの文字は、新しい画像の代替テキストになります。
• Word は、スペルチェックや編集の履歴でタグを途中で分けて保存します（{{custo + mer}}）。段落の中の文字はひと続きとして読むので、そのままで動きます。値の書式は、タグが始まる位置の文字の書式です。
• ヘッダーとフッター、区間の外のテキストボックスからは、データのいちばん外側の値が見えます。区間の中に置いたテキストボックスからは、その項目の値が見えます。脚注と文末脚注は穴埋めしません。
• ページ番号は Word のフィールド（PAGE、NUMPAGES）をそのまま使えます。

PowerPoint のテンプレート

PowerPoint では、図形・テキストボックス・表のセルの文字にタグを書きます。スライドは固定のページで、図形は置いた場所から動きません。

• | rows を付けた区間は、タグが同じ段落にあっても、表の中ならその行を、それ以外ならその段落を繰り返します。| pages を付けた区間はスライドを繰り返します（{{^items | pages}} は、項目がないときだけそのスライドを出します）。
• 文字の収まりは、値を入れたあとで PowerPoint と同じ規則で決め直します。「はみ出す場合だけ自動調整」の図形は文字を縮め、「テキストに合わせて図形のサイズを調整」の図形は高さを変えます。図形どうしが押し合うことはありません。
• 行が増えた表がスライドに収まらなくなると、同じスライドを複製して続きを載せます。繰り返す行より上の行（見出し）は各スライドに、下の行（合計など）は最後のスライドに出ます。表は、下にある図形の上端か、スライドの下の余白までを使います。
• スライド番号は {{_slide}} / {{_slides}} と書けます。繰り返しや表の続きで増えたスライドを含めた番号と枚数になります。
• 画像は、スライドに置いた画像の代替テキストに {{%photo}} と書きます。
• PowerPoint も言語の切り替わりでタグを途中で分けて保存しますが、段落の中の文字はひと続きとして読みます。

PDF フォーム

入力欄のある PDF（AcroForm。Acrobat や LibreOffice、多くのフォーム作成ツールが作るもの）は、そのままテンプレートになります。入力欄の名前がデータの名前です。bdf fill は入力欄の場所に値を描き、PDF のページを BDF の文書として書き出します。できた帳票に入力欄は残りません。

bdf template schema -json-schema application.pdf   # 入力欄を、データの JSON Schema として
bdf fill -data applicant.json application.pdf application.bdf
bdf pdf application.bdf filled.pdf

• 入力欄の名前が、データで値を引く名前です。applicant.name という欄は、オブジェクト applicant の name です（ドットを含む名前そのままでも渡せます）。
• スキーマには、PDF が欄について持っている情報が入ります。選択肢（enum。表示名は x-bdf.labels）、最大の文字数（maxLength）、PDF に入っている値（default）、欄のツールチップ（タイトル）です。
• 文字は、欄が指定する大きさ・色・揃えで、その文字を持つマシンのフォントを使って描きます。フォームのフォントは欧文だけのことが多いので、日本語の値はそれに左右されません。
• データに値がない欄は、PDF にある状態のまま残り、警告が出ます（-strict ではエラー）。押しボタンと署名欄は埋めません。
• 欄の枠線と背景は残ります。チェックボックスとラジオボタンは、PDF が持っているその状態の外観を使います。

pdfme のテンプレート

pdfme は、ブラウザで動くデザイナーを持つオープンソースの PDF 生成ライブラリです。そのデザイナーが保存するテンプレート（JSON のファイル。土台の PDF か白紙のページと、ミリ単位で場所を決めたフィールド）も、そのままテンプレートになります。pdfme の生成器と同じ規則で埋めます。

bdf fill -data invoice.json template.json invoice.bdf
bdf template compile template.json invoice.bdft   # デザイナーで入れてあった内容のページになる

• データは JSON の値で渡します。pdfme は表の行を JSON の文字列として受け取りますが、ここでは配列です。
• 白紙のページが土台のときは、表・リスト・伸びるテキスト（overflow: expand）がデータに合わせて伸び、下にあるものを押し下げ、次のページへ続きます。表はテンプレートの指定（repeatHead）があれば列の見出しをページごとに繰り返し、土台のページの固定のフィールド（staticSchema）は全ページに出ます。PDF が土台のときは、フィールドは置いた場所のまま、番号の対応する PDF のページに載ります。
• 読み取り専用のテキストには式を書けます（{price * 1.1}、{currentPage} / {totalPages}）。四則演算、比較、? :、文字列・数値・配列のメソッド、Math、JSON が使えます。それ以外のコードは動きません。式が読むデータの名前はスキーマのフィールドになります。pdfme が時計から読む date と dateTime も同じ扱いなので、同じデータからは同じ帳票ができます。
• テンプレートが指定するフォントは、マシンのフォントから探します（-font-dir）。指定がなければ pdfme の既定の Roboto です。マシンにないフォントは代わりのフォントで組みます。
• デザイナーでフィールドに入れてあった内容が、テンプレートのサンプルになります。-sample なしの bdf template compile はそれを見せ、フォームのページもそこから始まります。
• pdfme と違うところ: テキストの中の Markdown 風の書式は使えません。japanpost、upce、gs1datamatrix、pdf417 のコードは描かず、警告を出します。バーコードの下の文字は、バーの下に 1 行で置きます。QR コードは内容は同じですが、マスクの選び方が違うことがあります。SVG の画像は枠の中に全体を収めます（pdfme の生成器は一部を切り落とすことがあります）。
• 土台の PDF を URL で指定したテンプレートは読みに行きません。デザイナーが保存するとおり、テンプレートの中に入れてください。

QR コードとバーコード

画像のタグに qr か barcode:種類 を付けると、値を符号化したコードを画像の代わりに描きます。置く場所は画像と同じです。Excel ではタグを書いたセル（結合セルならその範囲）、Word と PowerPoint では代替テキストにタグを書いた画像の枠です。

• コードは黒いベクターの輪郭で描きます。拡大しても、PDF にして印刷しても、にじみません。
• QR コードは枠の中央に、正方形のまま収まります。バーコードは数字も含めて枠に収まります。読み取り機が必要とする太さになるように、枠の大きさを決めてください（JAN の標準は幅 37.29 mm、0.8 倍から 2 倍まで）。
• コードの周りには、読み取りに必要な余白（クワイエットゾーン。QR コードは 4 モジュール、バーコードは左右に 10 モジュール）が付きます。枠の外に余白があるなら quiet:0 で外せます。quiet:2 のようにモジュール数も書けます。
• 値は文字列か数値です。先頭が 0 のコード（0490…）は、データで文字列として渡してください。
• 値がない（空か null）ときは何も描きません。コードに入らない値（桁数の違う JAN、チェックデジットの誤り、使えない文字、大きすぎる QR コード）は、コードを描かずに警告を出します。-strict ではエラーです。
• 支援技術と検索のために、コードには図としての代替テキストが付きます。Excel と、代替テキストがタグだけの画像では、コードの内容そのものです。
• JAN / EAN-13、EAN-8、UPC-A は、チェックデジットも含めた数字をバーの下に描きます。数字の輪郭は image/barcode に内蔵しているため、フォントや別の値タグは不要です。

フォームを使わず、同じ描画を直接生成することもできます。

symbol, err := barcode.Encode("jan", "490123456789", nil) // チェックデジットを補い 4901234567894 に
// err を確認してから、バーと数字を一緒に描きます。
drawing := symbol.Object(113, 36)

バーだけ描く場合は &barcode.Options{NoText: true} を渡します。Symbol.At と Symbol.Rects は、数字の描画とは独立して符号化されたモジュールだけを返します。

PDF にする

bdf pdf は、BDF の文書を PDF に書き出します。帳票に限らず、どの文書でも使えます。

bdf pdf invoice.bdf invoice.pdf
bdf pdf -skip background -skip master slip.bdf slip.pdf   # 印刷済みの用紙に重ねて刷る
bdf pdf -tagged report.bdf report.pdf                      # タグ付き PDF
bdf pdf -pdfa 2a invoice.bdf invoice.pdf                   # 保存用の PDF/A

• 文字は文字のまま書き出します。文書のフォントを、使っているグリフだけにして埋め込むので、PDF の中で検索とコピーができます。名前で参照しているフォントは、書き出すマシンのフォントから埋め込みます（-font-dir）。埋め込みが許可されていないフォントの文字は、文字のアウトラインとして描き、検索のための文字列を付けます。
• 図形・線・グラデーション・透明・ブレンド・ソフトマスクはベクタのまま、JPEG はそのまま、ほかの画像は画素として入ります。SVG の画像は 300 dpi の画像にします。リンクと文書情報（タイトル・作成者・日付）も入ります。
• ページのあるビュー（Excel の印刷ビュー、Word のページ、スライド）を書き出します。ページのない文書（表計算のシート、スクロールだけの文書）は、全体を 1 ページにします。-view でビューを選べます。
• 影（SHADOW）は PDF に相当するものがないので、影だけを 300 dpi の半透明の画像にして、図形の下に敷きます。図形そのものはベクタのままです。
• FILTER と Canvas 特有の合成（destination-out など）は PDF に相当するものがないので、省くか通常の重ね描きにして警告を出します。暗号化は、まだ書き出しません。
• 同じ文書からは、同じバイト列の PDF ができます。

タグ付き PDF と PDF/A

タグ付き PDF（-tagged）は、ページの見た目とは別に、文書の構造を持つ PDF です。どの文字が見出しで、どれが段落、箇条書きの項目、表のセルなのか、どの順に読むのか、図は何を表しているのかが入ります。スクリーンリーダーはこの構造をたどって読み上げ、PDF から文字を取り出すツールは段落や表を崩さずに取り出せます。

• 構造は BDF が持っているもの（変換器が書く MARK 命令）をそのまま写します。見出しとそのレベル、段落、リスト、表（見出しセルと結合セルを含む）、代替テキストつきの図、リンク、文字の言語です。
• ページのヘッダーとフッター、スライドのマスター、背景、シートの枠線、影は、装飾（アーティファクト）として印を付けます。読み上げでは飛ばされます。

PDF/A（-pdfa）は、長期保存のための PDF です。10 年後に開いても同じに見えるように、開くマシンに頼るものを一切持ちません。

• PDF/A が許さないものは、別の形で書きます。画像はビューアに補間させず、どのフォントにもない文字は、空の箱を描く代わりに省いて警告を出します。
• レベル a では、私用領域の文字（アイコンフォントなど）に警告を出します。規格が、その文字が何であるかを示す文字列を求めるためです。
• 書き出したファイルは、開発の中で veraPDF で検査しています。PDF/UA は名乗りません。文書そのもののタイトル、言語、順序の正しい見出しも必要になるためです。透明を持てない PDF/A-1 は書き出しません。

データ

データは JSON の値でできた 1 つのオブジェクトです。-data を繰り返して組み立てます。

CSV の値は、JSON の数値と同じ書き方のものだけが数値になります（007 や 1,234 は文字列のまま）。true と false は真偽値、空は値なしです。画像はファイルのパス（-files のディレクトリ、既定ではテンプレートのディレクトリから）か data: URL で渡します。パスはそのディレクトリの中にとどまります。.. や外へ出るリンクはたどりません。

データにない名前のタグは空にして警告を出します。-strict を付けるとエラーにします。

レコードごとに 1 つずつ帳票を作るには -each を使い、出力のパスにタグを書きます。

bdf fill -each orders.csv -data items=lines.csv invoice.xlsx 'out/{{customer}}-{{no}}.bdf'

1 つの文書に全員分をまとめるなら、テンプレートの側で {{#orders | pages}} を使います。

コンパイル済みテンプレート（.bdft）

bdf template compile はテンプレートを検査し（タグの閉じ忘れや、行をまたぐ区間の書き間違いを、セルの番地や段落・図形の場所つきで報告します）、コンパイル済みテンプレートを書き出します。中身は BDF の文書で、サンプルデータで穴埋めしたページ（サンプルがなければタグのままのページ）を見せ、テンプレートそのものと、タグが引く名前の一覧を持ちます。ビューアやサムネイルでそのまま開け、bdf fill にテンプレートの代わりに渡せます。

bdf template compile -sample sample.yaml invoice.xlsx invoice.bdft
bdf template schema invoice.bdft        # タグが引く名前を JSON で
bdf fill -data order.yaml invoice.bdft out.bdf

データの JSON Schema と入力フォーム

テンプレートが求めるデータの形は、JSON Schema として取り出せます。入力フォームを自動で作るライブラリや、データの検証にそのまま渡せます。フォームのページの入力欄も、このスキーマから作っています。

bdf template schema -json-schema invoice.xlsx invoice.schema.json
bdf template schema -json-schema -sample sample.yaml invoice.xlsx   # サンプルで型と場所を確かめる

タグは値の型を書かないので、スキーマはタグから推し量ったものです。

• プロパティはテンプレートに出てくる順に並びます。それぞれの x-bdf に、タグの種類（kind）、表示形式（format）、繰り返し方（mode、slots）、コードの種類（code）、タグのある場所（at）が入ります。
• 区間の中の名前は、項目とその外側の両方から探されるので、タグだけではどちらのものか決まりません。外側でも同じ名前を使っていれば外側のもの、そうでなければ項目のものとして扱います。
• サンプルデータがあれば、それで確定します。名前はサンプルにある場所に置かれ、値の型はサンプルの値の型になり、区間は値が配列かオブジェクトか真偽値かで決まります。
• コンパイル済みテンプレート（.bdft）は、サンプルで確定したスキーマを中に持っています。bdf template schema -json-schema invoice.bdft はそれを返すので、テンプレートを読み直さずにフォームを作れます。
• 必須の項目（required）は付きません。データにない名前のタグは空になるだけです。
• PDF フォームと pdfme のテンプレートは、タグより多くのことをフィールドについて知っています。チェックボックスは真偽値、日付のフィールドは "format": "date"、選択肢は enum、入っている値は default、文字数の上限は maxLength になります。

Go から使う

data, err := form.LoadData(
	form.Source{FileName: "order.yaml", Data: order},
	form.Source{Name: "items", FileName: "lines.csv", Data: lines})
res, err := form.Fill(template, size, &form.Options{Data: data})
err = res.Doc.WriteSingle(out)

form.Fill は、テンプレートの形式を中身から判定します（Office のファイル、PDF フォーム、pdfme のテンプレート、コンパイル済みテンプレート）。form.Fields はタグが引く名前を、form.SchemaOf はデータの JSON Schema を、form.Compile はコンパイル済みテンプレートを返します。形式が決まっていれば xlsx.Fill、docx.Fill、pptx.Fill を直接呼べます。PDF は pdfbdf.Write で書き出します。

res, err := pdfbdf.Write(out, doc, &pdfbdf.Options{})                          // PDF
res, err = pdfbdf.Write(out, doc, &pdfbdf.Options{Tagged: true, PDFA: "2a"}) // タグ付きの PDF/A-2a

知っておくこと

• Excel のページの切れ目は Excel と同じ規則で決めますが、Excel は印刷のときに行の高さと列幅をプリンタの画素に丸めるので、自動の改ページが 1 行ずれることがあります。位置が大事な改ページは、手動の改ページにしてください。
• 文字は変換するマシンのフォントで組みます。テンプレートが指定するフォントがなければ代わりのフォントで組むので、-font-dir で使うフォントを決めておくと、どこで作っても同じ帳票になります。
• 同じテンプレートと同じデータからは、同じバイト列の文書ができます。Excel のヘッダーとフッターの &D・&T（日付と時刻）は、そのために空にします。
• Word と PowerPoint のテンプレートは計算をしません（Excel の数式にあたるものがありません）。合計や繰越はデータで渡します。
• テンプレートは信頼できない入力として扱います。タグはコードを実行せず、できあがる帳票の大きさ（セル、スライド、要素の数）には上限があります。pdfme テンプレートの式にも、評価のステップ数、書き出す文字列（1 MiB）、作るリストの要素数の上限があります。PDF フォームのフィールドの文字列は 65,536 文字で切ります。