アプリケーションのセットアップ

Webブラウザ上で動作させる

Webブラウザ上で帳票出力を行うアプリケーションを作成する場合、3つのセットアップ方法があります。

パブリックCDNを使う

jsDelivr等のパブリックCDNにホストされたyagisan-reportsを使用します。
もっとも簡単に使える方法ですが、パブリックCDNへのアクセスが発生します。

UMD版を自分でホストする

yagisan-reportsモジュールの配置を自分で管理することになる以外は、「パブリックCDNを使う」方法とほぼ同等です。

任意のbundlerを使う

Vite, webpack, esbuildなどの任意のbundlerを使用してyagisan-reportsを組み込みます。
bundlerの設定が必要になる分だけ、手順が煩雑になります。

パブリックCDNを使う

次のような内容のHTMLファイルを作成するだけでセットアップは完了です。

<!DOCTYPE html>
<html lang="ja">
<head>
<meta charset="utf-8">
<script src="https://cdn.jsdelivr.net/npm/yagisan-reports@latest/umd.js" defer></script>
<script type="module">
YagisanReports.globalOptions.workerUrl = 'https://cdn.jsdelivr.net/npm/yagisan-reports@latest/reportworker.js';
YagisanReports.globalOptions.fontUrl = 'https://cdn.jsdelivr.net/npm/yagisan-reports@latest/';
</script>
</head>
</html>

このコードではjsDelivrを使用していますが、UNPKGを使用することも可能です。UNPKGに切り替えたい場合は、 https://cdn.jsdelivr.net/npm の部分を https://www.unpkg.com に置換してください。

UMD版を自分でホストする

npmからyagisan-reportsをインストールします。

npm install yagisan-reports

インストールされた node_modules/yagisan-reports をディレクトリごとHTTPアクセス可能な場所に配置してください。

最後に次のような内容のHTMLファイルを作成してくだい。path/to/yagisan-reports の部分は、配置先のURLを設定してください。

<!DOCTYPE html>
<html lang="ja">
<head>
<meta charset="utf-8">
<script src="path/to/yagisan-reports/umd.js" defer></script>
<script type="module">
YagisanReports.globalOptions.workerUrl = 'path/to/yagisan-reports/reportworker.js';
YagisanReports.globalOptions.fontUrl = 'path/to/yagisan-reports/';
</script>
</head>
</html>

任意のbundlerを使う

npmからyagisan-reportsをインストールします。

npm install yagisan-reports

インストールした node_modules/yagisan-reports に含まれている下記のファイル群は、実行時に必要となるため、HTTPアクセス可能な場所に配置してください。node_modules/yagisan-reports をディレクトリごと配置してしまっても動作上の問題はありません。

  • reportworker.js

  • フォントファイル群（*.ttf, *.json, *.txt）

次にアプリケーション側にyagisan-reportsの初期設定処理を記述します。 globalOptions.workerUrl と globalOptions.fontUrl にそれぞれ前段の手順で配置したファイルへのURLを設定してください。

const YagisanReports = require('yagisan-reports');

YagisanReports.globalOptions.workerUrl = 'path/to/yagisan-reports/reportworker.js';
YagisanReports.globalOptions.fontUrl = 'path/to/yagisan-reports/';

Node.js上で動作させる

Node.jsで帳票出力を行うアプリケーションを作成する場合、特別な手順は不要です。

次のコマンドでnpmパッケージをインストールしてください。

npm install yagisan-reports

Node.jsでは特に初期設定は不要です。npmを読み込むだけで使用できます。

const YagisanReports = require('yagisan-reports');

最小限のコードの記述と要点

// 帳票テンプレートファイルの読み込み
const yrt = await fetch('https://example.com/sample.yrt').then(res => res.arrayBuffer());

// 帳票エンジンのセットアップ
const engine = YagisanReports.createEngine();
const tempalte = await engine.loadTemplate(yrt);
const generator = await tempalte.createPdfReportGenerator();

// 帳票を出力
const report = await generator.generate({
    message: 'hello!\nyagisan-reports!!'
});
const pdf = await report.getContent();

// 必要に応じて、出力した帳票を操作するコードを記述してください。
// download('hello.pdf', pdf);

// 帳票エンジンの破棄
generator.dispose();
tempalte.dispose();
engine.dispose();
createEngine()

  • 帳票エンジンを作成します。このAPIは通常、1回のみの呼び出しに留めるようにしてください。

    • Webブラウザ上で動作させる場合、このAPIを呼び出した分だけWeb Workerが生成されます。

loadTemplate()

  • 帳票テンプレートデータとして ArrayBuffer, Uint8Array, Buffer が入力可能です。

  • 帳票テンプレートの構文に誤りがあった場合、例外がthrowされます。

  • このAPIの初回呼び出し時に、内部でWeb Workerが生成されます（Webブラウザ上で動かす場合のみ）。

createPdfReportGenerator()

  • このAPIをコールすると、内部ではフォントデータの読み込みを行います。

  • フォントデータの読み込み失敗した場合、例外がthrowされます。

generate()

  • 実際に帳票を生成するAPIです。帳票テンプレート内のテンプレート変数に渡すデータを入力します。

dispose()

  • 各APIで作成したリソースは、明示的に dispose() を呼び出すまでメモリー上に確保され続けます。yagisan-reportsを長時間動作し続けるSPAやアプリケーションサーバー等に組み込む場合は、特に注意してください。