Основні API документу та сторінки в Aspose.PDF FOSS for TypeScript

Вступ

Кожну можливість у 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');

Підтримувані формати

Відкритий код & ліцензування

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

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

Початок роботи

• Початок роботи
• Посібник розробника
• Статті БЗ
• API Reference

Пов’язані ресурси

• Aspose.PDF Enterprise Product Family
• Aspose.PDF — Enterprise Blog