jsPDFの最新バージョンへ移行するための実践ガイド

JavaScriptでPDFを生成する際によく利用されるライブラリ「jsPDF」は、近年大きな変更が加えられました。特にv2.x以降ではAPI設計が刷新され、モジュール構成やフォント管理方法が大きく進化しています。既存プロジェクトで古いバージョンを使っている場合、コンソールに警告が出たり、一部機能が動作しなくなることがあります。この記事では、旧バージョンから最新版（例：2.5.1以上）へのスムーズな移行手順を解説します。

主な変更点の比較

まず、古い使い方と新しいパターンの違いを表で整理します。

カテゴリ	旧バージョン（v1.x）	新バージョン（v2.x+）
インポート方法	`window.jsPDF` グローバルオブジェクト	ES Modules / UMD形式での名前付きエクスポート
初期化パラメータ	位置引数： `new jsPDF('p', 'mm', 'a4')`	オプションオブジェクト： `new jsPDF({ orientation: 'portrait' })`
フォント登録	`addFont()` で直接指定	VFS経由：`addFileToVFS()` + `addFont()`
拡張機能	プラグインJSファイルを別途読み込み	動的インポートまたはバンドラーでオンデマンド読み込み

これらの変更により、コードの保守性・バンドルサイズ・国際化対応力が向上しています。

移行前の準備

本番環境に影響を与えないよう、以下のステップで準備を行いましょう。

現在のバージョンを確認：
npm list jspdf または package.json をチェック
Gitで新しいブランチを作成（例：git checkout -b upgrade-jspdf）
バックアップまたは差分確認用に現状のコードを保存

移行の4つの主要ステップ

1. インポート方式の変更

従来のグローバル参照から、モジュール指向に切り替えます。

// 古いやり方（非推奨）
var doc = new jsPDF();

// 新しい方法（ES Modules）
import { jsPDF } from 'jspdf';
const doc = new jsPDF();

// ブラウザグローバルでも同様
const { jsPDF } = window.jspdf;
const doc = new jsPDF();

2. コンストラクタの引数形式の更新

文字列や単位の順序に依存しない、オブジェクトベースの初期化に変更します。

// v1.x 風
const doc = new jsPDF('landscape', 'pt', 'letter');

// v2.x+
const doc = new jsPDF({
  orientation: 'landscape',
  unit: 'pt',
  format: 'letter',
  compress: true // 圧縮オプションも追加可能
});

3. フォントの扱い方の変更

日本語や中国語などの特殊フォントを使う場合、仮想ファイルシステム（VFS）に登録する必要があります。

async function setupCustomFont() {
  const fontUrl = '/assets/fonts/rounded-mplus-1c-regular.ttf';
  const fontArrayBuffer = await fetch(fontUrl).then(res => res.arrayBuffer());
  
  // VFSに登録
  doc.addFileToVFS('mplus.ttf', fontArrayBuffer);
  // フォントとして追加
  doc.addFont('mplus.ttf', 'MPlus', 'normal');
  // 使用開始
  doc.setFont('MPlus');
}

4. 画像挿入APIの拡張

画像の配置がより柔軟になり、回転や品質設定が可能になりました。

// 古い形式
doc.addImage(imgData, 'JPEG', 10, 10, 80, 60);

// 新しいオブジェクト形式
doc.addImage({
  imageData: imgData,
  format: 'JPEG',
  x: 10,
  y: 10,
  width: 80,
  height: 60,
  rotationDegrees: 90, // 回転も可能
  opacity: 0.9
});

よくある問題と対処法

「jsPDF is not defined」エラー

これはインポートミスが原因です。特にTypeScriptやWebpack環境では要注意。

// ❌ 間違ったインポート
import jsPDF from 'jspdf'; 

// ✅ 正しい方法
import { jsPDF } from 'jspdf';

日本語／中国語が豆腐化（□）になる

カスタムフォントが正しく読み込まれていない可能性があります。上記のVFS登録手順を必ず実施してください。また、フォントファイルのCORS設定にも注意が必要です。

`html()` メソッドが見つからない

HTML描画機能は独立したサブモジュールとなりました。別途インストールが必要です。

npm install jspdf-html html2canvas dompurify --save

使用時は動的に読み込みます。

const { html } = await import('jspdf-html');
await html(doc, document.getElementById('print-area'));

移行後の最適化アドバイス

コード分割：PDF生成ロジックをdynamic importで遅延読み込みし、初期ロードを軽量化
必要最小限のインポート：大規模アプリでは特定ページでのみ導入
TypeScript活用：型定義ファイルが充実しているため、IDE補完や静的チェックが有効
パフォーマンス計測：Performance APIを使って生成時間を比較。特に複数ページのPDFで改善が顕著

今後の展望

jsPDFチームはWebAssemblyを活用した高速レンダリングエンジンの開発を進めています。将来的にはSVGや複雑なレイアウトの処理速度がさらに向上することが期待されます。GitHubリポジトリの公式ページで開発動向を追うことができます。

また、examplesディレクトリには50以上のサンプルが含まれており、basic.htmlやtwo-page.jsなどは基本的なユースケースの参考になります。

タグ: jsPDF PDF生成 javascript TypeScript モジュール化

6月16日 20:19 投稿

異端開発室

jsPDFの最新バージョンへ移行するための実践ガイド