Fasády API

Fasády API

A facade je zjednodušený, úkolově orientovaný wrapper nad jádrem Document / Page / Annotation objektovým modelem. Místo toho, abyste sami procházeli strom stránek, připojíte fasádu ke zdrojovému PDF, zavoláte malou sadu vysoceúrovňových metod a výsledek uložíte. Každá fasáda v Aspose::Pdf::Facades implementuje stejnou minimální smlouvu definovanou IFacade (BindPdf, Close) a kde fasáda produkuje výstup, ISaveableFacade (Save). Abstraktní Facade and SaveableFacade základní třídy poskytují výchozí implementaci bind/close/save, na které jsou níže postavené konkrétní editory: PdfAnnotationEditor, PdfBookmarkEditor, PdfContentEditor, PdfConverter, PdfExtractor, PdfFileEditor, PdfFileInfo, PdfFileSecurity, PdfFileSignature, PdfFileStamp, PdfPageEditor, PdfXmpMetadata, a formulářově zaměřené FormEditor / FormFieldFacade pár.

Základní třídy facade a životní cyklus bind/save

IFacade deklaruje BindPdf(srcFile) (také přetížené tak, aby přijímalo paměťové Document) a Close(). ISaveableFacade přidává Save(destFile) pro facady, které zapisují výstup. Facade implementuje IFacade a zpřístupňuje svázaný Document(), abyste se mohli vrátit do jádrového modelu objektů, když metoda facade nepokryje, co potřebujete; SaveableFacade rozšiřuje Facade o implementaci Save. Každý konkrétní editor níže dědí tuto strukturu, takže stejný vzor bind → operate → save platí v celém Fasády API.

Vyplňování a úprava AcroForm polí

FormEditor přidává, odstraňuje, přejmenovává a přemisťuje pole AcroForm v již svázaném dokumentu. AddField(fieldType, fieldName, pageNum, llx, lly, urx, ury) vytvoří nové pole daného typu FieldType (Text, CheckBox, Radio, ComboBox, ListBox, PushButton, MultiLineText, Barcode, Signature, Image, Numeric, DateTime) na určených souřadnicích stránky. RemoveField, RenameField, MoveField a SetFieldAttribute spravují existující pole a SetFieldScript / AddFieldScript připojují akce JavaScript. SubmitFlag (hodnota SubmitFormFlag — Fdf, Html, Xfdf, FdfWithComments, XfdfWithComments nebo Pdf) určuje, jak tlačítko odeslat (submit) posílá data formuláře, a SetSubmitUrl nastavuje cílový endpoint.

Vizuální vzhled každého nového pole je řízen pomocí FormEditor.Facade(), který vrací FormFieldFacade. Jeho vlastnost Font přijímá hodnotu FontStyle (Helvetica, HelveticaBold, Courier, TimesRoman, Symbol a související varianty), TextEncoding přijímá EncodingType (Winansi, Macroman, Identity_h, Identity_v, Cp1250, Cp1252, Cp1257) a BorderStyle / BorderWidth nastavují okraj pole.

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

Správa osnov pomocí PdfBookmarkEditor

PdfBookmarkEditor vytváří, extrahuje, upravuje a odstraňuje položky osnov PDF. CreateBookmarks() zapisuje Bookmarks kolekci (každá položka je Bookmark s Title, PageNumber, Action, Level, Open a ChildItems pro vnořené osnovy) do vázaného dokumentu. ExtractBookmarks() načte existující osnovu zpět jako Bookmarks kolekci a DeleteBookmarks() — s volitelným filtrem title — odstraňuje položky. ExportBookmarksToXML / ImportBookmarksWithXML provádějí round-trip osnovy přes soubor XML a ExtractBookmarksToHTML / ExportBookmarksToHtml vykreslují osnovu jako stránku HTML.

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

Úprava anotací pomocí PdfAnnotationEditor

PdfAnnotationEditor zplošťuje a importuje anotace v celém dokumentu. FlatteningAnnotations() sloučuje anotace do proudu obsahu stránky, takže se vykreslují jako statický obsah místo interaktivních objektů; přetížení přijímající rozsah stránek start/end a typ anotace omezuje operaci. ImportAnnotationsFromXfdf / ImportAnnotationsFromFdf přinášejí anotace z externích souborů FDF/XFDF, a DeleteAnnotations() (nebo DeleteAnnotations(annotType) pro jediný typ) je odstraňuje.

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

Přepisování obsahu stránky pomocí PdfContentEditor

PdfContentEditor upravuje již vygenerovaný proud obsahu stránky místo přestavby stránky. ReplaceText(srcText, destText) vyhledává a nahrazuje odpovídající text v celém dokumentu, s přetíženími, které omezují nahrazení na jedinou stránku. ReplaceImage(pageNum, imageNum, fileName) a DeleteImage(pageNum, imageNum) vyměňují nebo odstraňují existující XObject obrázku. DeleteStampById / HideStampById / ShowStampById / MoveStampById spravují objekty razítek na stránce (základní obsah razítka je buď Form nebo Image, podle výčtu StampType), a AddDocumentAdditionalAction / AddDocumentAttachment připojují akce JavaScript na úrovni dokumentu a přílohy souborů.

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

Extrahování textu a příloh pomocí PdfExtractor

PdfExtractor může být svázáno buď pomocí BindPdf, nebo vytvořeno přímo z již otevřeného Document. ExtractText() následované HasNextPageText() / GetNextPageText(outputFile) prochází dokument stránku po stránce. Pro vložené soubory GetAttachNames() vylistuje přítomné přílohy a GetAttachment( outputPath) zapíše další na disk:

#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) extrahují vložené rastrové obrázky stejným způsobem, jakým GetNextPageText prochází stránky.

Sestavování a rozdělování souborů pomocí PdfFileEditor

PdfFileEditor pracuje s cestami k souborům místo svázaného Document, takže každá metoda přijímá vstupní/výstupní názvy souborů přímo. Concatenate (a nevyhazující TryConcatenate) slučuje dva nebo více souborů; Append vloží rozsah stránek z jednoho souboru do druhého; Extract vytáhne rozsah stránek nebo jedinou stránku do nového souboru; Delete odstraní stránku; a SplitFromFirst / SplitToEnd / SplitToPages / SplitToBulks rozdělí dokument na stránku, po stránce, nebo na bloky pevné velikosti. MakeBooklet a MakeNUp přeskupí stránky pro brožuru nebo tisk N-up, a ResizeContents / AddMargins / AddPageBreak upravují geometrii stránky v celém souboru. Většina operací má protějšek s předponou Try, který vrací false místo vyhození výjimky při selhání.

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

Vykreslování stránek do obrázků pomocí PdfConverter

PdfConverter vykresluje svázané stránky dokumentu do rastrových formátů. DoConvert() připravuje rozsah stránek (StartPage / EndPage) pro iteraci; HasNextImage () / GetNextImage(outputFile) pak prochází stránky po jedné. SaveAsTIFF zapíše celý rozsah do jednoho vícestránkového TIFF, s přetíženími pro rozlišení, kompresi a TiffSettings. RenderingOptions a Resolution řídí kvalitu rasterizace a ImageMergeMode (Vertical, Horizontal, Center) určuje, jak jsou kombinovány více vykreslených obrázků stránek, když je volající sloučí do jednoho obrázku.

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

Šifrování dokumentů pomocí PdfFileSecurity

PdfFileSecurity sváže zdrojový soubor a použije nebo odebere šifrování. EncryptFile(userPassword, ownerPassword, privilege, keySize) šifruje pomocí DocumentPrivilege (vytvořeného výchozím konstruktorem a boolovými nastaviteli, jako jsou AllowPrint, AllowCopy, AllowModifyContents) a KeySize (x40, x128 nebo x256); přetížení, které přijímá pátý argument cipher, explicitně vybírá Algorithm (RC4 nebo AES). DecryptFile( ownerPassword), ChangePassword a SetPrivilege pokrývají zbývající případy správy hesel, každá s nevyhazující variantou s předponou Try.

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

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

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

Podepisování a ověřování pomocí PdfFileSignature

PdfFileSignature podepisuje, certifikuje a kontroluje digitální podpisy na svázaném dokumentu. Sign(sigName, reason, contact, location, signature) aplikuje nový podpis do existujícího pole podpisu; Certify aplikuje certifikační podpis. GetSignatureNames(onlyEmpty) a GetBlankSignatureNames() vracejí pole podpisů dokumentu jako hodnoty SignatureName, a VerifySignature(sigName) / IsCoversWholeDocument (sigName) kontrolují platnost a pokrytí. RemoveSignature a RemoveSignatures() odstraňují existující podpisy a SetCertificate(pfxFile, password) poskytuje přihlašovací údaje pro podepisování před voláním Sign.

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

Razení záhlaví, zápatí a číslování stránek pomocí PdfFileStamp

PdfFileStamp překrývá opakující se obsah na každé stránce svázaného souboru. AddPageNumber(format) razí štítek s číslem stránky pomocí počátečního čísla a volitelných explicitních souřadnic; AddHeader(text, topMargin) a AddFooter(text, bottomMargin) přidávají opakující se text záhlaví/zápatí na zadaný okraj, s přetížením pro levý/pravý okraj. KeepSecurity zachovává jakékoli existující šifrování výstupního souboru a Close() finalizuje a uvolní svázaný dokument.

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

Čtení a zápis informací o dokumentu pomocí PdfFileInfo

PdfFileInfo čte a přepisuje klasický PDF /Info slovník a základní geometrie na stránku, aniž by otevřel celý objektový model. Author, Title, Subject, Keywords, CreationDate a ModDate jsou vlastnosti pro čtení/zápis; Producer a GetPdfVersion() jsou pouze pro čtení. GetPageWidth, GetPageHeight a GetPageRotation vrací geometrie na stránku podle čísla stránky a IsEncrypted() / HasOpenPassword() / HasEditPassword() hlásí stav ochrany dokumentu. SaveNewInfo(outputFile) zapíše změny zpět.

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

Přesouvání stránek pomocí PdfPageEditor

PdfPageEditor přesouvá, mění velikost a otáčí obsah stránky jako blok. MovePosition(offsetX, offsetY) posouvá obsah na stránkách vybraných pomocí ProcessPages; Zoom jej škáluje. Alignment (je AlignmentType — Left, Center nebo Right, každý získaný z odpovídající statické metody) a VerticalAlignment (je VerticalAlignmentType — Top, Center, Bottom) řídí, jak je obsah umístěn v cílovém PageSize, jakmile se spustí ApplyChanges(). GetPageRotation čte aktuální otočení stránky ve stupních.

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

Správa XMP metadat pomocí PdfXmpMetadata

PdfXmpMetadata je mapově podobná fasáda nad XMP paketem dokumentu. Add(key, value), Remove(key), Contains(key) / ContainsKey(key) a TryGetValue(key, value) spravují jednotlivé položky; Keys() a Values() vypisují celý paket. RegisterNamespaceURI(prefix, namespaceURI) deklaruje vlastní XMP jmenný prostor, než do něj přidáte vlastnosti. Známé názvy vlastností jsou uvedeny v DefaultMetadataProperties (CreateDate, CreatorTool, Identifier, ModifyDate, Nickname, Thumbnails a dalších) a PropertyFlag (ReadOnly, Required, NoExport) popisuje schématová omezení registrované vlastnosti.

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

Tipy a osvědčené postupy

• Každá fasáda dodržuje stejný BindPdf (nebo konstruktor přijímající název souboru) → operace → sekvenci Save/Close — naučení jedné fasády se přímo přenáší na další.
• Upřednostněte metody s předponou Try na PdfFileEditor a PdfFileSecurity při zpracování souborů z nedůvěryhodného nebo nepředvídatelného zdroje — v případě selhání vrací false místo vyhození výjimky.
• Metody PdfFileEditor přijímají cesty k souborům, nikoli svázaný Document — nemusíte sami otevírat zdrojový soubor před voláním Concatenate, Extract nebo SplitFromFirst.
• Fasády obalují hlavní objektový model místo jeho nahrazení: Facade odhaluje podkladový Document() pro případy, kdy metoda fasády nepokrývá.
• Zavolejte Close() (nebo nechte fasádu vyjít z dosahu, pokud je to podporováno), jakmile dokončíte práci se svázaným dokumentem, aby se uvolnil podkladový souborový handle.

Časté problémy

FAQ

Jaký je rozdíl mezi fasádou a jádrovým Dokumentem API?

Fasády poskytují malý, úkolově orientovaný soubor metod pro jednu práci—vyplnění formuláře, sloučení souborů, razítkování stránek. Jádro API (Document, Page, Annotation) poskytuje plný přístup ke každému PDF objektu. Fasády, které vystavují Document() (prostřednictvím základní třídy Facade), vám umožní vrátit se k jádrovému modelu pro cokoli, co metoda fasády nepokrývá.

Musím volat BindPdf před každou metodou fasády?

Ano, pro fasády, které implementují IFacade—BindPdf (nebo ekvivalentní přetížení konstruktoru, jako u PdfExtractor(doc)) musí být spuštěno před jakoukoli operací, která čte nebo mění připojený dokument.

Lze operace PdfFileEditor řetězit?

Každá metoda PdfFileEditor načte svůj vstupní soubor a zapíše svůj výstupní soubor, takže operace řetězíte tak, že výstupní soubor jedné metody předáte jako vstupní soubor dalšího volání—například Concatenate do merged.pdf, pak Extract z merged.pdf.

Které fasády podporují režim nevyhazování chyb?

PdfFileEditor (TryConcatenate, TryAppend, TryExtract, TrySplitFromFirst a související Try* metody) a PdfFileSecurity (TryEncryptFile, TryDecryptFile, TrySetPrivilege, TryChangePassword) oba nabízejí alternativy s předponou Try, které vracejí bool místo vyhození.

API Reference Shrnutí

Viz také:

• Aspose.PDF — Enterprise Documentation