Фасады API

Фасады API

A facade является упрощённой, ориентированной на задачи обёрткой над ядром Document / Page / Annotation объектной модели. Вместо того чтобы самостоятельно обходить дерево страниц, вы привязываете фасад к исходному PDF, вызываете небольшой набор высокоуровневых методов и сохраняете результат. Каждый фасад в Aspose::Pdf::Facades реализует тот же минимальный контракт, определённый IFacade (BindPdf, Close) и, где фасад генерирует вывод, ISaveableFacade (Save). Абстрактный Facade and SaveableFacade базовые классы предоставляют реализацию по умолчанию для bind/close/save, на которой строятся конкретные редакторы ниже: PdfAnnotationEditor, PdfBookmarkEditor, PdfContentEditor, PdfConverter, PdfExtractor, PdfFileEditor, PdfFileInfo, PdfFileSecurity, PdfFileSignature, PdfFileStamp, PdfPageEditor, PdfXmpMetadata, и ориентированный на формы FormEditor / FormFieldFacade пара.

Базовые классы фасадов и жизненный цикл bind/save

IFacade объявляет BindPdf(srcFile) (также перегруженный для приёма в-памяти Document) и Close(). ISaveableFacade добавляет Save(destFile) для фасадов, которые записывают вывод. Facade реализует IFacade и раскрывает привязанный Document(), чтобы вы могли вернуться к ядру объектной модели, когда метод фасада не покрывает требуемое; SaveableFacade расширяет Facade реализацией Save. Каждый конкретный редактор ниже наследует эту структуру, поэтому тот же шаблон bind → operate → save применяется ко всему набору Фасады API.

Заполнение и редактирование AcroForm полей

FormEditor добавляет, удаляет, переименовывает и перемещает AcroForm поля в уже привязанном документе. AddField(fieldType, fieldName, pageNum, llx, lly, urx, ury) создаёт новое поле заданного FieldType (Text, CheckBox, Radio, ComboBox, ListBox, PushButton, MultiLineText, Barcode, Signature, Image, Numeric, DateTime) в указанных координатах страницы. RemoveField, RenameField, MoveField и SetFieldAttribute управляют существующими полями, а SetFieldScript / AddFieldScript прикрепляют действия JavaScript. SubmitFlag (значение SubmitFormFlag — Fdf, Html, Xfdf, FdfWithComments, XfdfWithComments или Pdf) определяет, как кнопка отправки передаёт данные формы, а SetSubmitUrl задаёт целевой эндпоинт.

Визуальное оформление каждого нового поля управляется через FormEditor.Facade(), который возвращает FormFieldFacade. Его свойство Font принимает значение FontStyle (Helvetica, HelveticaBold, Courier, TimesRoman, Symbol и связанные варианты), TextEncoding принимает EncodingType (Winansi, Macroman, Identity_h, Identity_v, Cp1250, Cp1252, Cp1257), а BorderStyle / BorderWidth задают границу поля.

FormEditor editor;
editor.SrcFileName("template.pdf");
editor.DestFileName("output.pdf");
editor.AddField(FieldType::Text, "FirstName", 1, 100, 700, 300, 720);
editor.SetFieldAttribute("FirstName", AnnotationFlags::Print);
editor.Save();

Управление оглавлением с PdfBookmarkEditor

PdfBookmarkEditor создает, извлекает, изменяет и удаляет записи оглавления PDF. CreateBookmarks() записывает коллекцию Bookmarks (каждая запись представляет собой Bookmark с Title, PageNumber, Action, Level, Open и ChildItems для вложенных оглавлений) в привязанный документ. ExtractBookmarks() считывает существующее оглавление обратно как коллекцию Bookmarks, а DeleteBookmarks() — с необязательным фильтром title — удаляет записи. ExportBookmarksToXML / ImportBookmarksWithXML осуществляют круговой проход оглавления через файл XML, а ExtractBookmarksToHTML / ExportBookmarksToHtml визуализируют оглавление как страницу HTML.

PdfBookmarkEditor editor;
editor.BindPdf("input.pdf");
Bookmarks bookmarks = editor.ExtractBookmarks();
editor.DeleteBookmarks("Draft");
editor.Save("output.pdf");

Редактирование аннотаций с PdfAnnotationEditor

PdfAnnotationEditor уплощает и импортирует аннотации по всему документу. FlatteningAnnotations() объединяет аннотации в поток содержимого страницы, чтобы они отображались как статический контент вместо интерактивных объектов; перегрузка, принимающая диапазон страниц start/end и тип аннотации, ограничивает операцию. ImportAnnotationsFromXfdf / ImportAnnotationsFromFdf импортируют аннотации из внешних файлов FDF/XFDF, а DeleteAnnotations() (или DeleteAnnotations(annotType) для одного типа) удаляют их.

PdfAnnotationEditor editor;
editor.BindPdf("commented.pdf");
editor.FlatteningAnnotations();
editor.Save("flattened.pdf");

Перезапись содержимого страницы с PdfContentEditor

PdfContentEditor редактирует уже созданный поток содержимого страницы вместо пересоздания страницы. ReplaceText(srcText, destText) ищет и заменяет совпадающий текст по всему документу, с перегрузками, ограничивающими замену одной страницей. ReplaceImage(pageNum, imageNum, fileName) и DeleteImage(pageNum, imageNum) заменяют или удаляют существующий XObject изображения. DeleteStampById / HideStampById / ShowStampById / MoveStampById управляют объектами штампа на странице (основное содержимое штампа представлено либо Form, либо Image в соответствии с перечислением StampType), а AddDocumentAdditionalAction / AddDocumentAttachment прикрепляют действия уровня документа JavaScript и вложения файлов.

PdfContentEditor editor;
editor.BindPdf("template.pdf");
editor.ReplaceText("{{CustomerName}}", "Jane Doe");
editor.Save("output.pdf");

Извлечение текста и вложений с PdfExtractor

PdfExtractor может быть привязан либо с помощью BindPdf, либо создан напрямую из уже открытого Document. ExtractText(), за которым следуют HasNextPageText() / GetNextPageText(outputFile), проходит по документу постранично. Для встроенных файлов GetAttachNames() перечисляет присутствующие вложения, а GetAttachment( outputPath) записывает следующее из них на диск:

#include <aspose/pdf/document.hpp>
#include <aspose/pdf/facades/pdf_extractor.hpp>
#include <iostream>

int main() {
    Aspose::Pdf::Document doc("attachments.pdf");
    Aspose::Pdf::Facades::PdfExtractor extractor(doc);

    auto names = extractor.GetAttachNames();
    std::cout << "Attachments found: " << names.size() << "\n";

    if (!names.empty()) {
        extractor.GetAttachment("extracted-attachment.bin");
    }
}

ExtractImage() / HasNextImage() / GetNextImage(outputFile) извлекают встроенные растровые изображения так же, как GetNextPageText проходит страницы.

Сборка и разбиение файлов с помощью PdfFileEditor

PdfFileEditor работает с путями к файлам, а не с привязанным Document, поэтому каждый метод принимает имена входных/выходных файлов напрямую. Concatenate (и не бросающий исключения TryConcatenate) объединяет два или более файлов; Append вставляет диапазон страниц из одного файла в другой; Extract извлекает диапазон страниц или отдельную страницу в новый файл; Delete удаляет страницу; и SplitFromFirst / SplitToEnd / SplitToPages / SplitToBulks делят документ по странице, по страницам или на блоки фиксированного размера. MakeBooklet и MakeNUp переупорядочивают страницы для буклета или печати N-up, а ResizeContents / AddMargins / AddPageBreak корректируют геометрию страниц в файле. Большинство операций имеют вариант с префиксом Try, который возвращает false вместо броска исключения при неудаче.

PdfFileEditor editor;
editor.Concatenate("part1.pdf", "part2.pdf", "merged.pdf");
editor.Extract("merged.pdf", 1, 3, "first-three-pages.pdf");

Отрисовка страниц в изображения с помощью PdfConverter

PdfConverter отрисовывает привязанные страницы документов в растровые форматы. DoConvert() подготавливает диапазон страниц (StartPage / EndPage) для итерации; HasNextImage () / GetNextImage(outputFile) затем проходят по страницам одну за другой. SaveAsTIFF записывает весь диапазон в один многостраничный TIFF, с перегрузками для разрешения, сжатия и TiffSettings. RenderingOptions и Resolution управляют качеством растеризации, а ImageMergeMode (Vertical, Horizontal, Center) определяет, как несколько отрисованных изображений страниц объединяются, когда вызывающий объединяет их в одно изображение.

PdfConverter converter;
converter.BindPdf("report.pdf");
converter.Resolution(Aspose::Pdf::Devices::Resolution(150));
converter.DoConvert();
while (converter.HasNextImage()) {
    converter.GetNextImage("page.png");
}

Шифрование документов с помощью PdfFileSecurity

PdfFileSecurity привязывает исходный файл и применяет или удаляет шифрование. EncryptFile(userPassword, ownerPassword, privilege, keySize) шифрует с помощью DocumentPrivilege (созданного конструктором по умолчанию и булевыми сеттерами, такими как AllowPrint, AllowCopy, AllowModifyContents) и KeySize (x40, x128 или x256); перегрузка, принимающая пятый аргумент cipher, явно выбирает Algorithm (RC4 или AES). DecryptFile( ownerPassword), ChangePassword и SetPrivilege охватывают оставшиеся случаи управления паролем, каждый имеет вариант с префиксом Try, не бросающий исключения.

PdfFileSecurity security;
security.BindPdf("input.pdf");

DocumentPrivilege privilege;
privilege.AllowPrint(true);
privilege.AllowModifyContents(false);

security.EncryptFile("user-pass", "owner-pass", privilege, KeySize::x256);

Подписание и проверка с помощью PdfFileSignature

PdfFileSignature подписывает, сертифицирует и проверяет цифровые подписи в связанном документе. Sign(sigName, reason, contact, location, signature) добавляет новую подпись в существующее поле подписи; Certify добавляет сертификирующую подпись. GetSignatureNames(onlyEmpty) и GetBlankSignatureNames() возвращают поля подписи документа как значения SignatureName, а VerifySignature(sigName) / IsCoversWholeDocument (sigName) проверяют валидность и охват. RemoveSignature и RemoveSignatures() удаляют существующие подписи, а SetCertificate(pfxFile, password) предоставляет учетные данные подписи перед вызовом Sign.

PdfFileSignature signature;
signature.BindPdf("contract.pdf");
signature.SetCertificate("signing-cert.pfx", "cert-password");
bool signed_ok = signature.ContainsSignature();
signature.Save();

Нанесение заголовков, нижних колонтитулов и номеров страниц с помощью PdfFileStamp.

PdfFileStamp накладывает повторяющийся контент на каждую страницу связанного файла. AddPageNumber(format) наносит метку номера страницы, используя начальный номер и при необходимости явные координаты; AddHeader(text, topMargin) и AddFooter(text, bottomMargin) добавляют повторяющийся текст заголовка/нижнего колонтитула в заданном поле, с перегрузками для левого/правого полей. KeepSecurity сохраняет любое существующее шифрование в выходном файле, а Close() завершает и освобождает связанный документ.

PdfFileStamp stamp;
stamp.InputFile("input.pdf");
stamp.OutputFile("stamped.pdf");
stamp.AddPageNumber("Page # of #", 1);
stamp.Close();

Чтение и запись информации о документе с помощью PdfFileInfo.

PdfFileInfo читает и перезаписывает классический словарь PDF /Info и базовую геометрию каждой страницы без открытия полной модели объектов. Author, Title, Subject, Keywords, CreationDate и ModDate являются свойствами чтения/записи; Producer и GetPdfVersion() — только для чтения. GetPageWidth, GetPageHeight и GetPageRotation возвращают геометрию страниц по номеру, а IsEncrypted() / HasOpenPassword() / HasEditPassword() сообщают о состоянии защиты документа. SaveNewInfo(outputFile) записывает изменения обратно.

PdfFileInfo info;
info.BindPdf(document);
info.Title("Updated Report Title");
info.SaveNewInfo("output.pdf");

Перемещение страниц с помощью PdfPageEditor.

PdfPageEditor перемещает, изменяет размер и вращает содержимое страницы как блок. MovePosition(offsetX, offsetY) сдвигает содержимое на страницах, выбранных ProcessPages; Zoom масштабирует его. Alignment (это AlignmentType — Left, Center или Right, каждый получаемый через соответствующий статический метод) и VerticalAlignment (это VerticalAlignmentType — Top, Center, Bottom) управляют тем, как содержимое позиционируется внутри целевого PageSize, когда запускается ApplyChanges(). GetPageRotation считывает текущий угол вращения страницы в градусах.

PdfPageEditor editor;
editor.BindPdf("input.pdf");
editor.Alignment(AlignmentType::Center());
editor.MovePosition(0, -20);
editor.ApplyChanges();

Управление XMP-метаданными с помощью PdfXmpMetadata.

PdfXmpMetadata — фасад, похожий на отображение, над XMP-пакетом документа. Add(key, value), Remove(key), Contains(key) / ContainsKey(key) и TryGetValue(key, value) управляют отдельными записями; Keys() и Values() перечисляют весь пакет. RegisterNamespaceURI(prefix, namespaceURI) объявляет пользовательское XMP-пространство имён перед тем, как вы добавляете в него свойства. Известные имена свойств перечислены в DefaultMetadataProperties (CreateDate, CreatorTool, Identifier, ModifyDate, Nickname, Thumbnails и другие), а PropertyFlag (ReadOnly, Required, NoExport) описывает ограничения схемы зарегистрированного свойства.

PdfXmpMetadata xmp;
xmp.BindPdf(document);
xmp.Add("dc:creator", "Report Generator");
xmp.Save("output.pdf");

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

• Каждый фасад следует одной и той же последовательности BindPdf (или конструктора, принимающего имя файла) → выполнить → Save/Close — изучение одного фасада напрямую переносится на следующий.
• Отдавайте предпочтение методам с префиксом Try в PdfFileEditor и PdfFileSecurity при обработке файлов из ненадёжного или непредсказуемого источника — они возвращают false в случае ошибки вместо выброса исключения.
• Методы PdfFileEditor принимают пути к файлам, а не привязанный Document — вам не нужно самостоятельно открывать исходный файл перед вызовом Concatenate, Extract или SplitFromFirst.
• Фасады оборачивают ядровую объектную модель, а не заменяют её: Facade раскрывает базовый Document() для случаев, когда метод фасада не покрывает требуемую функциональность.
• Вызовите Close() (или позвольте фасаду выйти из области видимости, где это поддерживается), когда вы закончите работу с привязанным документом, чтобы освободить базовый файловый дескриптор.

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

FAQ

В чём разница между фасадом и ядром Document API?

Фасады предоставляют небольшую, ориентированную на задачу поверхность методов для одной задачи— заполнения формы, объединения файлов, штамповки страниц. Ядро API (Document, Page, Annotation) даёт полный доступ к каждому объекту PDF. Фасады, которые раскрывают Document() (через базовый класс Facade), позволяют вернуться к ядру модели для любого случая, когда метод фасада не покрывает.

Нужно ли вызывать BindPdf перед каждым методом фасада?

Да, для фасадов, реализующих IFacade,— BindPdf (или эквивалентный перегруженный конструктор, как в случае с PdfExtractor(doc)) должен быть выполнен перед любой операцией, читающей или изменяющей привязанный документ.

Можно ли цепочкой выполнять операции PdfFileEditor?

Каждый метод PdfFileEditor читает свой входной файл и записывает свой выходной файл, поэтому вы связываете операции, передавая выходной файл одного метода в качестве входного файла следующего вызова— например, Concatenate в merged.pdf, затем Extract из merged.pdf.

Какие фасады поддерживают режим ошибок без выброса исключений?

PdfFileEditor (TryConcatenate, TryAppend, TryExtract, TrySplitFromFirst, и связанные методы Try*) и PdfFileSecurity (TryEncryptFile, TryDecryptFile, TrySetPrivilege, TryChangePassword) оба предлагают альтернативы с префиксом Try, которые возвращают bool вместо выбрасывания исключения.

API Reference Сводка

См. также:

• Aspose.PDF — Enterprise Documentation