Фасади API

Фасади API

A facade є спрощеною, орієнтованою на завдання оболонкою над core 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 fields

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) замінюють або видаляють існуючий Image 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