version: v2.0

開発を始める

備考

本手順は将来のバージョンで改訂される予定です。

テキストエディタの準備

yagisan-reportsの開発では、XMLを編集できるテキストエディタが必要です。必須ではありませんが、XML Schema（XSD 1.0）に対応しているものを推奨します。

Visual Studio Code をお使いの場合は、次の拡張をインストールすると推奨環境が整います。

XML Language Support by Red Hat

Node.jsのインストール

Node.js 公式サイトからインストーラーをダウンロードしてインストールするか、mise や nvm などのバージョン管理ツールを使用して Node.js をインストールしてください。

使用可能なNode.jsのバージョンについては、動作環境・サポートポリシーをご覧ください。

npmパッケージのインストール

yagisan-reports開発ツール群をインストールします。

npm
pnpm

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

pnpm add @yagisan-reports/sdk
pnpm add -D https://github.com/DenkiYagi/yagisan-reports-devtool

エンタープライズ版を使用する場合は、次のコマンドを使用してください。

pnpm add @yagisan-reports/sdk-enterprise
pnpm add -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/2026.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ファイルから帳票テンプレートファイルを作成します。

npm
pnpm

npx yagisan yrt pack layout.xml -O template.yrt

pnpm exec yagisan yrt pack layout.xml -O template.yrt

アプリケーションへの組み込み

Node.jsで実行する

前述の手順で作成した帳票テンプレートファイルをアクセス可能な場所に配置し、以下のようにコードを記述します。

import { createEngine } from '@yagisan-reports/sdk';
// エンタープライズ版を使用する場合:
// import YagisanReports from '@yagisan-reports/sdk-enterprise';
import { readFile, writeFile } from 'fs/promises';

// 帳票テンプレートファイルの読み込み
const yrt = await readFile('path/to/template.yrt');

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

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

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

const { createEngine } = require('@yagisan-reports/sdk');
// エンタープライズ版を使用する場合:
// const { createEngine } = require('@yagisan-reports/sdk-enterprise');
const { readFile, writeFile } = require('fs/promises');

(async () => {
    // 帳票テンプレートファイルの読み込み
    const yrt = await readFile('path/to/template.yrt');

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

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

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

備考

Node.jsで実行する場合、bundler を使用して yagisan-reports をバンドルすることはできません。

Webブラウザで実行する

Webブラウザ上で帳票出力を行う場合、3つのセットアップ方法があります。

パブリックCDNを使う
- jsDelivr などのパブリックCDNにホストされた yagisan-reports を使用します。
- もっとも手軽な方法ですが、パブリックCDNの利用規約・プライバシーポリシー等に従う必要があります。
UMD版をセルフホストする
- yagisan-reports モジュールの配置を自分で管理すること以外は、「パブリックCDNを使う」方法とほぼ同等です。
任意のbundlerを使う
- Vite、webpack、esbuild などの任意の bundler を使用して yagisan-reports を組み込みます。

パブリックCDNを使うまたは UMD版をセルフホストする

あらかじめ、以下のファイルをHTTPアクセス可能な場所に配置してください。

前述の手順で作成した帳票テンプレートファイル
[セルフホストの場合のみ] yagisan-reports の npm パッケージ（通常は node_modules/@yagisan-reports/sdk）に含まれるリソース群
- umd.js
- reportworker.js
- フォントファイル群（*.ttf, *.glyphdata, *.txt）
- フォントファイル群は全て同一のディレクトリに配置する必要があるため、npmパッケージを丸ごとコピーして配置することを推奨します。

HTMLファイルを作成します。以下の部分は環境に合わせて変更してください。

<script src="... umd.js"> と globalOptions: 以下の例では、パブリックCDNの jsDelivr を使用しています。
- パブリックCDNとして UNPKG を使いたい場合は、 https://cdn.jsdelivr.net/npm の部分を https://www.unpkg.com に置換してください。
- セルフホストする場合は、自身で配置した yagisan-reports リソースのURLを設定してください。
fetch('path/to/template.yrt') : 帳票テンプレートファイルのURL

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

// エンタープライズ版を使用する場合
// YagisanReports.globalOptions.workerUrl = 'https://cdn.jsdelivr.net/npm/@yagisan-reports/sdk-enterprise@2.0.0/reportworker.js';
// YagisanReports.globalOptions.fontUrl = 'https://cdn.jsdelivr.net/npm/@yagisan-reports/sdk-enterprise@2.0.0/';

// 帳票テンプレートファイルの読み込み
const yrt = await fetch('path/to/template.yrt').then(res => res.arrayBuffer());

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

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

// 必要に応じて、出力した帳票をダウンロードするコードを記述してください。
console.log(pdf);

// 帳票エンジンの破棄
generator.dispose();
template.dispose();
engine.dispose();
</script>
</head>
</html>

任意のbundlerを使う

あらかじめ、以下のファイルをHTTPアクセス可能な場所に配置してください。

前述の手順で作成した帳票テンプレートファイル
yagisan-reportsのnpmパッケージ（通常は node_modules/@yagisan-reports/sdk ）に含まれている以下のファイル群
- reportworker.js
- フォントファイル群（*.ttf, *.glyphdata, *.txt）
- npmパッケージを丸ごとコピーして配置することを推奨します。

コードを記述し、任意のbundlerを使用してバンドルします。以下の部分は環境に合わせて変更してください。

globalOptions : yagisan-reportsのnpmパッケージを配置したURL
fetch('path/to/template.yrt') : 帳票テンプレートファイルのURL

import { createEngine, globalOptions } from '@yagisan-reports/sdk';
// エンタープライズ版を使用する場合:
// import { createEngine } from '@yagisan-reports/sdk-enterprise';

// yagisan-reportsリソースのURLを設定
globalOptions.workerUrl = 'https://example.com/path/to/yagisan-reports/reportworker.js';
globalOptions.fontUrl = 'https://example.com/path/to/yagisan-reports/';

// 帳票テンプレートファイルの読み込み
const yrt = await fetch('path/to/template.yrt').then(res => res.arrayBuffer());

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

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

// 必要に応じて、出力した帳票をダウンロードするコードを記述してください。
console.log(pdf);

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

const { createEngine, globalOptions } = require('@yagisan-reports/sdk');
// エンタープライズ版を使用する場合:
// const { createEngine } = require('@yagisan-reports/sdk-enterprise');

// yagisan-reportsリソースのURLを設定
globalOptions.workerUrl = 'https://example.com/path/to/yagisan-reports/reportworker.js';
globalOptions.fontUrl = 'https://example.com/path/to/yagisan-reports/';

(async () => {
    // 帳票テンプレートファイルの読み込み
    const yrt = await fetch('path/to/template.yrt').then(res => res.arrayBuffer());

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

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

    // 必要に応じて、出力した帳票をダウンロードするコードを記述してください。
    console.log(pdf);

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

帳票出力APIの解説・注意点

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() を呼び出すまでメモリー上に確保され続けます。長時間動作させるSPAやサーバー等にyagisan-reportsを組み込む場合は、特に注意してください。

テキストエディタの準備​

Node.jsのインストール​

npmパッケージのインストール​

帳票テンプレートの作成​

アプリケーションへの組み込み​

Node.jsで実行する​

Webブラウザで実行する​

パブリックCDNを使う または UMD版をセルフホストする​

任意のbundlerを使う​

帳票出力APIの解説・注意点​