Введение

Каждая возможность в Aspose.PDF FOSS для TypeScript достигается с помощью двух классов: Document и Page. Document управляет коллекцией страниц и всем, что относится к документу — метаданными, закладками, метками страниц и сохранением/загрузкой — тогда как каждый Page в doc.Pages управляет всем, что относится к конкретной странице: содержимым, аннотациями и полями формы. Как только вы познакомитесь с этими двумя классами, остальная часть интерфейса библиотеки — конверсия, аннотации, формы, безопасность — по сути лишь дополнительные методы тех же двух объектов.

В этом посте более подробно рассматриваются части того базового интерфейса, которые вводный пост лишь упоминает мимоходом: сборка документов из других документов, создание страниц с нуля, добавление дерева закладок для навигации и пометка содержимого для доступности. Все четыре — обычные вызовы методов — без отдельного модуля для импорта, без дополнительных зависимостей, кроме самого пакета @asposefoss/pdf.

Это операции, которые появляются, когда PDF-конвейер выходит за рамки «открыть один файл, изменить его, сохранить»: объединение отчетов из нескольких источников в один документ, программная генерация страниц вместо начала с шаблона и обеспечение навигации и доступности результата, а не только визуальной корректности.

Что включено

Сборка и реорганизация документов

Document.Split() разбивает документ на новый одностраничный Document для каждой страницы, в порядке страниц. Document.ExtractPages() копирует заданный набор нумераций страниц, начинающихся с 1, в новый автономный Document, в указанном порядке — одну и ту же страницу можно повторять. Страницы из одного документа также можно копировать в другой: Document.Append() копирует каждую страницу исходного документа в конец целевого, а Document.InsertPage() копирует одну страницу между документами в конкретную позицию, начинающуюся с 1.

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

const report = Document.OpenFile('report.pdf');

const parts = report.Split();                      // one Document per page
const chapter = report.ExtractPages([3, 4, 5]);     // subset (1-based, repeats allowed) as a new Document

const cover = Document.OpenFile('cover.pdf');
report.InsertPage(1, cover.Pages[0]);               // copy a single page across documents
report.Append(chapter);                             // copy chapter's pages onto report

report.WriteTo('assembled.pdf');

Несколько документов также можно объединить в один единственным вызовом Document.Merge(), который создаёт новый Document из копий каждой страницы каждого переданного ему документа, последовательно.

Создание страниц с нуля

Document.New() создаёт документ из ничего: ноль страниц, если формат опущен, или одну пустую страницу заданного PageFormat, если он указан. Дополнительные пустые страницы получаются из Document.AddPage(), который также принимает PageFormat (или существующий Page для копирования его размеров). Текст наносится на страницу с помощью Page.AddText(), размещённого в точке (x, y) в пользовательском пространстве PDF.

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

const doc = Document.New(PageFormat.A4);          // one blank A4 page
doc.Pages[0].AddText('Hello', 72, 720, { fontSize: 14 });
doc.AddPage(PageFormat.A4.landscape());           // append more as you go
doc.WriteTo('scratch.pdf');

Закладки и навигация по документу

Оглавление документа (панель закладок, которую большинство PDF-читалок отображает рядом со страницей) читается с помощью Document.GetOutlines() и полностью заменяется на Document.SetOutlines(), каждый из которых работает с деревом значений OutlineItem. Каждый OutlineItem содержит Title, пункт назначения Dest и, при необходимости, Children для вложенных записей, а также подсказки отображения, такие как Open (развёрнутый по умолчанию) и Bold.

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

const items: OutlineItem[] = [
  { Title: 'Introduction', Dest: { name: 'intro' } },
  {
    Title: 'Chapters',
    Open: true,
    Children: [
      { Title: 'Chapter 1', Dest: { name: 'ch1' } },
      { Title: 'Chapter 2', Dest: { name: 'ch2' } },
    ],
  },
];
doc.SetOutlines(items);

Названия пунктов назначения в таком виде ({ name: 'intro' }) разрешаются через таблицу именованных пунктов назначения документа, которой Document.GetNamedDestinations() и Document.SetNamedDestination() управляют напрямую, когда закладка должна указывать на пункт назначения, не привязанный к содержимому страницы.

Структурированный текст и маркировка доступности

Document.GetStructTree() возвращает логическое дерево структуры документа (или null, если документ не помечен), а Document.CreateStructTree() создаёт его, помечая документ как Tagged. Как только дерево структуры существует, Page.GetStructuredText() возвращает текст страницы в виде значений TextBlock — позиционированных фрагментов, уже сгруппированных в строки и блоки, похожие на абзацы, — которые служат входными данными для ручного прохода маркировки: обход блоков, определение, какие из них являются заголовками, а какие — основным текстом, и добавление соответствующих элементов в дерево.

function handTagPage(doc: Document, page: Page, heading: string): void {
  const root = doc.GetStructTree();
  if (!root) throw new Error('handTagPage: the document is not tagged yet');
  for (const block of page.GetStructuredText()) {
    const text = block.text.trim();
    if (text.length === 0) continue;
    const el = root.Append(text.startsWith(heading) ? 'H2' : 'P');
    el.MarkContent(page, block.quad);
  }
}

Дерево структур с тегами — это фундамент, на котором строятся последующие функции: семантический HTML экспорт переоформляет его вместо того, чтобы возвращаться к простому эвристическому макету, а Document.ValidatePdfUa() проверяет документ относительно подмножества стандарта доступности PDF/UA, которое зависит от наличия тегов.

Быстрый старт

Установите пакет, затем откройте документ, извлеките и объедините подмножество его страниц, и сохраните результат:

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
import { Document } from '@asposefoss/pdf';

const doc = Document.OpenFile('report.pdf');

const chapter = doc.ExtractPages([3, 4, 5]);   // subset (1-based, repeats allowed) as a new Document
const cover = Document.OpenFile('cover.pdf');

doc.InsertPage(1, cover.Pages[0]);             // copy a single page across documents
doc.Append(chapter);                           // copy chapter's pages onto doc

doc.WriteTo('assembled.pdf');

Поддерживаемые форматы

ФорматРасширениеЧтениеЗапись
PDFpdf✓✓
Markdownmd✓✓
SVGsvg✓✓
TIFFtiff✓✓
DOCXdocx—✓
HTMLhtml—✓
PNGpng—✓
EPUBepub—✓

Открытый исходный код и лицензирование

Aspose.PDF FOSS для TypeScript выпускается под лицензией MIT, исходный код опубликован на GitHub. Нет водяного знака оценки, ограничений использования или отдельного лицензионного файла для управления, и библиотеку можно использовать в коммерческих продуктах без роялти.

В настоящее время пакет находится в версии 0.1.0, что отражает активную раннюю разработку. Node.js (>=22) — единственное требование к среде выполнения, и у пакета нет других сторонних зависимостей.

Начало работы

Связанные ресурсы