Как конвертировать 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() в режиме по умолчанию (semantic) переоформляет содержимое из дерева структуры в заголовки и абзацы; передайте { 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() и так далее) на этом подмножестве.