Fasad API

Fasad API

A facade adalah wrapper yang disederhanakan, berorientasi tugas, di atas inti Document / Page / Annotation model objek. Alih-alih menelusuri pohon halaman sendiri, Anda mengikat sebuah facade ke PDF sumber, memanggil sekumpulan kecil metode tingkat tinggi, dan menyimpan hasilnya. Setiap facade di Aspose::Pdf::Facades menerapkan kontrak minimal yang sama yang didefinisikan oleh IFacade (BindPdf, Close) dan, dimana facade menghasilkan output, ISaveableFacade (Save). Abstrak Facade and SaveableFacade kelas dasar menyediakan implementasi bind/close/save default yang dibangun oleh editor konkret di bawah ini: PdfAnnotationEditor, PdfBookmarkEditor, PdfContentEditor, PdfConverter, PdfExtractor, PdfFileEditor, PdfFileInfo, PdfFileSecurity, PdfFileSignature, PdfFileStamp, PdfPageEditor, PdfXmpMetadata, dan yang berfokus pada formulir FormEditor / FormFieldFacade pasangan.

Kelas dasar Facade dan siklus hidup bind/save

IFacade mendeklarasikan BindPdf(srcFile) (juga overload untuk menerima Document dalam memori) dan Close(). ISaveableFacade menambahkan Save(destFile) untuk facade yang menulis output. Facade mengimplementasikan IFacade dan mengekspos Document() yang terikat sehingga Anda dapat kembali ke model objek inti ketika metode facade tidak mencakup apa yang Anda perlukan; SaveableFacade memperluas Facade dengan implementasi Save. Setiap editor konkret di bawah ini mewarisi bentuk ini, sehingga pola bind → operate → save yang sama berlaku di seluruh Fasad API.

Mengisi dan mengedit bidang AcroForm

FormEditor menambahkan, menghapus, mengganti nama, dan memposisikan kembali bidang AcroForm pada dokumen yang sudah terikat. AddField(fieldType, fieldName, pageNum, llx, lly, urx, ury) membuat bidang baru dengan FieldType yang diberikan (Text, CheckBox, Radio, ComboBox, ListBox, PushButton, MultiLineText, Barcode, Signature, Image, Numeric, DateTime) pada koordinat halaman yang ditentukan. RemoveField, RenameField, MoveField, dan SetFieldAttribute mengelola bidang yang ada, dan SetFieldScript / AddFieldScript melampirkan aksi JavaScript. SubmitFlag (nilai SubmitFormFlag — Fdf, Html, Xfdf, FdfWithComments, XfdfWithComments, atau Pdf) mengontrol cara tombol submit mengirim data formulir, dan SetSubmitUrl menetapkan endpoint target.

Penampilan visual setiap bidang baru dikontrol melalui FormEditor.Facade(), yang mengembalikan sebuah FormFieldFacade. Properti Font-nya menerima nilai FontStyle (Helvetica, HelveticaBold, Courier, TimesRoman, Symbol, dan varian terkait), TextEncoding menerima sebuah EncodingType (Winansi, Macroman, Identity_h, Identity_v, Cp1250, Cp1252, Cp1257), dan BorderStyle / BorderWidth mengatur batas bidang.

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

Mengelola outline dengan PdfBookmarkEditor

PdfBookmarkEditor membuat, mengekstrak, memodifikasi, dan menghapus entri outline PDF. CreateBookmarks() menulis koleksi Bookmarks (setiap entri berupa Bookmark dengan Title, PageNumber, Action, Level, Open, dan ChildItems untuk outline bersarang) ke dalam dokumen yang terikat. ExtractBookmarks() membaca kembali outline yang ada sebagai koleksi Bookmarks, dan DeleteBookmarks() — dengan filter title opsional — menghapus entri. ExportBookmarksToXML / ImportBookmarksWithXML melakukan round-trip outline melalui file XML, dan ExtractBookmarksToHTML / ExportBookmarksToHtml merender outline sebagai halaman HTML.

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

Menyunting anotasi dengan PdfAnnotationEditor

PdfAnnotationEditor meratakan dan mengimpor anotasi di seluruh dokumen. FlatteningAnnotations() menggabungkan anotasi ke dalam aliran konten halaman sehingga mereka ditampilkan sebagai konten statis alih-alih objek interaktif; overload yang menerima rentang halaman start/end dan tipe anotasi membatasi operasi tersebut. ImportAnnotationsFromXfdf / ImportAnnotationsFromFdf membawa anotasi dari file FDF/XFDF eksternal, dan DeleteAnnotations() (atau DeleteAnnotations(annotType) untuk satu tipe) menghapusnya.

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

Menulis ulang konten halaman dengan PdfContentEditor

PdfContentEditor menyunting aliran konten halaman yang sudah dihasilkan alih-alih membangun ulang halaman. ReplaceText(srcText, destText) menemukan dan mengganti teks yang cocok di seluruh dokumen, dengan overload yang membatasi penggantian ke satu halaman. ReplaceImage(pageNum, imageNum, fileName) dan DeleteImage(pageNum, imageNum) menukar atau menghapus XObject gambar yang ada. DeleteStampById / HideStampById / ShowStampById / MoveStampById mengelola objek stempel pada halaman (konten dasar stempel adalah Form atau Image, sesuai enum StampType), dan AddDocumentAdditionalAction / AddDocumentAttachment melampirkan aksi JavaScript tingkat dokumen dan lampiran file.

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

Mengekstrak teks dan lampiran dengan PdfExtractor

PdfExtractor dapat diikat baik dengan BindPdf atau dibangun langsung dari Document yang sudah terbuka. ExtractText() diikuti oleh HasNextPageText() / GetNextPageText(outputFile) menjelajahi dokumen halaman per halaman. Untuk file yang disematkan, GetAttachNames() menampilkan daftar lampiran yang ada dan GetAttachment( outputPath) menulis lampiran berikutnya ke 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) mengekstrak gambar raster yang disematkan dengan cara yang sama GetNextPageText menelusuri halaman.

Menggabungkan dan memecah file dengan PdfFileEditor

PdfFileEditor beroperasi pada jalur file bukan pada Document yang terikat, sehingga setiap metode menerima nama file input/output secara langsung. Concatenate (dan TryConcatenate yang tidak melempar pengecualian) menggabungkan dua file atau lebih; Append menyisipkan rentang halaman dari satu file ke file lain; Extract mengambil rentang halaman atau halaman tunggal ke dalam file baru; Delete menghapus sebuah halaman; dan SplitFromFirst / SplitToEnd / SplitToPages / SplitToBulks membagi dokumen pada sebuah halaman, per halaman, atau menjadi potongan berukuran tetap. MakeBooklet dan MakeNUp menyusun ulang halaman untuk pencetakan booklet atau N-up, dan ResizeContents / AddMargins / AddPageBreak menyesuaikan geometri halaman di seluruh file. Sebagian besar operasi memiliki pasangan berawalan Try yang mengembalikan false alih-alih melempar saat gagal.

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

Merender halaman menjadi gambar dengan PdfConverter

PdfConverter merender halaman dokumen yang terikat ke format raster. DoConvert() menyiapkan rentang halaman (StartPage / EndPage) untuk iterasi; HasNextImage () / GetNextImage(outputFile) kemudian melangkah melalui halaman satu per satu. SaveAsTIFF menulis seluruh rentang ke dalam satu TIFF multi-halaman, dengan overload untuk resolusi, kompresi, dan TiffSettings. RenderingOptions dan Resolution mengontrol kualitas rasterisasi, dan ImageMergeMode (Vertical, Horizontal, Center) mengatur bagaimana beberapa gambar halaman yang dirender digabungkan ketika pemanggil menggabungkannya menjadi satu gambar.

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

Mengenkripsi dokumen dengan PdfFileSecurity

PdfFileSecurity mengikat file sumber dan menerapkan atau menghapus enkripsi. EncryptFile(userPassword, ownerPassword, privilege, keySize) mengenkripsi dengan DocumentPrivilege (dibuat dengan konstruktor default dan setter boolean seperti AllowPrint, AllowCopy, AllowModifyContents) dan KeySize (x40, x128, atau x256); overload yang menerima argumen cipher kelima memilih Algorithm (RC4 atau AES) secara eksplisit. DecryptFile( ownerPassword), ChangePassword, dan SetPrivilege mencakup kasus manajemen kata sandi yang tersisa, masing-masing dengan varian berawalan Try yang tidak melempar pengecualian.

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

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

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

Menandatangani dan memverifikasi dengan PdfFileSignature

PdfFileSignature menandatangani, mengesahkan, dan memeriksa tanda tangan digital pada dokumen yang terikat. Sign(sigName, reason, contact, location, signature) menerapkan tanda tangan baru ke bidang tanda tangan yang ada; Certify menerapkan tanda tangan sertifikasi. GetSignatureNames(onlyEmpty) dan GetBlankSignatureNames() mengembalikan bidang tanda tangan dokumen sebagai nilai SignatureName, dan VerifySignature(sigName) / IsCoversWholeDocument (sigName) memeriksa keabsahan dan cakupan. RemoveSignature dan RemoveSignatures() menghapus tanda tangan yang ada, dan SetCertificate(pfxFile, password) menyediakan kredensial penandatangan sebelum memanggil Sign.

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

Mencetak header, footer, dan nomor halaman dengan PdfFileStamp

PdfFileStamp menempatkan konten berulang pada setiap halaman file yang terikat. AddPageNumber(format) mencetak label nomor halaman menggunakan nomor awal dan koordinat eksplisit opsional; AddHeader(text, topMargin) dan AddFooter(text, bottomMargin) menambahkan teks header/footer berulang pada margin tertentu, dengan overload untuk margin kiri/kanan. KeepSecurity mempertahankan enkripsi yang ada pada file output, dan Close() menyelesaikan dan melepaskan dokumen yang terikat.

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

Membaca dan menulis informasi dokumen dengan PdfFileInfo

PdfFileInfo membaca dan menulis ulang kamus klasik PDF /Info serta geometri dasar per halaman tanpa membuka model objek lengkap. Author, Title, Subject, Keywords, CreationDate, dan ModDate adalah properti baca/tulis; Producer dan GetPdfVersion() hanya baca. GetPageWidth, GetPageHeight, dan GetPageRotation mengembalikan geometri per halaman berdasarkan nomor halaman, dan IsEncrypted() / HasOpenPassword() / HasEditPassword() melaporkan status perlindungan dokumen. SaveNewInfo(outputFile) menulis perubahan kembali.

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

Memposisikan ulang halaman dengan PdfPageEditor

PdfPageEditor memindahkan, mengubah ukuran, dan memutar konten halaman sebagai satu blok. MovePosition(offsetX, offsetY) menggeser konten pada halaman yang dipilih oleh ProcessPages; Zoom memperbesarnya. Alignment (sebuah AlignmentType — Left, Center, atau Right, masing-masing diperoleh dari metode statis yang cocok) dan VerticalAlignment (sebuah VerticalAlignmentType — Top, Center, Bottom) mengontrol cara konten diposisikan dalam PageSize target setelah ApplyChanges() dijalankan. GetPageRotation membaca rotasi saat ini halaman dalam derajat.

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

Mengelola metadata XMP dengan PdfXmpMetadata

PdfXmpMetadata adalah sebuah facade mirip peta di atas paket XMP dokumen. Add(key, value), Remove(key), Contains(key) / ContainsKey(key), dan TryGetValue(key, value) mengelola entri individual; Keys() dan Values() mengenumerasi seluruh paket. RegisterNamespaceURI(prefix, namespaceURI) mendeklarasikan namespace XMP khusus sebelum Anda menambahkan properti di dalamnya. Nama properti yang dikenal luas terdaftar di DefaultMetadataProperties (CreateDate, CreatorTool, Identifier, ModifyDate, Nickname, Thumbnails, dan lainnya), dan PropertyFlag (ReadOnly, Required, NoExport) menggambarkan batasan skema properti yang terdaftar.

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

Tips dan Praktik Terbaik

• Setiap facade mengikuti BindPdf yang sama (atau konstruktor yang menerima nama file) → operasi → urutan Save/Close — mempelajari satu facade langsung dapat diterapkan pada yang berikutnya.
• Lebih pilih metode berawalan Try pada PdfFileEditor dan PdfFileSecurity saat memproses file dari sumber yang tidak terpercaya atau tidak dapat diprediksi — mereka mengembalikan false pada kegagalan alih-alih melempar pengecualian.
• Metode PdfFileEditor menerima jalur file, bukan Document yang terikat — Anda tidak perlu membuka file sumber secara manual sebelum memanggil Concatenate, Extract, atau SplitFromFirst.
• Facade membungkus model objek inti alih-alih menggantikannya: Facade mengekspos Document() yang mendasari untuk kasus di mana metode facade tidak mencakupnya.
• Panggil Close() (atau biarkan facade keluar dari lingkup, bila didukung) setelah Anda selesai dengan dokumen yang terikat untuk melepaskan pegangan file yang mendasari.

Masalah Umum

FAQ

Apa perbedaan antara facade dan Document inti API?

Facade menyediakan antarmuka metode kecil yang berorientasi tugas untuk satu pekerjaan — mengisi formulir, menggabungkan file, menstempel halaman. API inti (Document, Page, Annotation) memberikan akses penuh ke setiap objek PDF. Facade yang mengekspos Document() (melalui kelas dasar Facade) memungkinkan Anda kembali ke model inti untuk hal apa pun yang tidak dicakup oleh metode facade.

Apakah saya perlu memanggil BindPdf sebelum setiap metode facade?

Ya, untuk facade yang mengimplementasikan IFacade — BindPdf (atau overload konstruktor yang setara, seperti pada PdfExtractor(doc)) harus dijalankan sebelum operasi apa pun yang membaca atau memodifikasi dokumen yang terikat.

Apakah operasi PdfFileEditor dapat di-rantai?

Setiap metode PdfFileEditor membaca file inputnya sendiri dan menulis file outputnya sendiri, sehingga Anda dapat merantai operasi dengan memasukkan file output satu metode ke dalam file input panggilan berikutnya — misalnya, Concatenate ke merged.pdf, lalu Extract dari merged.pdf.

Facade mana yang mendukung mode kesalahan non-throwing?

PdfFileEditor (TryConcatenate, TryAppend, TryExtract, TrySplitFromFirst, dan metode Try* terkait) dan PdfFileSecurity (TryEncryptFile, TryDecryptFile, TrySetPrivilege, TryChangePassword) keduanya menawarkan alternatif berawalan Try yang mengembalikan bool alih-alih melempar.

API Reference Ringkasan

Lihat Juga

• Aspose.PDF — Enterprise Documentation