Reports.web TypeScript／Node.js 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. TypeScript／Node.jsのPrintDataへPREPDJを設定します。
3. DBやAPIから取得した値を、デザイン上のオブジェクト名へ設定します。
4. 1ページずつ確定し、.prepejを作ります。
5. PREPEJをブラウザのプレビュアー、またはサーバーWASMへ渡します。
6. 共通エンジンがSVGプレビュー、PDF、印刷を担当します。

1.3 二つのファイルRM004

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

2. サンプルを動かすRM005

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

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

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

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

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

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

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

3. 最初の一枚を作るRM006

01のprint-data.mjsは、処理の流れを短く見せるための小さな実装です。ここからは、02に同梱した機能一式のあるsrc/PrintData.tsを使います。TypeScriptはビルド後にJavaScriptになるため、importには.jsを指定します。

02のsrc/server.tsで、既存のimport type { JsonObject } ...は残し、その次に以下を追加してください。

import { PrintData } from "./PrintData.js";

同じファイルのconst url = new URL(...)とpath = url.pathname;の直後、最初のifより前に、次の処理を追加します。既存のHTTPサーバー、帳票定義の読込処理、エラー処理を利用するため、別のサーバーを作る必要はありません。

if (path === "/first-report" && req.method === "GET") {
  const definition = await catalog.definition("quick-start");
  const print = new PrintData()
    .setDefinition(definition)
    .pageStart()
    .setValue("Text2", "はじめての帳票")
    .pageEnd();
  res.writeHead(200, {
    "Content-Type": "application/json; charset=utf-8",
    "Content-Disposition": "attachment; filename=first-report.prepej"
  });
  res.end(print.toJson());
  return;
}

保存後、02のターミナルでdocker compose up -d --build --wait --wait-timeout 180を実行します。成功したらhttp://127.0.0.1:19221/first-reportを開きます。ダウンロードしたfirst-report.prepejを02の画面の「印刷データを開く」で選ぶと、変更した文字が表示されます。PDFも保存してみてください。

Text2は02のresources/definitions/quick-start.prepdjにある動的文字の名前です。01のMessageとは異なります。自分の帳票では、デザイナーで付けたオブジェクト名を指定します。文字が出ない場合は、JavaScriptの変数名ではなく、この名前の対応を確認してください。

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

4. PrintData APIリファレンスRM007

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

4.1 引数と戻り値RM008

引数の順序と省略時の値は次のとおりです。JsonObjectはJSONオブジェクト、Scalarは文字列・有限の数値・真偽値・nullを表します。

new PrintData()
setDefinition(d: JsonObject)
pageStart(d: JsonObject | null = null)
setValue(n: string, v: Scalar, i = 0, drawing = true)
setRepeatedValue(n: string, v: Scalar, x: number, y: number, drawing = true)
setTypedValue(n: string, type: string, v: Scalar, i = 0, drawing = true)
setImage(n: string, source: string, i = 0, drawing = true)
setBarcode(n: string, code: string, i = 0, drawing = true)
drawObject(n: string, i = 0, type: string | null = null)
changeAttributes(n: string, values: Record<string, Scalar>, i = 0)
changeRepeatedAttributes(n: string, values: Record<string, Scalar>,
                         i = 0, x?: number, y?: number, type: string | null = null)
pageEnd()
toObject(): JsonObject
toJson(pretty = true): string
save(path: string): Promise<void>

setDefinitionからpageEndまでは同じPrintDataを返すため、続けて呼び出せます。toObjectは完成データのコピーを返します。toJson(false)は整形用の空白を省きます。saveはサーバー側のファイル保存なのでawait print.save("output.prepej")とします。ブラウザーへのダウンロードは、第3章のようにHTTP応答を返す別の処理です。

名前が空、インデックスが不正、値が配列やオブジェクト、ページ開始・終了の順序が不正な場合は例外になります。HTTP要求ごとに新しいPrintDataを作り、作成途中のインスタンスを複数要求で共有しないでください。

4.2 値とインデックスRM009

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

drawing=falseは、その繰返し位置を描画しない場合に使います。値の設定は一覧へ追加され、同じ名前・同じ位置の以前の設定を削除する操作ではありません。一か所への値は一度に決めて渡してください。動的属性の値にはnullを使えず、changeRepeatedAttributesのxとyは両方指定するか、両方省略します。

型を省略（null）すると、そのページで有効な帳票定義からText／Line／Square／Circle／Image／Barcodeを調べ、対応するDynamic型を記録します。型を明示した場合は指定値を優先し、勝手に置換しません。定義にない名前を指定すると、値を記録せずその場で例外（帳票にオブジェクト「名前」がありません。）になります。空の名前、負のindex、x/yの片方だけの指定もエラーです。

4.3 ページごとに定義を切り替えるRM010

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

5. 明細と改ページRM011

以下は自分の帳票に組み込むための抜粋です。definitionには「ページ」「品番」「品名」「金額」を持つ定義を、detailsにはcode・name・amountを持つ明細配列を用意します。第3章の単純帳票へそのまま貼り付ける例ではありません。

const print = new PrintData().setDefinition(definition);
for (let offset = 0, page = 1; offset < details.length; offset += 20, page++) {
  print.pageStart().setValue("ページ", page);
  details.slice(offset, offset + 20).forEach((d, row) =>
    print.setValue("品番", d.code, row)
         .setValue("品名", d.name, row)
         .setValue("金額", d.amount, row));
  print.pageEnd();
}

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

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

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

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

print.setValue("明細線", "", row); // この行の罫線を消す

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

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

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

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

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

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

print.drawObject("明細線", row); // この行の罫線を描く（null を書く）

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

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

帳票にない名前へ setValue を呼ぶと、その場で例外になります。サーバーの画像は各ページで画像データを値として渡します。定義のパスのままなら HTTP 400 です。

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

この抜粋では、ページ開始後のprint、画像のdata URIを持つstampDataUri、対応する「角印」「商品QR」「合計金額」を定義に用意していることを前提にします。

print.setImage("角印", stampDataUri)
  .setBarcode("商品QR", "https://example.jp/items/123")
  .changeAttributes("合計金額", {
    bold: true, fontSize: 16, horizontalAlignment: "Right"
  });

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

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

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

TypeScript／Node.js APIはPREPEJをapplication/json; charset=utf-8で返します。ブラウザ側は共通のReports Web APIへ渡します。

<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('/first-report');
  if (!response.ok) throw new Error(`HTTP ${response.status}`);
  await viewer.contentWindow.ReportsWeb.setPrintData(await response.json());
});
viewer.src = '/demo/reports.web/preview/?empty=1';
</script>

上は第3章で追加したデータAPIを使う処理の抜粋です。02ではpublic/index.htmlが画面にあたり、すでに受信・表示・PDF保存の実装があります。まずそのソースと見比べてください。自作アプリでは配信先に合わせてURLを変更し、通信失敗を画面に表示します。

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

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

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

8.1 ブラウザで作るRM017

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

8.2 サーバーで作るRM018

Node.jsから同一プロセスまたは共通Node/WASMサービスへPREPEJを渡します。 定期処理、メール添付、保存、監査、画面を開かない帳票生成に向きます。

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

<PREPEJ JSON>

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

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

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

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

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

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

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

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

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

PCへNode.jsを導入せずDockerだけで動かした場合は、まずREADMEの手順で表示・編集・PDF保存を確認します。PC側にもNode.js 22以降を用意した方は、02フォルダーでnpm ci、npm testの順に実行すると、同梱の単体試験を実行できます。01の短い実装にはこの単体試験はありません。

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

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

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

12. よくある問題RM022

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

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

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