Fasádok API

Felületek API

A facade egy egyszerűsített, feladatra orientált csomagoló a mag felett Document / Page / Annotation objektummodell. Ahelyett, hogy saját maga bejárná az oldalfát, egy facade-et köt egy forrás PDF-hez, meghív egy kis halmaz magas szintű metódust, és elmenti az eredményt. Minden facade a Aspose::Pdf::Facades implementálja ugyanazt a minimális szerződést, amelyet IFacade (BindPdf, Close) és, ahol a facade kimenetet állít elő, ISaveableFacade (Save). Az absztrakt Facade and SaveableFacade alaposztályok biztosítják az alapértelmezett bind/close/save implementációt, amelyre az alább látható konkrét szerkesztők épülnek: PdfAnnotationEditor, PdfBookmarkEditor, PdfContentEditor, PdfConverter, PdfExtractor, PdfFileEditor, PdfFileInfo, PdfFileSecurity, PdfFileSignature, PdfFileStamp, PdfPageEditor, PdfXmpMetadata, és az űrlap-központú FormEditor / FormFieldFacade pár.

Facade alaposztályok és a bind/save életciklus

IFacade deklarálja a BindPdf(srcFile)-t (továbbá túlterhelve, hogy elfogadjon egy memóriában lévő Document) és a Close()-t. ISaveableFacade hozzáadja a Save(destFile)-t azoknak a facadeknek, amelyek kimenetet írnak. Facade megvalósítja a IFacade-t, és elérhetővé teszi a kötött Document()-t, hogy visszatérhessen a core objektummodellbe, ha egy facade metódus nem fedi le a szükségeset; SaveableFacade kibővíti a Facade-t a Save implementációval. Minden alábbi konkrét szerkesztő örökli ezt a struktúrát, így ugyanaz a bind → operate → save minta érvényes a teljes Felületek API-ban.

A AcroForm mezők kitöltése és szerkesztése

FormEditor hozzáad, eltávolít, átnevez és áthelyez AcroForm mezőket egy már kötött dokumentumban. AddField(fieldType, fieldName, pageNum, llx, lly, urx, ury) új mezőt hoz létre a megadott FieldType típusú (Text, CheckBox, Radio, ComboBox, ListBox, PushButton, MultiLineText, Barcode, Signature, Image, Numeric, DateTime) a megadott oldalkoordínátákon. RemoveField, RenameField, MoveField és SetFieldAttribute a meglévő mezőket kezelik, és a SetFieldScript / AddFieldScript JavaScript műveleteket csatolják. SubmitFlag (egy SubmitFormFlag érték — Fdf, Html, Xfdf, FdfWithComments, XfdfWithComments vagy Pdf) határozza meg, hogyan küldi el a beküldés gomb az űrlap adatokat, és a SetSubmitUrl beállítja a cél végpontot.

Az egyes új mezők vizuális megjelenését a FormEditor.Facade() szabályozza, amely egy FormFieldFacade-t ad vissza. Ennek Font tulajdonsága egy FontStyle értéket vesz fel (Helvetica, HelveticaBold, Courier, TimesRoman, Symbol és kapcsolódó változatok), a TextEncoding egy EncodingType-t (Winansi, Macroman, Identity_h, Identity_v, Cp1250, Cp1252, Cp1257) kap, és a BorderStyle / BorderWidth állítja be a mező keretét.

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

Vázlatok kezelése a PdfBookmarkEditor segítségével

PdfBookmarkEditor létrehozza, kicsomagolja, módosítja és eltávolítja a PDF vázlatbejegyzéseket. CreateBookmarks() egy Bookmarks gyűjteményt (minden bejegyzés egy Bookmark Title, PageNumber, Action, Level, Open és ChildItems mezőkkel a beágyazott vázlatokhoz) ír a kötött dokumentumba. ExtractBookmarks() a meglévő vázlatot visszaolvassa egy Bookmarks gyűjteményként, és DeleteBookmarks() — opcionális title szűrővel — eltávolítja a bejegyzéseket. ExportBookmarksToXML / ImportBookmarksWithXML egy vázlatot egy XML fájlon keresztül körbehalad, és ExtractBookmarksToHTML / ExportBookmarksToHtml a vázlatot HTML oldalként rendereli.

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

Megjegyzések szerkesztése a PdfAnnotationEditor segítségével

PdfAnnotationEditor laposítja és importálja a megjegyzéseket az egész dokumentumban. FlatteningAnnotations() egyesíti a megjegyzéseket az oldal tartalomfolyamába, így statikus tartalomként jelennek meg az interaktív objektumok helyett; a start/end oldaltartományt és egy megjegyzéstípust fogadó overload korlátozza a műveletet. ImportAnnotationsFromXfdf / ImportAnnotationsFromFdf külső FDF/XFDF fájlokból hozza be a megjegyzéseket, és DeleteAnnotations() (vagy DeleteAnnotations(annotType) egyetlen típus esetén) eltávolítja őket.

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

Oldaltartalom újraírása a PdfContentEditor segítségével

PdfContentEditor egy már létrehozott oldal tartalomfolyamát szerkeszti az oldal újbóli felépítése helyett. ReplaceText(srcText, destText) megtalálja és kicseréli a megfelelő szöveget a dokumentumban, olyan overloadokkal, amelyek a cserét egyetlen oldalra korlátozzák. ReplaceImage(pageNum, imageNum, fileName) és DeleteImage(pageNum, imageNum) kicserélik vagy eltávolítják a meglévő kép XObject-et. DeleteStampById / HideStampById / ShowStampById / MoveStampById pecsét objektumokat kezelnek egy oldalon (a pecsét alaptartalma Form vagy Image a StampType felsoroló típus szerint), és AddDocumentAdditionalAction / AddDocumentAttachment dokumentumszintű JavaScript műveleteket és fájlcsatolmányokat csatol.

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

Szöveg és csatolmányok kinyerése a PdfExtractor segítségével

PdfExtractor kötve lehet akár BindPdf segítségével, akár közvetlenül egy már nyitott Document alapján létrehozva. ExtractText() után a HasNextPageText() / GetNextPageText(outputFile) a dokumentumot oldalanként bejárja. Beágyazott fájlok esetén a GetAttachNames() felsorolja a jelen lévő csatolmányokat, a GetAttachment( outputPath) pedig a következőt a lemezre írja:

#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) beágyazott raszteres képeket ugyanúgy vonja ki, ahogy GetNextPageText lapokat jár.

Fájlok összeállítása és felosztása a PdfFileEditor segítségével.

PdfFileEditor fájlútvonalakon dolgozik, nem egy kötött Document objektumon, ezért minden metódus közvetlenül bemeneti/kimeneti fájlneveket vesz. Concatenate (és a nem dobó TryConcatenate) egyesíti két vagy több fájlt; Append egy oldaltartományt szúr be egy fájlból egy másikba; Extract egy oldaltartományt vagy egyetlen oldalt áthelyez egy új fájlba; Delete eltávolít egy oldalt; és SplitFromFirst / SplitToEnd / SplitToPages / SplitToBulks egy dokumentumot egy oldalon, oldalanként vagy rögzített méretű darabokra osztja. MakeBooklet és MakeNUp átrendezik az oldalakat füzet vagy N-up nyomtatáshoz, és ResizeContents / AddMargins / AddPageBreak módosítják az oldalgeometriát a fájlban. A legtöbb műveletnek van egy Try-prefixel ellátott megfelelője, amely false-t ad vissza ahelyett, hogy hibát dobna.

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

Oldalak képekké renderelése a PdfConverter segítségével.

PdfConverter a kötött dokumentum oldalakat raszteres formátumokba rendereli. DoConvert() előkészíti az oldaltartományt (StartPage / EndPage) az iteráláshoz; HasNextImage () / GetNextImage(outputFile) ezután egyesével lépked az oldalakon. SaveAsTIFF az egész tartományt egyetlen többoldalas TIFF-be írja, felülterhelésekkel a felbontásra, tömörítésre és TiffSettings-ra. RenderingOptions és Resolution szabályozzák a rasterizálás minőségét, és ImageMergeMode (Vertical, Horizontal, Center) határozza meg, hogyan kombinálódnak a több renderelt oldalképek, amikor a hívó egyetlen képpé egyesíti őket.

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

Dokumentumok titkosítása a PdfFileSecurity segítségével.

PdfFileSecurity egy forrásfájlt köt és alkalmaz vagy eltávolít titkosítást. EncryptFile(userPassword, ownerPassword, privilege, keySize) titkosít egy DocumentPrivilege (alapértelmezett konstruktorral és olyan logikai beállítókkal, mint AllowPrint, AllowCopy, AllowModifyContents) és egy KeySize (x40, x128 vagy x256) segítségével; az a túlterhelés, amely ötödik cipher argumentumot kap, kifeexplicit módon kiválasztja a Algorithm (RC4 vagy AES) értékét. DecryptFile( ownerPassword), ChangePassword és SetPrivilege lefedik a maradék jelszó-kezelési eseteket, mindegyik egy nem dobó Try-prefixel változattal.

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

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

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

Aláírás és ellenőrzés a PdfFileSignature segítségével.

PdfFileSignature aláír, tanúsít és ellenőrzi a digitális aláírásokat egy kötött dokumentumon. Sign(sigName, reason, contact, location, signature) új aláírást helyez el egy meglévő aláírásmezőben; Certify tanúsító aláírást alkalmaz. GetSignatureNames(onlyEmpty) és GetBlankSignatureNames() visszaadják a dokumentum aláírásmezőit SignatureName értékekként, és a VerifySignature(sigName) / IsCoversWholeDocument (sigName) ellenőrzik a hitelességet és a lefedettséget. RemoveSignature és RemoveSignatures() eltávolítják a meglévő aláírásokat, és a SetCertificate(pfxFile, password) biztosítja az aláírási hitelesítést a Sign meghívása előtt.

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

Fejlécek, láblécek és oldalszámok bélyegzése a(z) PdfFileStamp segítségével.

PdfFileStamp átfedi a megismétlődő tartalmat a kötött fájl minden oldalán. AddPageNumber(format) bélyegzi az oldalszám címkét egy kezdő számmal és opcionális kifejezett koordinátákkal; AddHeader(text, topMargin) és AddFooter(text, bottomMargin) hozzáadják az ismétlődő fejléc/lábléc szöveget egy adott margón, bal/jobb margókra is kiterjesztett változatokkal. KeepSecurity megőrzi a kimeneti fájl esetleges meglévő titkosítását, és Close() befejezi és kiadja a kötött dokumentumot.

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

Dokumentum információk olvasása és írása a(z) PdfFileInfo segítségével.

PdfFileInfo olvassa és újraírja a klasszikus PDF /Info szótárat és az alapvető oldalonkénti geometriát anélkül, hogy megnyitná a teljes objektummodellt. Author, Title, Subject, Keywords, CreationDate és ModDate olvasás/írás tulajdonságok; Producer és GetPdfVersion() csak olvashatóak. GetPageWidth, GetPageHeight és GetPageRotation oldalonkénti geometriát adnak vissza oldal száma szerint, és a IsEncrypted() / HasOpenPassword() / HasEditPassword() jelentik a dokumentum védelmi állapotát. SaveNewInfo(outputFile) visszaírja a változásokat.

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

Oldalak áthelyezése a(z) PdfPageEditor segítségével.

PdfPageEditor mozgatja, átméretezi és elforgatja az oldal tartalmát blokként. MovePosition(offsetX, offsetY) eltolja a tartalmat a ProcessPages által kiválasztott oldalakon; Zoom méretezi azt. Alignment (egy AlignmentType — Left, Center vagy Right, mindegyik a megfelelő statikus metódusból származik) és VerticalAlignment (egy VerticalAlignmentType — Top, Center, Bottom) szabályozzák, hogy a tartalom hogyan helyezkedik el a cél PageSize belsejében, miután a ApplyChanges() lefut. GetPageRotation elolvassa egy oldal aktuális forgatását fokokban.

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

XMP metaadatok kezelése a(z) PdfXmpMetadata segítségével.

PdfXmpMetadata egy térkép-szerű facade egy dokumentum XMP csomagja felett. Add(key, value), Remove(key), Contains(key) / ContainsKey(key), és TryGetValue(key, value) egyedi bejegyzéseket kezelnek; Keys() és Values() felsorolják az egész csomagot. RegisterNamespaceURI(prefix, namespaceURI) egy egyéni XMP névtér definiálását teszi lehetővé, mielőtt tulajdonságokat adna hozzá. A jól ismert tulajdonságneveket a DefaultMetadataProperties (CreateDate, CreatorTool, Identifier, ModifyDate, Nickname, Thumbnails és egyebek) tartalmazza, és a PropertyFlag (ReadOnly, Required, NoExport) leírja egy regisztrált tulajdonság sémakorlátait.

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

Tippek és bevált gyakorlatok

• Minden facade ugyanazt a BindPdf (vagy egy fájlnevet elfogadó konstruktort) → működés → Save/Close sorozatot követi — egy facade megtanulása közvetlenül átvihető a következőre.
• Előnyben részesítsd a Try előtagú metódusokat a PdfFileEditor és PdfFileSecurity esetén, ha megbízhatatlan vagy kiszámíthatatlan forrásból származó fájlokat dolgozol fel — hibák esetén false értéket adnak vissza a kivétel dobás helyett.
• A PdfFileEditor metódusok fájlútvonalakat várnak, nem egy kötött Document -t — nem kell saját maga megnyitnia a forrásfájlt, mielőtt meghívná a Concatenate, Extract vagy SplitFromFirst metódusokat.
• A facades a mag objektummodellt burkolják, nem helyettesítik: a Facade a rejtett Document() -t teszi elérhetővé azokban az esetekben, amikor egy facade metódus nem fedi le.
• Hívd meg a Close() (vagy hagyd, hogy a facade hatókörön kívülre kerüljön, ahol támogatott) miután befejezted a kötött dokumentummal végzett műveleteket, hogy felszabadítsd a rejtett fájlkezelőt.

Gyakori problémák

FAQ

Mi a különbség egy facade és a core Document API között?

A facade-k kis, feladatra szabott metódusfelületet biztosítanak egyetlen feladathoz — űrlap kitöltése, fájlok egyesítése, oldalak pecsételése. A core API (Document, Page, Annotation) teljes hozzáférést ad minden PDF objektumhoz. Azok a facade-k, amelyek Document()-t (a Facade alaposztályon keresztül) teszik elérhetővé, lehetővé teszik, hogy visszatérj a core modellbe minden olyan esetben, amelyet egy facade metódus nem fed le.

Meg kell hívnom a BindPdf-t minden facade metódus előtt?

Igen, azoknál a facade-oknál, amelyek implementálják a IFacade-t — a BindPdf (vagy egy ekvivalens konstruktor túlterhelés, mint a PdfExtractor(doc)) futnia kell minden olyan művelet előtt, amely olvassa vagy módosítja a kötött dokumentumot.

Láncolhatók a PdfFileEditor műveletek?

Minden PdfFileEditor metódus saját bemeneti fájlt olvas és saját kimeneti fájlt ír, így a műveleteket úgy láncolhatod, hogy egy metódus kimeneti fájlját a következő hívás bemeneti fájljaként használod — például a Concatenate-t a merged.pdf-ba, majd a Extract-t a merged.pdf-ből.

Mely facade-k támogatják a nem dobó hibamódot?

PdfFileEditor (TryConcatenate, TryAppend, TryExtract, TrySplitFromFirst, és a kapcsolódó Try* metódusok) és PdfFileSecurity (TryEncryptFile, TryDecryptFile, TrySetPrivilege, TryChangePassword) egyaránt Try-prefixed alternatívákat kínálnak, amelyek bool-t adnak vissza a dobás helyett.

API Reference összefoglaló

Lásd még:

• Aspose.PDF — Enterprise Documentation