Reports.web Ruby WASM言語ラッパー プログラマーズガイド／APIリファレンス

1. 最初に知っておくことRM001

1.1 「WASM言語ラッパー」とはRM002

本書では、各言語でPREPEJを組み立てる補助ライブラリをWASM言語ラッパーと呼びます。実装の中心はPrintDataです。ラッパー自身はWASMを直接ロードせず、SVGやPDFも描きません。出力形式を共通JSONに揃えることで、業務処理と描画エンジンを疎結合にします。

これはPure Java／Pure Python／WPF・.NETの言語別エンジンとは異なる方式です。Pure系は各言語の帳票エンジンを直接呼びます。WASM方式は7言語が同じWASMエンジンとブラウザUIを共有します。

1.2 帳票ができるまでRM003

1. デザイナーで帳票定義 .prepdj を作ります。
2. RubyのPrintDataへPREPDJを設定します。
3. DBやAPIから取得した値を、デザイン上のオブジェクト名へ設定します。
4. 1ページずつ確定し、.prepejを作ります。
5. PREPEJをブラウザのプレビュアー、またはサーバーWASMへ渡します。
6. 共通エンジンがSVGプレビュー、PDF、印刷を担当します。

1.3 二つのファイルRM004

PREPEJは単なる一時レスポンスではありません。ファイル保存、再読込、メール添付、REST API、サーバー間転送、後日の再印刷に同じ文書を使えます。

2. サンプルを動かすRM005

基準環境は Ruby 3.3 です。同梱のDocker構成では必要な言語環境とDBをコンテナ内に用意するため、まずPC側で準備するのはDockerです。Windows／MacではDocker Desktopを起動し、LinuxではDocker EngineとComposeプラグインが使える状態にしてください。

ZIPを全体ごと展開してください。共通RuntimeとDB初期化データも使うため、番号フォルダーだけを取り出さないでください。初回のイメージ取得とビルドにはインターネット接続が必要です。

短いコードから学ぶ場合は WebAssembly/Samples/ruby/01.あっという間に帳票出力/README.html から始めます。ここでは全帳票を確認できる02の起動を説明します。

1. VS CodeやCursor、または使い慣れたエディターで WebAssembly/Samples/ruby/02.全帳票をWebでプレビュー を開きます。
2. そのフォルダーでターミナルを開き、次を実行します。開発用のReports Webリポジトリをビルドする必要はありません。

docker compose up -d --build --wait
docker compose ps

3. 起動が成功してから、ブラウザで http://127.0.0.1:19261/ を開きます。URLを開くだけではアプリは起動しません。
4. 終了するときは、同じフォルダーで docker compose down を実行します。このサンプルのコンテナとネットワークが削除されます。DBデータの初期化やイメージの片付けは、そのフォルダーのREADMEに手順があります。

02では、単純帳票、10の倍数、郵便番号一覧、見積書、請求書、商品一覧、名刺、デザイン機能見本を確認できます。請求書などを選び、ソースと出力結果を見比べてください。別のアプリから帳票APIを呼ぶ使い方は、続く03のREADMEに説明しています。

3. 最初の一枚を作るRM006

01のquick_start.rbを開き、definition = ...からprint_data = ...to_jsonまでを次のコードへ置き換えます。上のrequire群と、下のserver = ...以降は残します。クラスと定義は01に同梱済みです。ここでの/appはDockerコンテナー内の配置先で、利用者のパソコンに同名フォルダーを作る必要はありません。

definition = JSON.parse(File.read('/app/definition/quick-report.prepdj', encoding: 'UTF-8'))
print_data = PaoReportsWeb::PrintData.new
  .set_definition(definition)
  .page_start
  .set_value('Title', 'はじめての帳票')
  .set_value('CustomerName', 'パオ商事株式会社')
  .page_end
  .to_json(pretty: true)

01のフォルダーでdocker compose up -d --build --wait --wait-timeout 180を実行し、成功後にhttp://127.0.0.1:19260/を再読み込みします。「はじめての帳票」と会社名が表示され、「PDFを保存」で同じ内容を保存できます。TitleとCustomerNameは同梱定義内の名前です。自作の定義ではデザイナー上の名前に合わせます。

呼出順は 定義を設定 → ページを開始 → 値を設定 → ページを確定 → JSONを取得 です。未完了のページがある状態ではPREPEJを取得できません。この制約により、途中までの帳票を誤って配信することを防ぎます。

4. PrintData APIリファレンスRM007

配布ZIP内の実装ファイルは WebAssembly/Samples/ruby/02.全帳票をWebでプレビュー/lib/pao_reports_web/print_data.rb です。各番号のサンプルにも必要なソースを置いています。次のAPI名は実装に合わせています。

4.1 値とインデックスRM008

PaoReportsWeb::PrintData.newで新しい文書を作ります。HTTP要求ごとに別のインスタンスを使い、利用者間で作成途中の文書を共有しないでください。変更メソッドは自分自身を返すため、第3章のようにつなげて呼べます。不正な値や順序ではArgumentError、ファイル保存の失敗ではファイル操作の例外が発生します。

saveはブラウザーへのダウンロードではありません。ダウンロードの実装は01のindex.htmlや03の応答を参照してください。

値には文字列、数値、真偽値、nullの単純値を渡します。配列や任意オブジェクトを値として渡さず、帳票オブジェクトごとに明示的に対応付けてください。繰返しのindex、indexX、indexYは0から始まり、負数はエラーです。

drawing=falseは、その繰返し位置を描画しない場合に使います。値の設定はページのValuesへ追加されるため、同じ名前・同じ位置へ何度も設定せず、業務処理で決めた最終値を一度渡します。属性の値にはnilを渡せません。

kindを省略（nil）すると、そのページで有効な帳票定義から対応するDynamic型を推論します。明示kindはそのまま優先します。定義にない名前は従来互換のDynamicTextになります。空の名前、負のindex、x/yの片方だけの指定、nil属性値、非有限の数値は例外です。

4.2 ページごとに定義を切り替えるRM009

表紙と本文、途中から異なる一覧形式などでは、ページ開始時に別のPREPDJを渡します。座標をプログラムへ直接書くのではなく、デザイナーで完成させた定義をページへ結び付けます。定義を変更する前に現在のページを必ず確定してください。

5. 明細と改ページRM010

次は明細処理の抜粋です。definitionには「ページ」「品番」「品名」「金額」の動的文字を持つ定義、detailsには:code、:name、:amountを持つHashの配列を用意します。第3章の1ページ定義へそのまま貼る例ではありません。実際の同梱帳票との対応は02のlib/pao_reports_web/sample_catalog.rbを参照してください。

print = PaoReportsWeb::PrintData.new.set_definition(definition)
details.each_slice(20).with_index(1) do |rows, page|
  print.page_start.set_value('ページ', page)
  rows.each_with_index do |d, row|
    print.set_value('品番', d[:code], row)
         .set_value('品名', d[:name], row)
         .set_value('金額', d[:amount], row)
  end
  print.page_end
end

1ページの行数は帳票定義と業務仕様から決めます。最終ページの空行を描画するか、明細ごとに罫線を出すかもプログラム側で明示します。ページ番号はPREPEJのページ順と、帳票へ表示する業務上のページ番号を分けて考えます。

5.1 空文字で罫線・図形を消すRM011

罫線・四角・円（Line、DynamicLine、Square／Rectangle、Circle／Ellipse）は、値で表示を切り替えられます。

繰返しの行でも、1つだけの図形でも同じです。最初に書いたときも、別の値のあとに書いたときも同じです。表の行を途中で終える、合計行の上だけ線を引かない、条件で枠を消す、などに使います。次の明細線は、定義にある罫線のオブジェクト名の例です。

print.set_value('明細線', '', row) # この行の罫線を消す

drawing=falseも描きません。PREPEJでは、図形の値が""ならDrawingがtrueでも描きません。

文字の欄（Text）は別の規則です。値が""またはnilなら、文字も枠線も背景色も描きません。SVG・印刷・PDFで同じです。

5.2 何も書かない繰返しは1行目だけ描くRM012

繰返し（RepeatCountが2以上）のある物体に、そのページで何も書かないと、定義どおり1つだけ、1行目の位置に描きます。行の数だけ並べては描きません。

一部の行にだけ書くと、書いた行だけ描きます。書かなかった行は描きません。1行目に書かなければ、1行目も描きません。

表の罫線や枠を全部の行に描くには、描きたい行それぞれにnil（値なし）を書きます。罫線・図形はnilなら描き、""なら消えます（5.1）。次の1行を上の明細のループに足すと、明細の行数ぶん明細線にnilを書きます。

print.set_value('明細線', nil, row) # この行の罫線を描く

文字の欄は、nilを書くとその行の文字が空になります。定義の文字を出したい行には、その文字を書きます。PREPEJへ保存した印刷データでも同じです。

6. 画像・バーコード・動的属性RM013

値を書いていない文字・四角には、同じページで前に値を書いた物体の最後の行と同じ行の属性だけが当たります。値なしの罫線・楕円・画像・バーコードの旧形式の属性は当たりません。

ページ開始後の操作例です。定義に動的画像「角印」、動的バーコード「商品QR」、動的文字「合計金額」があり、stamp_data_uriに画像データの文字列が入っている前提です。

print.set_image('角印', stamp_data_uri)
     .set_barcode('商品QR', 'https://example.jp/items/123')
     .change_attributes('合計金額', {
       'bold' => true, 'fontSize' => 16,
       'horizontalAlignment' => 'Right'
     })

画像は閲覧先でも取得できる管理下のURL、または許容サイズのdata URIにします。サーバーPDF生成では、任意の外部URLをそのまま取得するとSSRFにつながります。固定画像は許可リストまたはアプリ管理下のファイルから解決してください。

動的属性では、名前・型・値を無検証のリクエストから直接渡さないでください。変更できる属性をアプリ側で限定し、数値範囲、色、配置、フォント名を検証します。

7. ブラウザへ渡して表示するRM014

Ruby APIはPREPEJをapplication/json; charset=utf-8で返します。次は01の実在するURLを使った表示部分の抜粋です。エラー表示やPDFボタンを含む画面全体は01のindex.htmlを参照してください。

<iframe id="reportsViewer" title="帳票プレビュー" style="width:100%;height:75vh;border:0"></iframe>
<script>
const viewer = document.querySelector('#reportsViewer');
viewer.addEventListener('load', async () => {
  const response = await fetch('/print-data');
  if (!response.ok) throw new Error(`HTTP ${response.status}`);
  await viewer.contentWindow.ReportsWeb.setPrintData(await response.json());
});
viewer.src = '/reports.web/preview/index.html?empty=1';
</script>

親画面とプレビュアーは同一オリジンに置くのが最も簡単です。別オリジンでpostMessageを使う場合は、送信元と送信先のoriginを固定し、*を本番環境で使わないでください。

プレビュアー側ではsetZoom("auto")、ページ移動、検索、印刷、exportPdf()、savePrintData()を利用できます。独自画面へ表示面だけを組み込む場合はhideAll()でツール群を隠し、同じ機能を外側のボタンから呼び出します。

8. PDFを作る二つの場所RM015

8.1 ブラウザで作るRM016

PREPEJを利用者のブラウザへ渡し、ブラウザ内のWASMがPDFを生成します。サーバーのPDF描画負荷を抑え、プレビューからそのまま保存・印刷する操作に向きます。機密データをブラウザへ渡してよいかは、業務の認可設計で判断します。

8.2 サーバーで作るRM017

Sinatra／Pumaなどから共通Node/WASMサービスへHTTPでPREPEJを送ります。 定期処理、メール添付、保存、監査、画面を開かない帳票生成に向きます。

POST /render/pdf
Content-Type: application/json

<PREPEJ JSON>

成功時はapplication/pdfを返します。失敗時は次の状態コードと、理由を書いたJSON（{"error":"…"}）を返します。

408・413・503のときもサーバーは止まらず、次の要求を処理します。業務アプリ側でも処理時間を制限し、失敗時の途中PDFを保存・配信しないでください。ブラウザ生成とサーバー生成は同じPREPEJを入力にするため、業務データ組立てを二重実装する必要はありません。

9. PREPEJを保存・再利用するRM018

saveは完成したPREPEJをUTF-8 JSONとして保存します。保存前にページをすべて確定してください。ファイル名には.prepejを使い、アップロード時には拡張子だけで信用せず、Format、Version、Definition、Pages、サイズ、ページ数を検証します。

保存した文書は、Webプレビュアーの「開く」またはドラッグ＆ドロップで再表示できます。HTTPで受け渡す場合もファイルと同じJSONです。再印刷の証跡として保管する場合は、業務データの保持期間、暗号化、アクセス権、削除規則を定めます。

10. Web APIとデータベースRM019

DB列と帳票オブジェクト名はコードで明示的に対応付けます。SQLはプレースホルダーを使い、利用者が参照できる伝票かを取得前に確認します。日付、通貨、端数処理は帳票へ渡す前に業務規則で確定します。

機密帳票のレスポンスにはCache-Control: no-storeを設定します。内部例外、接続文字列、ファイルパスを利用者へ返さず、要求IDを安全なサーバーログへ残します。帳票定義や画像は可能なら公開ルート外へ置きます。

11. テストとリリース確認RM020

まず各サンプルのREADMEに沿って、表示・文字変更・PDF保存・再読込を確認します。Dockerだけを用意した方も実施できます。ラッパーを変更する場合は、以下の条件についても試験を追加してください。

最低限、次を確認します。

• 共通印刷データの形式識別子を持ち、Versionが1.0である
• PREPDJを設定せずにページを開始するとエラーになる
• ページを閉じずに次のページを開始できない
• 日本語、改行、数値、真偽値、nullが壊れない
• 明細の先頭・最終行、改ページ前後に欠落や重複がない
• ページ途中の帳票定義切替が、完了済みページを変更しない
• 画像・角印、バーコード、動的属性がSVGとPDFへ反映される
• 保存したPREPEJを開き直すと同じページ・内容になる
• ブラウザ生成とサーバー生成のページ数・主要表示が一致する

ラッパー変更時はWASM描画エンジン全体を毎回再試験するのではなく、生成PREPEJが共通仕様と基準サンプルに一致することを中心に確認します。WASM、プレビュアー、フォント、画像処理を変更した場合は、別途描画回帰試験が必要です。

12. よくある問題RM021

13. 配置・更新・ライセンスRM022

ラッパー、プレビュアー、JavaScript／TypeScript、CSS、WASMは同じReports.web配布版から取り出してください。HTMLだけ、またはラッパーだけを別バージョンへ差し替えると、PREPEJや公開APIの互換性を判断できなくなります。

現行の製品版への切替は、購入者のメールアドレスを含む電子署名付きの reports-web.license を、実際に帳票を出力する側へ配置して行います。購入者ごとにWASMを差し替える手順ではありません。ブラウザーとサーバーでは配置先が異なるため、製品版を使い始めるに従ってください。ライセンスファイルを公開サンプルやソース管理へ混入させないでください。正式な動作環境、使用許諾、更新履歴、問い合わせ先は共通製品マニュアルを正本とします。開発ライセンスは開発用PC 1台につき1ライセンスです。