利用方法

セットアップ手順

1. kintone アプリ設定で外部 JavaScript URL を追加

アプリ設定 → JavaScript / CSS でカスタマイズ → URL で指定

以下の 2 つの URL をこの順番で追加してください:

1. https://gariban.monosus.party/js/gariban-vendor.min.js コピー
   pdf-lib・fontkit・JSZip を1本に同梱
2. https://gariban.monosus.party/js/gariban-pdf.min.js コピー
   ランタイム本体

gariban-vendor.min.js に JSZip も含むため「個別PDF一括出力」もそのまま使えます。 ライブラリは外部CDNではなく配信元 Worker に固定バージョンで同梱（社内CSP/プロキシ対策・サプライチェーン安全性のため）。 旧来の4本構成（pdf-lib / fontkit / jszip / gariban-pdf）も後方互換で利用できます。

2. プラグイン ID の設定（オプション）

デフォルトの PLUGIN_ID (jmagmddpolfhhdapbcjapdianmolmbob) 以外を使う場合:

JavaScript カスタマイズ → ファイルで指定 で以下のコードを追加:

(function() {
  'use strict';
  window.KINTONE_PDF_PLUGIN_ID = 'YOUR_PLUGIN_ID_HERE';
})();

3. プラグイン設定

「拡張設定プラグイン」をインストールし、PDF 出力設定 JSON を設定します。

プラグイン ID は window.KINTONE_PDF_PLUGIN_ID で設定した値と一致させてください。

4. 設定 JSON の構造

プラグイン設定で以下の構造の JSON をアップロードします。出力モードは3種類あります:

• detail — 詳細画面から単一レコードのPDFを出力。JSZip を読み込んでいれば、一覧画面で個別PDF一括出力（ZIP）ボタンも表示されます
• index — 一覧画面の全レコードを1つのPDFにまとめて出力（行ピッチで繰り返し配置）
• combined — ヘッダー（mappings）は先頭レコード、一覧行（indexMappings）は全レコードを1つのPDFに複合出力

必要なモードだけ設定すれば OK です。

{
  "pdfPositioner": {
    "detail": {
      "templateUrl": "https://example.com/templates/invoice.pdf",
      "fontUrl": "https://example.com/fonts/NotoSansJP-Regular.ttf",
      "outputFileName": "invoice_{レコード番号}.pdf",
      "mappings": [
        {
          "fieldCode": "取引先名",
          "page": 0,
          "x": 50,
          "y": 30,
          "fontSize": 12,
          "align": "left"
        }
      ],
      "subtables": [
        {
          "tableCode": "明細テーブル",
          "page": 0,
          "startY": 80,
          "rowPitch": 8,
          "columns": [
            { "fieldCode": "品名", "x": 20, "fontSize": 10 },
            { "fieldCode": "金額", "x": 150, "fontSize": 10, "align": "right" }
          ]
        }
      ],
      "relatedRecords": []
    },
    "index": {
      "templateUrl": "https://example.com/templates/list.pdf",
      "fontUrl": "https://example.com/fonts/NotoSansJP-Regular.ttf",
      "outputFileName": "list_{TODAY}.pdf",
      "mappings": [
        {
          "fieldCode": "注文番号",
          "page": 0,
          "x": 20,
          "y": 50,
          "fontSize": 10
        }
      ],
      "rowPitch": 10,
      "rowCount": 0
    },
    "combined": {
      "templateUrl": "https://example.com/templates/report.pdf",
      "fontUrl": "https://example.com/fonts/NotoSansJP-Regular.ttf",
      "outputFileName": "report_{TODAY}.pdf",
      "mappings": [ ... ],
      "indexMappings": [ ... ],
      "rowPitch": 10
    }
  }
}

各フィールドの詳細（型・必須/任意・デフォルト値など）は JSON Schema を、レイアウトの振る舞い（overflow・座標系・フォーマット・モード別の描画ロジック等）は Behavior Guide を参照してください。

メリット

トラブルシューティング

一般的なチェックポイント

スクリプトが読み込まれない?

ブラウザコンソールで CORS エラーを確認してください。Workers の CORS ヘッダーが有効か確認。

"PDFLib is not defined" エラー?

pdf-lib と fontkit の URL が gariban-pdf.min.js の前に読み込まれているか確認してください。

設定が見つからない?

window.KINTONE_PDF_PLUGIN_ID がプラグイン ID と一致しているか確認。設定しない場合はデフォルト値を使用します。

PDF がダウンロードされない?

1. ブラウザコンソールでエラーを確認
2. プラグイン設定 JSON の構造が正しいか確認
3. templateUrl と fontUrl が正しい URL か確認

エラーコード別の対処方法

PDF 出力時に表示されるエラーダイアログ右下の「ヘルプを開く」ボタンから、該当する項目に直接ジャンプできます。

PLUGIN_CONFIG_MISSING — プラグイン設定が見つからない

1. kintone アプリ設定 → プラグイン から、Gariban Printer（または拡張設定プラグイン）が有効になっているか確認
2. プラグインの設定画面で、設定 JSON が保存されているか確認
3. アプリを保存してデプロイ済みか確認

CONFIG_JSON_INVALID — 設定 JSON の形式が不正

1. プラグイン設定の JSON 文字列が有効な JSON か（カンマ・引用符の閉じ忘れに注意）
2. 必須プロパティ templateUrl、fontUrl、mappings が存在するか
3. JSON Linter（jsonlint.com など）で構文チェック

TEMPLATE_FETCH_FAILED — テンプレートPDFの取得失敗

1. ブラウザのアドレスバーに templateUrl を貼り付けて、PDF が直接ダウンロードできるか確認
2. URL が https:// で始まっているか
3. 配信サーバー側で CORS（Access-Control-Allow-Origin）が許可されているか
4. kintone のドメインからアクセスできるか（社内ファイアウォール等の制限がないか）

FONT_FETCH_FAILED — フォントファイルの取得失敗

1. fontUrl の URL が有効な TTF/OTF ファイルを指しているか
2. https:// で始まっているか（kintone は HTTPS 必須）
3. 配信サーバーの CORS 設定（フォントファイルに対する Access-Control-Allow-Origin）
4. コンソールに表示される失敗 URL（[PDF Export] Related URL:）を確認

CONFIG_URL_INVALID — 設定 URL の形式が不正

1. JSON 内の templateUrl / fontUrl が https:// で始まっているか
2. URL に余分な空白や全角文字が混入していないか
3. パスやファイル拡張子（.pdf / .ttf など）が正しいか

PDF_UPLOAD_FAILED — PDFのアップロード失敗

1. kintone アプリの「アクセス権」で、対象ユーザーに「ファイル添付」「レコード編集」権限が付与されているか
2. アップロード先フィールドが存在し、フィールドコードが正しいか
3. テスト環境（未公開）にしか存在しないフィールドにアップロードしようとしていないか（黄色いバナーが出ていないか）
4. ネットワーク接続を確認

RECORD_UPDATE_FAILED — レコード更新失敗

1. 対象レコードに対する「編集」権限があるか
2. アップロード先フィールドが「閲覧のみ」「無効」になっていないか
3. レコードがプロセス管理で編集禁止のステータスになっていないか

UNKNOWN / その他のエラー

予期しないエラーが発生した場合は、ブラウザの開発者ツール（F12）の Console タブで詳細を確認してください。サポートに問い合わせる際は、表示されたエラーコードとバージョン（例: v0.2.0）を併せてお伝えください。

従来の方法に戻す場合

外部スクリプト方式で問題が発生した場合:

1. kintone アプリ設定から Workers URL を削除
2. gariban-pdf.js を直接 kintone にアップロード（ファイルで指定）
3. プラグイン設定はそのまま使用可能

バージョン固定

デフォルトの URL（/js/gariban-pdf.min.js）は常に最新版を配信します。破壊的変更の影響を避けたい場合は、バージョン番号付き URL で特定バージョンに固定できます。

バージョン固定 URL の例

現在のバージョンは window.PDF_POSITIONER_VERSION で確認できます。ブラウザコンソールで以下を実行してください:

console.log(window.PDF_POSITIONER_VERSION); // => "0.1.0"

URL リファレンス