Як конвертувати PDF-документи у TypeScript

У цьому посібнику показано, як конвертувати вміст PDF у інші формати за допомогою Aspose.PDF FOSS для TypeScript. 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 відноситься до рідного 72 DPI PDF, тому 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() у своєму режимі за замовчуванням (семантичному) переоформлює вміст зі структурного дерева у заголовки та абзаци; передайте { mode: 'fixed' }, щоб замість цього відтворити кожну сторінку у вигляді позиціонованого SVG та абсолютного тексту. 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() і так далі) для цієї підмножини.