Ядро API

Основной API

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

Жизненный цикл документа

Document.OpenFile() открывает PDF из пути к файлу; Document.Open() принимает Uint8Array в памяти. Страницы можно просматривать и редактировать на месте, а Document.WriteTo() записывает результат обратно — при желании с компрессией xref-stream и object-stream.

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

// Open from disk (or Document.Open(uint8array) for in-memory data)
const doc = Document.OpenFile('input.pdf');

// Inspect and edit pages
const pages = doc.Pages;
console.log(pages.length);
pages[0].Rotate = 90;
doc.RemovePage(2);                 // 1-based page number
doc.Reorder([3, 1, 2]);

// Metadata
doc.SetMetadata({ title: 'Report', author: 'Jane', custom: { Dept: 'R&D' } });

// Save
doc.WriteTo('output.pdf');         // or: const bytes = doc.Save();
doc.WriteTo('small.pdf', { compressed: true }); // xref stream + object streams

Разделение, объединение и извлечение страниц

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

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

docA.Append(docB);                               // copy all of docB's pages onto docA
docA.InsertPage(1, docB.Pages[0]);               // copy a single page across documents

Создание нового документа

Document.New() начинает пустой документ в заданном PageFormat. Page.AddText() размещает позиционированный текст, а Document.AddPage() добавляет дальнейшие страницы, включая повернутый формат, такой как PageFormat.A4.landscape().

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');

Водяные знаки и номера страниц

Page.AddText() также поддерживает вращение, цвет и непрозрачность, что достаточно для отображения номера страницы и диагонального водяного знака без каких-либо дополнительных классов.

const doc = Document.OpenFile('in.pdf');
const page = doc.Pages[0];

// Page number, right-aligned near the bottom-right corner.
const w = page.Rect[2] - page.Rect[0];
page.AddText(`Page ${page.Number}`, w - 40, 20, { fontSize: 10, align: 'right' });

// Semi-transparent diagonal watermark, centered on the page.
page.AddText('DRAFT', page.Rect[2] / 2, page.Rect[3] / 2, {
  font: 'Times-Bold', fontSize: 64, color: [0.7, 0.7, 0.7], opacity: 0.4, rotate: 45, align: 'center',
});

doc.WriteTo('out.pdf');

Инспекция потока содержимого

parseContentStream() декодирует необработанный поток /Contents страницы в список пар оператор/операнд, а serializeContentStream() преобразует отредактированный список операторов обратно в байты.

import { parseContentStream, serializeContentStream } from '@asposefoss/pdf';

const ops = parseContentStream(doc.Pages[0].Contents);
// ops: { operator: string, operands: PdfObject[], inlineImage?: {...} }[]
for (const op of ops) {
  if (op.operator === 'Tj') console.log('text op:', op.operands);
}
const bytes = serializeContentStream(ops);       // round-trips operators + operands

Многоколоночный поток текста

Page.AddTextBlock() размещает длинную строку текста в прямоугольной области и возвращает любой текст, который не поместился, что можно передать во второй вызов для продолжения потока в другую колонку.

const rest = page.AddTextBlock(longText, [72, 600, 200, 150], {
  font: 'Times-Roman', fontSize: 11, align: 'justify', valign: 'top', leading: 14,
});
if (rest) page.AddTextBlock(rest, [300, 600, 200, 150]); // continue into a 2nd column

Советы и лучшие практики

• Используйте Document.OpenFile() для файловых путей и Document.Open() для данных Uint8Array в памяти.
• Номера страниц, передаваемые в методы, такие как RemovePage() и ExtractPages(), нумеруются с 1, в то время как doc.Pages — массив с нулевой базой.
• Передайте { compressed: true } в Document.WriteTo(), чтобы включить сжатие xref-stream и object-stream при выводе.
• Document.ExtractPages() принимает повторяющиеся номера страниц, поэтому одна и та же исходная страница может встречаться в результате более одного раза.
• Прочитайте page.Rect, чтобы вычислять позиции относительно фактической ширины и высоты страницы, а не задавать координаты вручную.

Распространённые проблемы

FAQ

Принимает ли Document.Open() как пути к файлам, так и данные в памяти?

Document.OpenFile() открывается из пути к файлу; Document.Open() принимает Uint8Array из байтов в памяти.

Нумерация страниц начинается с нуля или с единицы?

И то, и другое, в зависимости от API: doc.Pages — обычный массив с нулевой индексацией, но такие методы, как RemovePage() и ExtractPages(), используют нумерацию страниц, начинающуюся с 1.

Могу ли я зашифровать документ при сохранении?

Да — передайте параметр encrypt в WriteTo() / Save() вместе с algorithm: 'aes256' | 'aes128' | 'rc4' и необязательными паролями пользователя/владельца.

Как уменьшить размер выходного файла?

Передайте { compressed: true } в Document.WriteTo(), чтобы включить сжатие xref-stream и object-stream.

Могу ли я просмотреть операторы сырого контент-стрима страницы?

Да — parseContentStream(doc.Pages[0].Contents) возвращает список операторов, а serializeContentStream() преобразует отредактированный список обратно в байты.

API Reference Сводка

См. также:

• Aspose.PDF — Enterprise Documentation