Facades API

Facades API

A facade เป็นตัวห่อที่เรียบง่ายและมุ่งเน้นงานเหนือแกนหลัก Document / Page / Annotation โมเดลวัตถุ. แทนที่จะเดินสำรวจโครงสร้างหน้าเอง คุณผูก façade กับ PDF แหล่งต้นทาง, เรียกชุดเมธอดระดับสูงจำนวนเล็กน้อย, และบันทึกผลลัพธ์. ทุก façade ใน Aspose::Pdf::Facades ทำตามสัญญาขั้นต่ำเดียวกันที่กำหนดโดย IFacade (BindPdf, Close) และ, เมื่อ façade ผลิตผลลัพธ์, ISaveableFacade (Save). คลาสนามธรรม Facade and SaveableFacade คลาสฐานให้การดำเนินการ bind/close/save เริ่มต้นที่ตัวแก้ไขเชิงรูปธรรมด้านล่างอิงอยู่: PdfAnnotationEditor, PdfBookmarkEditor, PdfContentEditor, PdfConverter, PdfExtractor, PdfFileEditor, PdfFileInfo, PdfFileSecurity, PdfFileSignature, PdfFileStamp, PdfPageEditor, PdfXmpMetadata, และที่เน้นแบบฟอร์ม FormEditor / FormFieldFacade คู่.

คลาสฐานของ Facade และวงจรชีวิต bind/save

IFacade ประกาศ BindPdf(srcFile) (ยังมีการ overload เพื่อรับ Document ที่อยู่ในหน่วยความจำ) และ Close(). ISaveableFacade เพิ่ม Save(destFile) สำหรับ facade ที่เขียนผลลัพธ์. Facade implements IFacade และเปิดเผย Document() ที่ถูก bind ไว้เพื่อให้คุณสามารถย้อนกลับไปยังโมเดลวัตถุหลักเมื่อเมธอดของ facade ไม่ครอบคลุมความต้องการของคุณ; SaveableFacade extends Facade ด้วยการนำ Save ไปใช้. ตัวแก้ไขคอนกรีตทั้งหมดด้านล่างสืบทอดรูปแบบนี้ ดังนั้นรูปแบบ bind → operate → save เดียวกันจึงใช้ได้ทั่วทั้ง Facades API.

การเติมและแก้ไข AcroForm fields

FormEditor เพิ่ม, ลบ, เปลี่ยนชื่อ, และย้ายตำแหน่งฟิลด์ AcroForm ในเอกสารที่ผูกไว้แล้ว. AddField(fieldType, fieldName, pageNum, llx, lly, urx, ury) สร้างฟิลด์ใหม่ตาม FieldType ที่ระบุ (Text, CheckBox, Radio, ComboBox, ListBox, PushButton, MultiLineText, Barcode, Signature, Image, Numeric, DateTime) ที่พิกัดหน้าที่กำหนด. RemoveField, RenameField, MoveField, และ SetFieldAttribute จัดการฟิลด์ที่มีอยู่, และ SetFieldScript / AddFieldScript แนบการกระทำ JavaScript. SubmitFlag (ค่าประเภท SubmitFormFlag — Fdf, Html, Xfdf, FdfWithComments, XfdfWithComments, หรือ Pdf) ควบคุมว่าปุ่มส่งข้อมูลจะโพสต์ข้อมูลฟอร์มอย่างไร, และ SetSubmitUrl กำหนดปลายทาง.

รูปลักษณ์ภาพที่แต่ละฟิลด์ใหม่ได้รับจะถูกควบคุมผ่าน FormEditor.Facade(), ซึ่งจะคืนค่า FormFieldFacade. คุณสมบัติ Font ของมันรับค่าประเภท FontStyle (Helvetica, HelveticaBold, Courier, TimesRoman, Symbol, และรูปแบบที่เกี่ยวข้อง), TextEncoding รับค่า EncodingType (Winansi, Macroman, Identity_h, Identity_v, Cp1250, Cp1252, Cp1257), และ BorderStyle / BorderWidth ตั้งค่าขอบของฟิลด์.

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

การจัดการโครงร่างด้วย PdfBookmarkEditor

PdfBookmarkEditor สร้าง, ดึงออก, แก้ไข, และลบรายการโครงร่าง PDF. CreateBookmarks() เขียนคอลเลกชัน Bookmarks (แต่ละรายการเป็น Bookmark ที่มี Title, PageNumber, Action, Level, Open, และ ChildItems สำหรับโครงร่างที่ซ้อนกัน) ลงในเอกสารที่ผูกไว้. ExtractBookmarks() อ่านโครงร่างที่มีอยู่กลับออกเป็นคอลเลกชัน Bookmarks, และ DeleteBookmarks() — พร้อมกับตัวกรอง title ทางเลือก — ลบรายการ. ExportBookmarksToXML / ImportBookmarksWithXML ทำการ round-trip โครงร่างผ่านไฟล์ XML, และ ExtractBookmarksToHTML / ExportBookmarksToHtml แสดงโครงร่างเป็นหน้า HTML.

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

การแก้ไขหมายเหตุด้วย PdfAnnotationEditor

PdfAnnotationEditor ทำให้หมายเหตุแบนและนำเข้าทั่วทั้งเอกสาร. FlatteningAnnotations() ผสานหมายเหตุเข้ากับสตรีมเนื้อหาหน้ากระดาษเพื่อให้แสดงเป็นเนื้อหาคงที่แทนวัตถุแบบโต้ตอบ; การ overload ที่รับช่วงหน้ากระดาษ start/end และประเภทหมายเหตุจะจำกัดการทำงาน. ImportAnnotationsFromXfdf / ImportAnnotationsFromFdf นำหมายเหตุเข้าจากไฟล์ FDF/XFDF ภายนอก, และ DeleteAnnotations() (หรือ DeleteAnnotations(annotType) สำหรับประเภทเดียว) จะลบมันออก.

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

การเขียนใหม่เนื้อหาหน้ากระดาษด้วย PdfContentEditor

PdfContentEditor แก้ไขสตรีมเนื้อหาของหน้าที่สร้างเสร็จแล้วแทนการสร้างหน้าขึ้นใหม่. ReplaceText(srcText, destText) ค้นหาและแทนที่ข้อความที่ตรงกันทั่วทั้งเอกสาร, พร้อม overload ที่จำกัดการแทนที่ให้เฉพาะหน้าหนึ่ง. ReplaceImage(pageNum, imageNum, fileName) และ DeleteImage(pageNum, imageNum) สลับหรือลบ XObject รูปภาพที่มีอยู่. DeleteStampById / HideStampById / ShowStampById / MoveStampById จัดการอ็อบเจ็กต์สแตมป์บนหน้า (เนื้อหาพื้นฐานของสแตมป์เป็น Form หรือ Image ตาม enum StampType), และ AddDocumentAdditionalAction / AddDocumentAttachment แนบการกระทำระดับเอกสาร JavaScript และไฟล์แนบ.

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

การดึงข้อความและไฟล์แนบด้วย PdfExtractor

PdfExtractor สามารถผูกได้ทั้งด้วย BindPdf หรือสร้างตรงจาก Document ที่เปิดอยู่แล้ว. ExtractText() ตามด้วย HasNextPageText() / GetNextPageText(outputFile) จะเดินเอกสารหน้าโดยหน้า. สำหรับไฟล์ที่ฝังอยู่, GetAttachNames() แสดงรายการไฟล์แนบที่มีอยู่และ GetAttachment( outputPath) เขียนไฟล์ต่อไปลงดิสก์:

#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) ดึงภาพเรสเตอร์ที่ฝังอยู่ในแบบเดียวกับที่ GetNextPageText เดินหน้าในแต่ละหน้า.

การประกอบและแยกไฟล์ด้วย PdfFileEditor

PdfFileEditor ทำงานกับเส้นทางไฟล์แทนที่จะเป็น Document ที่ผูกไว้, ดังนั้นทุกเมธอดจะรับชื่อไฟล์อินพุต/เอาต์พุตโดยตรง. Concatenate (และเวอร์ชันที่ไม่โยนข้อยกเว้น TryConcatenate) รวมไฟล์สองไฟล์หรือมากกว่า; Append แทรกช่วงหน้าจากไฟล์หนึ่งไปยังอีกไฟล์หนึ่ง; Extract ดึงช่วงหน้า หรือหน้าเดียว ไปยังไฟล์ใหม่; Delete ลบหน้า; และ SplitFromFirst / SplitToEnd / SplitToPages / SplitToBulks แบ่งเอกสารตามหน้า, หน้าโดยหน้า, หรือเป็นชิ้นส่วนขนาดคงที่. MakeBooklet และ MakeNUp จัดเรียงหน้าสำหรับการพิมพ์แบบบุกเก็ตหรือ N-up, และ ResizeContents / AddMargins / AddPageBreak ปรับเรขาคณิตของหน้าในไฟล์. การดำเนินการส่วนใหญ่มีเวอร์ชันที่ขึ้นต้นด้วย Try ซึ่งจะคืนค่า false แทนการโยนข้อผิดพลาด.

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

การเรนเดอร์หน้าต่อภาพด้วย PdfConverter

PdfConverter เรนเดอร์หน้าของเอกสารที่ผูกไว้เป็นรูปแบบเรสเตอร์. DoConvert() เตรียมช่วงหน้า (StartPage / EndPage) เพื่อการวนซ้ำ; HasNextImage () / GetNextImage(outputFile) จากนั้นเดินหน้าแต่ละหน้าอย่างต่อเนื่อง. SaveAsTIFF เขียนช่วงทั้งหมดลงในไฟล์ TIFF หน้าหลายหน้าเดียว, พร้อมโอเวอร์โหลดสำหรับความละเอียด, การบีบอัด, และ TiffSettings. RenderingOptions และ Resolution ควบคุมคุณภาพการเรสเตอร์ไลเซชัน, และ ImageMergeMode (Vertical, Horizontal, Center) กำหนดวิธีที่ภาพหน้าที่เรนเดอร์หลายหน้าเชื่อมต่อกันเมื่อผู้เรียกรวมเป็นภาพเดียว.

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

การเข้ารหัสเอกสารด้วย PdfFileSecurity

PdfFileSecurity ผูกไฟล์ต้นทางและทำการประยุกต์หรือถอดการเข้ารหัส. EncryptFile(userPassword, ownerPassword, privilege, keySize) เข้ารหัสด้วย DocumentPrivilege (สร้างด้วยคอนสตรัคเตอร์เริ่มต้นและตัวตั้งค่าแบบบูลีน เช่น AllowPrint, AllowCopy, AllowModifyContents) และ KeySize (x40, x128, หรือ x256); การโอเวอร์โหลดที่รับอาร์กิวเมนต์ cipher ที่ห้าเลือก Algorithm (RC4 หรือ AES) อย่างชัดเจน. DecryptFile( ownerPassword), ChangePassword, และ SetPrivilege ครอบคลุมกรณีการจัดการรหัสผ่านที่เหลือ, แต่ละกรณีมีเวอร์ชันที่ขึ้นต้นด้วย Try ซึ่งไม่โยนข้อยกเว้น.

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

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

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

การลงนามและการตรวจสอบด้วย PdfFileSignature

PdfFileSignature ทำการเซ็น, รับรอง, และตรวจสอบลายเซ็นดิจิทัลบนเอกสารที่ผูกไว้. Sign(sigName, reason, contact, location, signature) ใส่ลายเซ็นใหม่ลงในฟิลด์ลายเซ็นที่มีอยู่; Certify ใส่ลายเซ็นรับรอง. GetSignatureNames(onlyEmpty) และ GetBlankSignatureNames() คืนค่าฟิลด์ลายเซ็นของเอกสารเป็นค่า SignatureName, และ VerifySignature(sigName) / IsCoversWholeDocument (sigName) ตรวจสอบความถูกต้องและการครอบคลุม. RemoveSignature และ RemoveSignatures() ลบลายเซ็นที่มีอยู่, และ SetCertificate(pfxFile, password) จัดหาข้อมูลประจำตัวการเซ็นก่อนเรียก Sign.

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

การตราประทับหัวกระดาษ, ส่วนท้าย, และหมายเลขหน้าโดยใช้ PdfFileStamp

PdfFileStamp วางเนื้อหาที่ซ้ำกันบนทุกหน้าของไฟล์ที่ผูกไว้. AddPageNumber(format) ตราประทับป้ายหมายเลขหน้าโดยใช้หมายเลขเริ่มต้นและพิกัดที่ระบุเพิ่มเติมตามต้องการ; AddHeader(text, topMargin) และ AddFooter(text, bottomMargin) เพิ่มข้อความหัวกระดาษ/ส่วนท้ายที่เกิดซ้ำตามขอบที่กำหนด, พร้อมโอเวอร์โหลดสำหรับขอบซ้าย/ขวา. KeepSecurity รักษาการเข้ารหัสที่มีอยู่บนไฟล์ผลลัพธ์, และ Close() สรุปและปล่อยเอกสารที่ผูกไว้.

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

การอ่านและเขียนข้อมูลเอกสารด้วย PdfFileInfo

PdfFileInfo อ่านและเขียนพจนานุกรม /Info ของ PDF แบบคลาสสิกและเรขาคณิตพื้นฐานต่อหน้าโดยไม่ต้องเปิดโมเดลอ็อบเจกต์เต็ม. Author, Title, Subject, Keywords, CreationDate, และ ModDate เป็นคุณสมบัติอ่าน/เขียน; Producer และ GetPdfVersion() เป็นแบบอ่านอย่างเดียว. GetPageWidth, GetPageHeight, และ GetPageRotation คืนค่าเรขาคณิตต่อหน้าตามหมายเลขหน้า, และ IsEncrypted() / HasOpenPassword() / HasEditPassword() รายงานสถานะการป้องกันของเอกสาร. SaveNewInfo(outputFile) เขียนการเปลี่ยนแปลงกลับออกไป.

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

การจัดตำแหน่งหน้าใหม่ด้วย PdfPageEditor

PdfPageEditor ย้าย, ปรับขนาด, และหมุนเนื้อหาหน้าเป็นบล็อก. MovePosition(offsetX, offsetY) เลื่อนเนื้อหาบนหน้าที่เลือกโดย ProcessPages; Zoom ปรับสเกล. Alignment (เป็น AlignmentType — Left, Center, หรือ Right, แต่ละอย่างได้มาจากเมธอดสเตติกที่ตรงกัน) และ VerticalAlignment (เป็น VerticalAlignmentType — Top, Center, Bottom) ควบคุมวิธีการวางตำแหน่งเนื้อหาภายใน PageSize เป้าหมายเมื่อ ApplyChanges() ทำงาน. GetPageRotation อ่านการหมุนปัจจุบันของหน้าหนึ่งเป็นองศา.

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

การจัดการเมตาดาต้า XMP ด้วย PdfXmpMetadata

PdfXmpMetadata เป็น facade แบบแผนที่เหนือแพ็กเกจ XMP ของเอกสาร. Add(key, value), Remove(key), Contains(key) / ContainsKey(key), และ TryGetValue(key, value) จัดการรายการแต่ละรายการ; Keys() และ Values() แสดงรายการทั้งหมดของแพ็กเกจ. RegisterNamespaceURI(prefix, namespaceURI) ประกาศ namespace XMP ที่กำหนดเองก่อนที่คุณจะเพิ่มคุณสมบัติในนั้น. ชื่อคุณสมบัติที่เป็นที่รู้จักกันดีได้ถูกรายการใน DefaultMetadataProperties (CreateDate, CreatorTool, Identifier, ModifyDate, Nickname, Thumbnails, และอื่น ๆ), และ PropertyFlag (ReadOnly, Required, NoExport) อธิบายข้อจำกัดของสคีมาที่ลงทะเบียนสำหรับคุณสมบัตินั้น.

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

เคล็ดลับและแนวทางปฏิบัติที่ดีที่สุด

• แต่ละ facade ปฏิบัติตาม BindPdf เดียวกัน (หรือคอนสตรัคเตอร์ที่รับชื่อไฟล์) → ทำงาน → ลำดับ Save/Close — การเรียนรู้ facade หนึ่งจะถ่ายทอดโดยตรงไปยัง facade ถัดไป.
• ควรใช้เมธอดที่มีคำนำหน้า Try บน PdfFileEditor และ PdfFileSecurity เมื่อประมวลผลไฟล์จากแหล่งที่ไม่เชื่อถือหรือไม่สามารถคาดเดาได้ — พวกมันจะคืนค่า false เมื่อเกิดความล้มเหลวแทนการโยนข้อยกเว้น.
• เมธอด PdfFileEditor รับเส้นทางไฟล์ ไม่ใช่ Document ที่ผูกไว้ — คุณไม่จำเป็นต้องเปิดไฟล์ต้นทางด้วยตนเองก่อนเรียก Concatenate, Extract, หรือ SplitFromFirst.
• Facades ห่อหุ้มโมเดลอ็อบเจกต์หลักแทนที่จะทดแทนมัน: Facade เปิดเผย Document() ด้านล่างสำหรับกรณีที่เมธอดของ facade ไม่ครอบคลุม.
• เรียก Close() (หรือให้ facade ออกจากขอบเขตเมื่อรองรับ) เมื่อคุณทำงานกับเอกสารที่ผูกแล้วเสร็จ เพื่อปล่อยตัวจัดการไฟล์พื้นฐาน.

ปัญหาที่พบบ่อย

FAQ

ความแตกต่างระหว่าง facade กับ Document API แกนคืออะไร?

Facade ให้พื้นผิวเมธอดขนาดเล็กที่มุ่งเน้นงานเฉพาะสำหรับงานหนึ่ง — การกรอกแบบฟอร์ม, การรวมไฟล์, การประทับหน้ากระดาษ. API แกน (Document, Page, Annotation) ให้การเข้าถึงเต็มรูปแบบทุกอ็อบเจกต์ PDF. Facade ที่เปิดเผย Document() (ผ่านคลาสฐาน Facade) ให้คุณย้อนกลับไปยังโมเดลแกนสำหรับสิ่งที่เมธอดของ facade ไม่ครอบคลุม.

ฉันต้องเรียก BindPdf ก่อนทุกเมธอดของ facade หรือไม่?

ใช่, สำหรับ facade ที่ทำงาน IFacade — BindPdf (หรือ overload ของคอนสตรัคเตอร์ที่เทียบเท่า, เช่นกับ PdfExtractor(doc)) ต้องทำงานก่อนการดำเนินการใด ๆ ที่อ่านหรือแก้ไขเอกสารที่ผูกไว้.

สามารถเชื่อมต่อการดำเนินการ PdfFileEditor กันได้หรือไม่?

แต่ละเมธอด PdfFileEditor จะอ่านไฟล์อินพุตของตนเองและเขียนไฟล์เอาต์พุตของตนเอง, ดังนั้นคุณจึงเชื่อมต่อการดำเนินการโดยนำไฟล์เอาต์พุตของเมธอดหนึ่งเป็นไฟล์อินพุตของเมธอดถัดไป — ตัวอย่างเช่น, Concatenate ไปยัง merged.pdf, แล้ว Extract จาก merged.pdf.

Facade ใดบ้างที่รองรับโหมดข้อผิดพลาดแบบไม่โยนข้อยกเว้น?

PdfFileEditor (TryConcatenate, TryAppend, TryExtract, TrySplitFromFirst และวิธี Try* ที่เกี่ยวข้อง) และ PdfFileSecurity (TryEncryptFile, TryDecryptFile, TrySetPrivilege, TryChangePassword) ทั้งสองให้ตัวเลือกที่มีคำนำหน้า Try ซึ่งคืนค่า bool แทนการโยน.

API Reference สรุป

ดูเพิ่มเติม

• Aspose.PDF — Enterprise Documentation