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

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やアプリケーションサーバー等に組み込む場合は、特に注意してください。