開発を始める
本手順は将来のバージョンで改訂される予定です。
テキストエディタの準備
yagisan-reportsの開発では、XMLを編集可能なテキストエディタが必要です。 必須ではありませんが、XML Schema(XSD 1.0)に対応していることが推奨となります。
Visual Studio Code をお使いの場合は、次の拡張をインストールすると推奨環境が整います。
リリース時期は未定ですが、Visual Studio Code用のyagisan-reports拡張を開発中です。
Node.jsのインストール
Node.js 公式サイト からインストーラーをダウンロードしてインストールするか、 volta や nvm などのバージョン管理ツールを使用して、Node.jsをインストールしてください。
yagisan-reportsがサポートしているNode.jsのバージョンは Maintenance LTS 以降です。
特に理由がなければ、最新の LTS バージョンの使用を推奨します。
Node.jsのバージョンについては、 Node.js公式のリリース情報 を参照してください。
npmパッケージのインストール
yagisan-reports開発ツール群をインストールします。
- 通常
- エンタープライズ版を使用する場合
npm install @yagisan-reports/sdk
npm install -D https://github.com/DenkiYagi/yagisan-reports-devtool
npm install @yagisan-reports/sdk-enterprise
npm install -D https://github.com/DenkiYagi/yagisan-reports-devtool
yagisan-reports-devtoolは将来、npmレジストリで公開する予定です。
帳票テンプレートの作成
以下のXMLをコピーして layout.xml として保存します。
文字エンコーディングはUTF-8を使用してください。
<LinearLayout
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="https://schemas.yagisan.app/2025.1/layout.xsd"
size="A4"
orientation="portrait"
>
<LayoutBody>
<Text size="30">${message}</Text>
<Spacer height="30" />
<Text size="12">このPDFはyagisan-reportsによって作成されました</Text>
</LayoutBody>
</LinearLayout>
yagisanコマンドを使って、XMLファイルから帳票テンプレートファイルを作成します。
npx yagisan yrt pack layout.xml -O template.yrt
アプリケーションへの組み込み
Webブラウザで実行する
Webブラウザ上で帳票出力を行うアプリケーションを作成する場合、3つのセットアップ方法があります。
- パブリックCDNを使う
- jsDelivr等のパブリックCDNにホストされたyagisan-reportsを使用します。
- もっとも簡単に使える方法ですが、パブリックCDNの利用規約・プライバシーポリシーに従う必要があります。
- UMD版を自分でホストする
- yagisan-reportsモジュールの配置を自分で管理することになる以外は、「パブリックCDNを使う」方法とほぼ同等です。
- 任意のbundlerを使う
- Vite, webpack, esbuildなどの任意のbundlerを使用してyagisan-reportsを組み込みます。
パブリックCDNを使う
以下の内容のHTMLファイルを作成してください。
- 通常
- エンタープライズ版を使用する場合
<!DOCTYPE html>
<html lang="ja">
<head>
<meta charset="utf-8">
<script src="https://cdn.jsdelivr.net/npm/@yagisan-reports/sdk@latest/umd.js" defer></script>
<script type="module">
YagisanReports.globalOptions.workerUrl = 'https://cdn.jsdelivr.net/npm/@yagisan-reports/sdk@latest/reportworker.js';
YagisanReports.globalOptions.fontUrl = 'https://cdn.jsdelivr.net/npm/@yagisan-reports/sdk@latest/';
</script>
</head>
</html>
<!DOCTYPE html>
<html lang="ja">
<head>
<meta charset="utf-8">
<script src="https://cdn.jsdelivr.net/npm/@yagisan-reports/sdk-enterprise@latest/umd.js" defer></script>
<script type="module">
YagisanReports.globalOptions.workerUrl = 'https://cdn.jsdelivr.net/npm/@yagisan-reports/sdk-enterprise@latest/reportworker.js';
YagisanReports.globalOptions.fontUrl = 'https://cdn.jsdelivr.net/npm/@yagisan-reports/sdk-enterprise@latest/';
</script>
</head>
</html>
このコードではjsDelivrを使用していますが、UNPKGを使用することも可能です。
UNPKGに切り替えたい場合は、 https://cdn.jsdelivr.net/npm の部分を https://www.unpkg.com に置換してください。
UMD版を自分でホストする
yagisan-reportsのnpmパッケージ（通常は node_modules/yagisan-reports ）をディレクトリごと、HTTPアクセス可能な場所に配置してください。
次に、以下の内容のHTMLファイルを作成してください。
path/to/yagisan-reports の部分は、先ほどの手順で配置したURLに置換してください。
<!DOCTYPE html>
<html lang="ja">
<head>
<meta charset="utf-8">
<script src="https://example.com/path/to/yagisan-reports/umd.js" defer></script>
<script type="module">
YagisanReports.globalOptions.workerUrl = 'https://example.com/path/to/yagisan-reports/reportworker.js';
YagisanReports.globalOptions.fontUrl = 'https://example.com/path/to/yagisan-reports/';
</script>
</head>
</html>
任意のbundlerを使う
yagisan-reportsは任意のbundlerを使用してバンドルすることができます。
ただし、yagisan-reportsのnpmパッケージ（通常は node_modules/yagisan-reports ）に含まれている以下のファイル群は、実行時に必要となるため、HTTPアクセス可能な場所に配置してください。
reportworker.js- フォントファイル群（
*.ttf,*.glyphdata,*.txt）
次に、アプリケーション側にyagisan-reportsのセットアップコードを記述します。
path/to/yagisan-reports の部分は、先ほどの手順で配置したURLに置換してください。
- 通常
- エンタープライズ版を使用する場合
const YagisanReports = require('@yagisan-reports/sdk');
YagisanReports.globalOptions.workerUrl = 'https://example.com/path/to/yagisan-reports/reportworker.js';
YagisanReports.globalOptions.fontUrl = 'https://example.com/path/to/yagisan-reports/';
const YagisanReports = require('@yagisan-reports/sdk-enterprise');
YagisanReports.globalOptions.workerUrl = 'https://example.com/path/to/yagisan-reports/reportworker.js';
YagisanReports.globalOptions.fontUrl = 'https://example.com/path/to/yagisan-reports/';
Node.jsで実行する
Node.jsで帳票出力を行うアプリケーションを作成する場合、特別な手順は不要です。 npmを読み込むだけで使用できます。
- 通常
- エンタープライズ版を使用する場合
const YagisanReports = require('@yagisan-reports/sdk');
const YagisanReports = require('@yagisan-reports/sdk-enterprise');
帳票テンプレートファイルの配置
前述の手順で作成しておいた帳票テンプレートファイル（template.yrt）を、アクセス可能な場所に配置してください。
帳票出力コードの記述
Webブラウザ、Node.jsのいずれの場合も、帳票出力コードは同じです。
path/to/template.yrt の部分は、配置した帳票テンプレートファイルのURLまたはパスに置換してください。
// 帳票テンプレートファイルの読み込み
const yrt = await fetch('https://example.com/path/to/template.yrt').then(res => res.arrayBuffer());
// Node.jsの場合は次のように読み込みます。
// const fs = require('fs/promises');
// const yrt = await fs.readFile('path/to/template.yrt');
// 帳票エンジンのセットアップ
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()- 実際に帳票PDFを出力します。帳票テンプレートに渡すデータを入力します。
- このAPIは何度呼び出しても構いません。
dispose()- インスタンスを破棄し、リソースを開放します。
- 各APIで作成したリソースは、明示的に
dispose()を呼び出すまでメモリー上に確保され続けます。 yagisan-reportsを長時間動作し続けるSPAやサーバー等に組み込む場合は、特に注意してください。