Cepheler API

Facade’lar API

A facade çekirdek üzerindeki basitleştirilmiş, görev odaklı bir sarmalayıcıdır Document / Page / Annotation nesne modeli. Sayfa ağacını kendiniz dolaşmak yerine, bir facade’ı kaynak PDF’ye bağlar, az sayıda yüksek seviyeli yöntemi çağırırsınız ve sonucu kaydedersiniz. Her facade Aspose::Pdf::Facades aynı minimal sözleşmeyi tanımlayan IFacade (BindPdf, Close) ve, facade çıktısı ürettiğinde, ISaveableFacade (Save). Soyut Facade and SaveableFacade temel sınıflar, aşağıdaki somut editörlerin üzerine inşa ettiği varsayılan bind/close/save uygulamasını sağlar: PdfAnnotationEditor, PdfBookmarkEditor, PdfContentEditor, PdfConverter, PdfExtractor, PdfFileEditor, PdfFileInfo, PdfFileSecurity, PdfFileSignature, PdfFileStamp, PdfPageEditor, PdfXmpMetadata, ve form odaklı FormEditor / FormFieldFacade çift.

Facade temel sınıfları ve bind/save yaşam döngüsü

IFacade, BindPdf(srcFile)‘i (aynı zamanda bellek içi bir Document kabul edecek şekilde aşırı yüklenir) ve Close()‘ü bildirir. ISaveableFacade, çıktı yazan facade’ler için Save(destFile) ekler. Facade, IFacade‘yi uygular ve bağlı Document()‘i ortaya çıkarır, böylece bir facade yöntemi ihtiyacınızı karşılamadığında temel nesne modeline geri dönebilirsiniz; SaveableFacade, Facade‘ı Save uygulamasıyla genişletir. Aşağıdaki her somut editör bu yapıyı miras alır, böylece aynı bind → operate → save deseni tüm Facade’lar API boyunca geçerlidir.

AcroForm alanlarını doldurma ve düzenleme

FormEditor, zaten bağlı bir belgede AcroForm alanlarını ekler, kaldırır, yeniden adlandırır ve konumlarını değiştirir. AddField(fieldType, fieldName, pageNum, llx, lly, urx, ury), belirtilen sayfa koordinatlarında verilen FieldType (Text, CheckBox, Radio, ComboBox, ListBox, PushButton, MultiLineText, Barcode, Signature, Image, Numeric, DateTime) tipinde yeni bir alan oluşturur. RemoveField, RenameField, MoveField ve SetFieldAttribute mevcut alanları yönetir, ve SetFieldScript / AddFieldScript JavaScript eylemlerini ekler. SubmitFlag (bir SubmitFormFlag değeri — Fdf, Html, Xfdf, FdfWithComments, XfdfWithComments veya Pdf) bir gönder düğmesinin form verilerini nasıl post edeceğini kontrol eder, ve SetSubmitUrl hedef uç noktayı ayarlar.

Her yeni alanın görsel görünümü, bir FormFieldFacade döndüren FormEditor.Facade() aracılığıyla kontrol edilir. Font özelliği bir FontStyle değeri (Helvetica, HelveticaBold, Courier, TimesRoman, Symbol ve ilgili varyantlar) alır, TextEncoding bir EncodingType (Winansi, Macroman, Identity_h, Identity_v, Cp1250, Cp1252, Cp1257) alır ve BorderStyle / BorderWidth alanın kenarlığını ayarlar.

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

Taslakları PdfBookmarkEditor ile yönetme

PdfBookmarkEditor PDF taslak girişlerini oluşturur, çıkarır, değiştirir ve kaldırır. CreateBookmarks(), bağlanmış belgeye bir Bookmarks koleksiyonu yazar (her giriş, iç içe taslaklar için Title, PageNumber, Action, Level, Open ve ChildItems içeren bir Bookmark’dir). ExtractBookmarks(), mevcut taslağı bir Bookmarks koleksiyonu olarak geri okur ve DeleteBookmarks() — isteğe bağlı bir title filtresi ile — girişleri kaldırır. ExportBookmarksToXML / ImportBookmarksWithXML, bir taslağı XML dosyası üzerinden çift yönlü aktarır, ve ExtractBookmarksToHTML / ExportBookmarksToHtml, taslağı bir HTML sayfa olarak render eder.

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

Ek açıklamaları PdfAnnotationEditor ile düzenleme

PdfAnnotationEditor, tüm belge boyunca ek açıklamaları düzleştirir ve içe aktarır. FlatteningAnnotations(), ek açıklamaları sayfa içerik akışına birleştirir, böylece etkileşimli nesneler yerine statik içerik olarak render edilir; start/end sayfa aralığı ve bir ek açıklama türü alan aşırı yükleme işlemi sınırlar. ImportAnnotationsFromXfdf / ImportAnnotationsFromFdf, harici FDF/XFDF dosyalarından ek açıklamaları getirir, ve DeleteAnnotations() (veya tek bir tür için DeleteAnnotations(annotType)) onları kaldırır.

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

Sayfa içeriğini PdfContentEditor ile yeniden yazma

PdfContentEditor, sayfayı yeniden oluşturmak yerine zaten oluşturulmuş bir sayfanın içerik akışını düzenler. ReplaceText(srcText, destText), belge genelinde eşleşen metni bulur ve değiştirir; tek bir sayfaya sınırlayan aşırı yüklemeler mevcuttur. ReplaceImage(pageNum, imageNum, fileName) ve DeleteImage(pageNum, imageNum), mevcut bir görüntü XObject’ini değiştirir veya kaldırır. DeleteStampById / HideStampById / ShowStampById / MoveStampById, bir sayfadaki damga nesnelerini yönetir (damganın temel içeriği Form veya Image olabilir, StampType enum’ına göre), ve AddDocumentAdditionalAction / AddDocumentAttachment, belge düzeyinde JavaScript eylemlerini ve dosya eklerini ekler.

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

Metin ve ekleri PdfExtractor ile çıkarma

PdfExtractor, ya BindPdf ile bağlanabilir ya da zaten açık bir Document‘den doğrudan oluşturulabilir. ExtractText(), ardından HasNextPageText() / GetNextPageText(outputFile), belgeyi sayfa sayfa dolaşır. Gömülü dosyalar için, GetAttachNames() mevcut ekleri listeler ve GetAttachment( outputPath) bir sonraki ek’i diske yazar:

#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) gömülü raster görüntüleri, GetNextPageText sayfaları dolaştığı aynı şekilde çıkarır.

PdfFileEditor ile dosyaları birleştirme ve bölme

PdfFileEditor, bağlanmış bir Document yerine dosya yolları üzerinde çalışır, bu yüzden her yöntem giriş/çıkış dosya adlarını doğrudan alır. Concatenate (ve atma yapmayan TryConcatenate) iki ya da daha fazla dosyayı birleştirir; Append bir dosyadan diğerine sayfa aralığı ekler; Extract bir sayfa aralığını ya da tek bir sayfayı yeni bir dosyaya çeker; Delete bir sayfayı kaldırır; ve SplitFromFirst / SplitToEnd / SplitToPages / SplitToBulks bir belgeyi bir sayfada, sayfa sayfasına veya sabit boyutlu parçalar halinde böler. MakeBooklet ve MakeNUp sayfaları kitapçık ya da N-up baskı için yeniden düzenler, ve ResizeContents / AddMargins / AddPageBreak bir dosya boyunca sayfa geometrisini ayarlar. Çoğu işlem, başarısızlıkta istisna atmak yerine false döndüren Try ön ekli bir karşılığına sahiptir.

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

PdfConverter ile sayfaları görüntülere render etme

PdfConverter, bağlanmış belge sayfalarını raster formatlarına render eder. DoConvert(), yineleme için sayfa aralığını (StartPage / EndPage) hazırlar; HasNextImage () / GetNextImage(outputFile) ise sayfalar arasında tek tek ilerler. SaveAsTIFF, tüm aralığı tek bir çok sayfalı TIFF’e yazar, çözünürlük, sıkıştırma ve TiffSettings için aşırı yüklemelerle. RenderingOptions ve Resolution, rasterleştirme kalitesini kontrol eder, ve ImageMergeMode (Vertical, Horizontal, Center) bir çağırıcı birden fazla render edilmiş sayfa görüntüsünü tek bir görüntüye birleştirdiğinde nasıl birleştirileceğini yönetir.

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

PdfFileSecurity ile belgeleri şifreleme

PdfFileSecurity, bir kaynak dosyayı bağlar ve şifreleme uygular ya da kaldırır. EncryptFile(userPassword, ownerPassword, privilege, keySize), bir DocumentPrivilege (varsayılan yapıcı ve AllowPrint, AllowCopy, AllowModifyContents gibi boolean ayarlayıcılarla oluşturulan) ve bir KeySize (x40, x128 veya x256) ile şifreler; beşinci cipher argümanını alan aşırı yükleme, Algorithm (RC4 veya AES) seçimini açıkça belirler. DecryptFile( ownerPassword), ChangePassword ve SetPrivilege, kalan şifre yönetimi durumlarını kapsar, her biri atma yapmayan Try ön ekli bir varyante sahiptir.

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

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

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

PdfFileSignature ile imzalama ve doğrulama

PdfFileSignature bağlanmış bir belgede dijital imzaları imzalar, onaylar ve inceler. Sign(sigName, reason, contact, location, signature) mevcut bir imza alanına yeni bir imza uygular; Certify bir onaylayıcı imza uygular. GetSignatureNames(onlyEmpty) ve GetBlankSignatureNames() belgenin imza alanlarını SignatureName değerleri olarak döndürür, ve VerifySignature(sigName) / IsCoversWholeDocument (sigName) geçerlilik ve kapsamı kontrol eder. RemoveSignature ve RemoveSignatures() mevcut imzaları kaldırır, ve SetCertificate(pfxFile, password), Sign çağrılmadan önce imzalama kimlik bilgilerini sağlar.

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

Başlıkları, dipnotları ve sayfa numaralarını PdfFileStamp ile damgalama.

PdfFileStamp, bağlanmış bir dosyanın her sayfasına tekrarlayan içeriği üst üste bindirir. AddPageNumber(format), başlangıç numarası ve isteğe bağlı açık koordinatlar kullanarak bir sayfa numarası etiketi damgalar; AddHeader(text, topMargin) ve AddFooter(text, bottomMargin), belirli bir kenarda tekrarlayan başlık/dipnot metni ekler, sol/sağ kenarlar için aşırı yüklemelerle. KeepSecurity, çıktı dosyasındaki mevcut şifrelemeyi korur ve Close(), bağlanmış belgeyi sonlandırır ve serbest bırakır.

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

PdfFileInfo ile belge bilgilerini okuma ve yazma.

PdfFileInfo, tam nesne modelini açmadan klasik PDF /Info sözlüğünü ve sayfa başına temel geometrileri okur ve yeniden yazar. Author, Title, Subject, Keywords, CreationDate ve ModDate okuma/yazma özellikleridir; Producer ve GetPdfVersion() sadece okuma içindir. GetPageWidth, GetPageHeight ve GetPageRotation, sayfa numarasına göre sayfa başına geometriyi döndürür, ve IsEncrypted() / HasOpenPassword() / HasEditPassword() belgenin koruma durumunu rapor eder. SaveNewInfo(outputFile), değişiklikleri geri yazar.

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

PdfPageEditor ile sayfaları yeniden konumlandırma.

PdfPageEditor, sayfa içeriğini bir blok olarak taşır, yeniden boyutlandırır ve döndürür. MovePosition(offsetX, offsetY), ProcessPages tarafından seçilen sayfalardaki içeriği kaydırır; Zoom ise ölçeklendirir. Alignment (bir AlignmentType — Left, Center veya Right, her biri ilgili statik yöntemden elde edilir) ve VerticalAlignment (bir VerticalAlignmentType — Top, Center, Bottom) ApplyChanges() çalıştırıldığında hedef PageSize içinde içeriğin nasıl konumlandırılacağını kontrol eder. GetPageRotation, bir sayfanın mevcut dönüş açısını derece cinsinden okur.

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

PdfXmpMetadata ile XMP üst verilerini yönetme.

PdfXmpMetadata, bir belgenin XMP paketinin harita benzeri bir dış görünüşüdür. Add(key, value), Remove(key), Contains(key) / ContainsKey(key) ve TryGetValue(key, value) bireysel girdileri yönetir; Keys() ve Values() tüm paketi numaralandırır. RegisterNamespaceURI(prefix, namespaceURI), içinde özellik eklemeden önce özel bir XMP ad alanı bildirir. Bilinen özellik adları DefaultMetadataProperties (CreateDate, CreatorTool, Identifier, ModifyDate, Nickname, Thumbnails ve diğerleri) içinde listelenir ve PropertyFlag (ReadOnly, Required, NoExport) kaydedilmiş bir özelliğin şema kısıtlamalarını tanımlar.

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

İpuçları ve En İyi Uygulamalar

• Her dış görünüş aynı BindPdf (veya dosya adı alan bir yapıcı) → işlet → Save/Close dizisini izler — bir dış görünüşü öğrenmek bir sonrakine doğrudan aktarılır.
• Güvenilmeyen veya öngörülemeyen bir kaynaktan dosyaları işlerken PdfFileEditor ve PdfFileSecurity üzerindeki Try ön ekli yöntemleri tercih edin — başarısızlıkta istisna fırlatmak yerine false döner.
• PdfFileEditor yöntemleri dosya yollarını alır, bağlanmış bir Document almaz — Concatenate, Extract veya SplitFromFirst çağırmadan önce kaynak dosyayı kendiniz açmanıza gerek yok.
• Dış görünümler çekirdek nesne modelini değiştirmek yerine sarar: Facade, bir dış görünüş yöntemi kapsamayan durumlar için alttaki Document() öğesini ortaya çıkarır.
• Bağlanmış bir belgeyle işiniz bittiğinde alttaki dosya tanıtıcısını serbest bırakmak için Close()‘ı çağırın (veya destekleniyorsa dış görünüşün kapsam dışına çıkmasına izin verin).

Yaygın Sorunlar

FAQ

Facade ile temel Document API arasındaki fark nedir?

Facade’ler tek bir iş için — form doldurma, dosya birleştirme, sayfa damgalama — küçük, görev odaklı bir yöntem yüzeyi sağlar. Çekirdek API (Document, Page, Annotation) her PDF nesnesine tam erişim verir. Document()‘ı (Facade temel sınıfı aracılığıyla) ortaya çıkaran facade’ler, bir facade yöntemi kapsamıyorsa çekirdek modele geri dönmenizi sağlar.

Her facade yöntemi öncesinde BindPdf çağırmam gerekiyor mu?

Evet, IFacade‘ı uygulayan facade’ler için — BindPdf (veya PdfExtractor(doc) gibi eşdeğer bir yapıcı aşırı yüklemesi) bağlanan belgeyi okuyan veya değiştiren herhangi bir işlemden önce çalıştırılmalıdır.

PdfFileEditor işlemleri zincirlenebilir mi?

Her PdfFileEditor yöntemi kendi giriş dosyasını okur ve kendi çıkış dosyasını yazar, bu yüzden bir yöntemin çıkış dosyasını bir sonraki çağrının giriş dosyası olarak kullanarak işlemleri zincirleyebilirsiniz — örneğin, Concatenate‘ı merged.pdf‘ye, ardından Extract‘ı merged.pdf‘ten.

Hangi facade’ler hata fırlatmayan bir mod destekliyor?

PdfFileEditor (TryConcatenate, TryAppend, TryExtract, TrySplitFromFirst ve ilgili Try* yöntemleri) ve PdfFileSecurity (TryEncryptFile, TryDecryptFile, TrySetPrivilege, TryChangePassword) her ikisi de Try-önekli alternatifler sunar ve atmak yerine bool döndürür.

API Reference Özeti

Ayrıca Bakınız

• Aspose.PDF — Enterprise Documentation