TypeScriptでPDFドキュメントを変換する方法

このガイドでは、Aspose.PDF FOSS for TypeScript を使用して PDF コンテンツを他の形式に変換する方法を示します。Page は単一ページを SVG またはラスタ画像としてエクスポートし、Document はファイル全体を HTML、Markdown、または DOCX としてエクスポートでき、ドキュメントを PDF/A に検証・変換することもできます。Node.js 22 以降が必要です。

ステップバイステップガイド

ステップ 1: パッケージをインストールする

git clone https://github.com/aspose-pdf-foss/Aspose.PDF-FOSS-for-TypeScript.git
cd Aspose.PDF-FOSS-for-TypeScript
npm install
npm run build

パッケージがインストールされたら、Document クラスを新しい TypeScript ファイルにインポートしてインストールを確認してください — この行はエラーなく解決されるはずです：

import { Document } from '@asposefoss/pdf';

ステップ 2: 必要なクラスをインポートする

ファイルを開くには Document をインポートします。以下で使用する変換メソッドは返された Document と Page のインスタンス上で直接呼び出すので、追加のインポートは不要です：

import { Document } from '@asposefoss/pdf';

ステップ 3: ページを SVG またはラスタ画像に変換する

Page.ToSvg() は単体の <svg> 文字列を返します。Page.ToImage() はページをラスタバイトにレンダリングします。scale は PDF のネイティブ 72 DPI に対する相対値なので、scale: 2 は 144 DPI でレンダリングされます：

import { Document } from '@asposefoss/pdf';

const doc = Document.OpenFile('input.pdf');
const svg = doc.Pages[0].ToSvg(); // standalone <svg> string
const png = doc.Pages[0].ToImage({ scale: 2 }); // Uint8Array of PNG bytes @144 DPI

ステップ 4: ドキュメントを HTML または Markdown に変換する

デフォルト（セマンティック）モードの Document.ToHtml() は、構造ツリーから見出しや段落へコンテンツをリフローします。代わりに各ページを配置された SVG と絶対配置テキストとして再現するには { mode: 'fixed' } を渡します。Document.ToMarkdown() はドキュメント全体の GFM Markdown を生成します：

const semanticHtml = doc.ToHtml(); // reflowable markup, all pages
const fixedHtml = doc.ToHtml({ mode: 'fixed', fonts: 'embed' }); // positioned, fonts embedded
const markdown = doc.ToMarkdown(); // GFM Markdown, all pages

セマンティックモードは Document.GetStructTree() / Document.CreateStructTree() によって構築された構造ツリーを読み取ります。タグが付いていないドキュメントではヒューリスティックな本文にフォールバックし、エクスポート時に見出し構造が失われます。

ステップ 5: ドキュメントを DOCX に変換する

Document.ToDocx() はコンテンツがリフローされ、画像が内部にパッケージされた .docx バイトを返します。リフローせずに各ページ固有の固定ジオメトリを保持するには { mode: 'textbox' } を渡します：

const docx = doc.ToDocx(); // .docx bytes, reflowed, images in the package
const fixed = doc.ToDocx({ mode: 'textbox' }); // .docx keeping each page's own geometry

ステップ6: PDF/A に検証して変換する

Document.ValidatePdfA(level)、Document.ValidatePdfX(level)、およびDocument.ValidatePdfUa()は、文書が指定された標準に合格しているかを記述するValidationReportを返します。Document.ConvertToPdfA(level, opts)は、適用された修正と未解決の問題を列挙したConversionReportを返します。ライブ文書を未変換のまま保存しなければならない場合は、Document.ExtractPages()コピーで変換を実行してください：

const report = doc.ValidatePdfA('2b');
console.log(report.Passed);

const copy = doc.ExtractPages(doc.Pages.map((_, i) => i + 1));
const conversion = copy.ConvertToPdfA('2b');
console.log(conversion.applied.length, conversion.unresolved.length, conversion.passed);
copy.Save();

一般的な問題と修正策

Document.ToHtml() 見出し構造が失われます。 セマンティックモードは構造ツリーをたどるため、タグ付けパスの後に実行する必要があります — いずれか Document.AutoTag() または手動で作成したタグ付けを介して StructTreeRoot.Append(). ToHtml() ヒューリスティックな本文にフォールバックします、条件は GetStructTree() returns null.

ConvertToPdfA() 変換せずに保持したいファイルを変更してしまいます。 変換は、以下からのコピーで実行してください Document.ExtractPages()、その後コピーを別々に保存します — ConvertToPdfA() 呼び出されたドキュメントを変更します。

ValidatePdfA() 最初の実行時に失敗を報告します。 一般的な原因は、埋め込まれていない標準フォントと欠落した /OutputIntent — 確認 report.Passed そして、個々のルール結果を確認して、どの条件が満たされていないかを確認します。

Page.ToImage() 出力が低解像度に見えます。 scale は72 DPI を基準としています。上げてください（例として { scale: 2 } 144 DPI）で印刷品質の出力を得られます。

よくある質問

セマンティックと固定 HTML エクスポートの違いは何ですか？

セマンティックモードは、文書の構造ツリーから内容を再配置し、任意の幅のブラウザでも読みやすいマークアップに変換します。固定モードは、各ページを配置された SVG と絶対位置指定のテキストとして再現し、元のレイアウトと完全に一致させます。

`Document.ToDocx()` は元のページレイアウトを保持しますか？

デフォルトでは ToDocx() はコンテンツを再配置します。代わりに { mode: 'textbox' } を渡すと、各ページ固有の固定ジオメトリを保持します。

変換する前に、ドキュメントが PDF/A に適合しているかどうかを確認するにはどうすればよいですか？

Document.ValidatePdfA(level) を呼び出し（例: '2b'）、返される ValidationReport を確認してください — これにより、ドキュメントを変更せずに現在の状態が報告されます。

ページのサブセットだけを変換できますか？

はい — 最初に Document のサブセットを Document.ExtractPages() で構築し、次にそのサブセットに対して変換メソッド (ToHtml()、ToDocx()、ConvertToPdfA()、など) を呼び出します。