Fasady API

Fasady API

A facade jest uproszczonym, zadaniowo-zorientowanym wrapperem nad core Document / Page / Annotation model obiektowy. Zamiast samodzielnie przechodzić po drzewie stron, wiążesz fasadę ze źródłowym PDF, wywołujesz niewielki zestaw metod wysokiego poziomu i zapisujesz wynik. Każda fasada w Aspose::Pdf::Facades implementuje ten sam minimalny kontrakt zdefiniowany przez IFacade (BindPdf, Close) i, tam gdzie fasada generuje wyjście, ISaveableFacade (Save). Abstrakcyjny Facade and SaveableFacade klasy bazowe dostarczają domyślną implementację bind/close/save, na której opierają się konkretne edytory poniżej: PdfAnnotationEditor, PdfBookmarkEditor, PdfContentEditor, PdfConverter, PdfExtractor, PdfFileEditor, PdfFileInfo, PdfFileSecurity, PdfFileSignature, PdfFileStamp, PdfPageEditor, PdfXmpMetadata, i skoncentrowane na formularzach FormEditor / FormFieldFacade para.

Klasy bazowe fasady oraz cykl życia bind/save

IFacade deklaruje BindPdf(srcFile) (również przeciążone, aby przyjmować pamięciowy Document) oraz Close(). ISaveableFacade dodaje Save(destFile) dla fasad, które zapisują wyjście. Facade implementuje IFacade i udostępnia powiązany Document(), abyś mógł wrócić do rdzeniowego modelu obiektowego, gdy metoda fasady nie obejmuje potrzebnej funkcjonalności; SaveableFacade rozszerza Facade o implementację Save. Każdy konkretny edytor poniżej dziedziczy tę strukturę, więc ten sam wzorzec bind → operate → save ma zastosowanie w całym zestawie Fasady API.

Wypełnianie i edycja pól AcroForm

FormEditor dodaje, usuwa, zmienia nazwę i przestawia pola AcroForm w już powiązanym dokumencie. AddField(fieldType, fieldName, pageNum, llx, lly, urx, ury) tworzy nowe pole o podanym FieldType (Text, CheckBox, Radio, ComboBox, ListBox, PushButton, MultiLineText, Barcode, Signature, Image, Numeric, DateTime) w określonych współrzędnych strony. RemoveField, RenameField, MoveField i SetFieldAttribute zarządzają istniejącymi polami, a SetFieldScript / AddFieldScript dołączają akcje JavaScript. SubmitFlag (wartość SubmitFormFlag — Fdf, Html, Xfdf, FdfWithComments, XfdfWithComments lub Pdf) określa, w jaki sposób przycisk wysyłania przesyła dane formularza, a SetSubmitUrl ustawia docelowy punkt końcowy.

Wygląd wizualny każdego nowego pola jest kontrolowany przez FormEditor.Facade(), który zwraca FormFieldFacade. Jego własność Font przyjmuje wartość FontStyle (Helvetica, HelveticaBold, Courier, TimesRoman, Symbol i powiązane warianty), TextEncoding przyjmuje EncodingType (Winansi, Macroman, Identity_h, Identity_v, Cp1250, Cp1252, Cp1257), a BorderStyle / BorderWidth ustawiają obramowanie pola.

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

Zarządzanie spisami przy pomocy PdfBookmarkEditor

PdfBookmarkEditor tworzy, wyodrębnia, modyfikuje i usuwa wpisy spisu treści PDF. CreateBookmarks() zapisuje kolekcję Bookmarks (każdy wpis to Bookmark z Title, PageNumber, Action, Level, Open i ChildItems dla zagnieżdżonych spisów) w powiązanym dokumencie. ExtractBookmarks() odczytuje istniejący spis z powrotem jako kolekcję Bookmarks, a DeleteBookmarks() — z opcjonalnym filtrem title — usuwa wpisy. ExportBookmarksToXML / ImportBookmarksWithXML wykonują pełny cykl spisu przez plik XML, a ExtractBookmarksToHTML / ExportBookmarksToHtml renderują spis jako stronę HTML.

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

Edycja adnotacji przy użyciu PdfAnnotationEditor

PdfAnnotationEditor spłaszcza i importuje adnotacje w całym dokumencie. FlatteningAnnotations() scala adnotacje z strumieniem zawartości strony, dzięki czemu renderują się jako treść statyczna zamiast obiektów interaktywnych; przeciążenie przyjmujące zakres stron start/end oraz typ adnotacji ogranicza operację. ImportAnnotationsFromXfdf / ImportAnnotationsFromFdf wprowadzają adnotacje z zewnętrznych plików FDF/XFDF, a DeleteAnnotations() (lub DeleteAnnotations(annotType) dla pojedynczego typu) je usuwa.

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

Przepisanie zawartości strony przy użyciu PdfContentEditor

PdfContentEditor edytuje już wygenerowany strumień zawartości strony zamiast przebudowywać stronę. ReplaceText(srcText, destText) wyszukuje i zamienia pasujący tekst w całym dokumencie, z przeciążeniami ograniczającymi zamianę do jednej strony. ReplaceImage(pageNum, imageNum, fileName) i DeleteImage(pageNum, imageNum) wymieniają lub usuwają istniejący obiekt XObject obrazu. DeleteStampById / HideStampById / ShowStampById / MoveStampById zarządzają obiektami pieczęci na stronie (podstawowa zawartość pieczęci to Form lub Image, zgodnie z wyliczeniem StampType), a AddDocumentAdditionalAction / AddDocumentAttachment dołączają akcje JavaScript na poziomie dokumentu oraz załączniki plików.

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

Wyodrębnianie tekstu i załączników przy użyciu PdfExtractor

PdfExtractor może być powiązany albo z BindPdf, albo skonstruowany bezpośrednio z już otwartego Document. ExtractText() po HasNextPageText() / GetNextPageText(outputFile) przegląda dokument stronę po stronie. Dla osadzonych plików, GetAttachNames() wymienia istniejące załączniki, a GetAttachment( outputPath) zapisuje kolejny na dysk:

#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) wyodrębnia osadzone obrazy rastrowe w taki sam sposób, w jaki GetNextPageText przegląda strony.

Łączenie i dzielenie plików przy użyciu PdfFileEditor

PdfFileEditor działa na ścieżkach plików, a nie na powiązanym Document, więc każda metoda przyjmuje bezpośrednio nazwy plików wejściowych/wyjściowych. Concatenate (oraz nie wyrzucająca TryConcatenate) scala dwa lub więcej plików; Append wstawia zakres stron z jednego pliku do drugiego; Extract wyciąga zakres stron lub pojedynczą stronę do nowego pliku; Delete usuwa stronę; oraz SplitFromFirst / SplitToEnd / SplitToPages / SplitToBulks dzielą dokument na stronie, po stronie lub na fragmenty o stałym rozmiarze. MakeBooklet i MakeNUp przestawiają strony dla druku broszury lub N-up, a ResizeContents / AddMargins / AddPageBreak dostosowują geometrię stron w całym pliku. Większość operacji ma odpowiednik z prefiksem Try, który zwraca false zamiast rzucać wyjątek w przypadku niepowodzenia.

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

Renderowanie stron do obrazów przy użyciu PdfConverter

PdfConverter renderuje powiązane strony dokumentu do formatów rastrowych. DoConvert() przygotowuje zakres stron (StartPage / EndPage) do iteracji; HasNextImage () / GetNextImage(outputFile) następnie przechodzą przez strony pojedynczo. SaveAsTIFF zapisuje cały zakres do jednego wielostronicowego TIFF, z przeciążeniami dla rozdzielczości, kompresji i TiffSettings. RenderingOptions i Resolution kontrolują jakość rasteryzacji, a ImageMergeMode (Vertical, Horizontal, Center) określa, jak wiele wyrenderowanych obrazów stron jest łączonych, gdy wywołujący scala je w jeden obraz.

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

Szyfrowanie dokumentów przy użyciu PdfFileSecurity

PdfFileSecurity wiąże plik źródłowy i stosuje lub usuwa szyfrowanie. EncryptFile(userPassword, ownerPassword, privilege, keySize) szyfruje przy użyciu DocumentPrivilege (zbudowanego przy pomocy domyślnego konstruktora i setterów boolowskich, takich jak AllowPrint, AllowCopy, AllowModifyContents) oraz KeySize (x40, x128 lub x256); przeciążenie przyjmujące piąty argument cipher wybiera Algorithm (RC4 lub AES) explicite. DecryptFile( ownerPassword), ChangePassword i SetPrivilege obejmują pozostałe przypadki zarządzania hasłem, każdy z nie wyrzucającą wariantą z prefiksem Try.

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

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

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

Podpisywanie i weryfikacja przy użyciu PdfFileSignature

PdfFileSignature podpisuje, poświadcza i sprawdza cyfrowe podpisy w połączonym dokumencie. Sign(sigName, reason, contact, location, signature) nakłada nowy podpis w istniejącym polu podpisu; Certify stosuje podpis certyfikujący. GetSignatureNames(onlyEmpty) i GetBlankSignatureNames() zwracają pola podpisów dokumentu jako wartości SignatureName, a VerifySignature(sigName) / IsCoversWholeDocument (sigName) sprawdzają ważność i zakres. RemoveSignature i RemoveSignatures() usuwają istniejące podpisy, a SetCertificate(pfxFile, password) dostarcza dane uwierzytelniające do podpisu przed wywołaniem Sign.

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

Nakładanie nagłówków, stopek i numerów stron przy użyciu PdfFileStamp

PdfFileStamp nakłada powtarzającą się treść na każdą stronę połączonego pliku. AddPageNumber(format) umieszcza etykietę z numerem strony, używając liczby początkowej i opcjonalnych wyraźnych współrzędnych; AddHeader(text, topMargin) i AddFooter(text, bottomMargin) dodają powtarzający się tekst nagłówka/stopki w zadanym marginesie, z przeciążeniami dla lewego/prawego marginesu. KeepSecurity zachowuje istniejące szyfrowanie w pliku wyjściowym, a Close() finalizuje i zwalnia połączony dokument.

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

Odczytywanie i zapisywanie informacji o dokumencie przy użyciu PdfFileInfo

PdfFileInfo odczytuje i przepisuje klasyczny słownik PDF /Info oraz podstawową geometrię każdej strony bez otwierania pełnego modelu obiektów. Author, Title, Subject, Keywords, CreationDate i ModDate są właściwościami odczyt/zapis; Producer i GetPdfVersion() są tylko do odczytu. GetPageWidth, GetPageHeight i GetPageRotation zwracają geometrię strony według numeru, a IsEncrypted() / HasOpenPassword() / HasEditPassword() raportują stan ochrony dokumentu. SaveNewInfo(outputFile) zapisuje zmiany z powrotem.

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

Przemieszczanie stron przy użyciu PdfPageEditor

PdfPageEditor przesuwa, zmienia rozmiar i obraca zawartość strony jako blok. MovePosition(offsetX, offsetY) przesuwa zawartość na stronach wybranych przez ProcessPages; Zoom skaluje ją. Alignment (jest AlignmentType — Left, Center lub Right, każdy uzyskany z odpowiedniej metody statycznej) oraz VerticalAlignment (jest VerticalAlignmentType — Top, Center, Bottom) kontrolują, jak zawartość jest pozycjonowana w docelowym PageSize, gdy uruchomi się ApplyChanges(). GetPageRotation odczytuje aktualny obrót strony w stopniach.

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

Zarządzanie metadanymi XMP przy użyciu PdfXmpMetadata

PdfXmpMetadata jest fasadą podobną do mapy nad pakietem XMP dokumentu. Add(key, value), Remove(key), Contains(key) / ContainsKey(key) oraz TryGetValue(key, value) zarządzają poszczególnymi wpisami; Keys() i Values() wyliczają cały pakiet. RegisterNamespaceURI(prefix, namespaceURI) deklaruje niestandardową przestrzeń nazw XMP przed dodaniem do niej własności. Znane nazwy własności są wymienione w DefaultMetadataProperties (CreateDate, CreatorTool, Identifier, ModifyDate, Nickname, Thumbnails i inne), a PropertyFlag (ReadOnly, Required, NoExport) opisuje ograniczenia schematu zarejestrowanej własności.

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

Wskazówki i najlepsze praktyki

• Każda fasada podąża za tym samym BindPdf (lub konstruktorem przyjmującym nazwę pliku) → operuj → sekwencją Save/Close — nauka jednej fasady przekłada się bezpośrednio na kolejną.
• Preferuj metody z prefiksem Try na PdfFileEditor i PdfFileSecurity przy przetwarzaniu plików z niezaufanego lub nieprzewidywalnego źródła — zwracają false w przypadku niepowodzenia zamiast rzucać wyjątek.
• Metody PdfFileEditor przyjmują ścieżki do plików, a nie związany Document — nie musisz samodzielnie otwierać pliku źródłowego przed wywołaniem Concatenate, Extract lub SplitFromFirst.
• Fasady otaczają rdzeniowy model obiektowy zamiast go zastępować: Facade udostępnia podstawowy Document() w przypadkach, gdy metoda fasady nie obejmuje danej funkcjonalności.
• Wywołaj Close() (lub pozwól fasadzie wyjść z zakresu, jeśli jest to obsługiwane), gdy skończysz pracę z powiązanym dokumentem, aby zwolnić podstawowy uchwyt pliku.

Typowe problemy

FAQ

Jaka jest różnica między fasadą a głównym Document API?

Fasady zapewniają mały, zadaniowo-zorientowany interfejs metodowy dla jednej czynności — wypełniania formularza, łączenia plików, znakowania stron. Rdzeniowy API (Document, Page, Annotation) daje pełny dostęp do każdego obiektu PDF. Fasady, które udostępniają Document() (poprzez klasę bazową Facade), pozwalają wrócić do modelu rdzeniowego w przypadku wszystkiego, czego metoda fasady nie obejmuje.

Czy muszę wywołać BindPdf przed każdą metodą fasady?

Tak, dla fasad implementujących IFacade — BindPdf (lub równoważny przeciążony konstruktor, tak jak w przypadku PdfExtractor(doc)) musi zostać wywołany przed każdą operacją, która odczytuje lub modyfikuje powiązany dokument.

Czy operacje PdfFileEditor mogą być łańcuchowane?

Każda metoda PdfFileEditor odczytuje własny plik wejściowy i zapisuje własny plik wyjściowy, więc łańcuchujesz operacje, przekazując plik wyjściowy jednej metody jako plik wejściowy kolejnego wywołania — na przykład, Concatenate do merged.pdf, a następnie Extract z merged.pdf.

Które fasady obsługują tryb błędów nie rzucający wyjątków?

PdfFileEditor (TryConcatenate, TryAppend, TryExtract, TrySplitFromFirst, oraz powiązane Try* metody) oraz PdfFileSecurity (TryEncryptFile, TryDecryptFile, TrySetPrivilege, TryChangePassword) oba oferują alternatywy z prefiksem Try, które zwracają bool zamiast rzucać.

API Reference Podsumowanie

Zobacz także

• Aspose.PDF — Enterprise Documentation