Mặt tiền API

Facades API

A facade là một lớp bao bọc đơn giản, hướng nhiệm vụ trên lõi Document / Page / Annotation mô hình đối tượng. Thay vì tự mình duyệt cây trang, bạn gắn một facade vào PDF nguồn, gọi một tập hợp nhỏ các phương thức cấp cao, và lưu kết quả. Mỗi facade trong Aspose::Pdf::Facades thực hiện cùng một hợp đồng tối thiểu được định nghĩa bởi IFacade (BindPdf, Close) và, khi facade tạo ra đầu ra, ISaveableFacade (Save). Các lớp trừu tượng Facade and SaveableFacade các lớp cơ sở cung cấp triển khai mặc định cho bind/close/save mà các trình chỉnh sửa cụ thể bên dưới dựa trên: PdfAnnotationEditor, PdfBookmarkEditor, PdfContentEditor, PdfConverter, PdfExtractor, PdfFileEditor, PdfFileInfo, PdfFileSecurity, PdfFileSignature, PdfFileStamp, PdfPageEditor, PdfXmpMetadata, và tập trung vào biểu mẫu FormEditor / FormFieldFacade cặp.

Các lớp cơ sở Facade và vòng đời bind/save

IFacade khai báo BindPdf(srcFile) (cũng được overload để chấp nhận một Document trong bộ nhớ) và Close(). ISaveableFacade thêm Save(destFile) cho các facade ghi đầu ra. Facade thực thi IFacade và công khai Document() đã được bind để bạn có thể quay lại mô hình đối tượng lõi khi phương thức facade không đáp ứng nhu cầu; SaveableFacade mở rộng Facade với triển khai Save. Mỗi trình chỉnh sửa cụ thể bên dưới kế thừa cấu trúc này, vì vậy mẫu bind → operate → save giống nhau được áp dụng trên toàn bộ Facades API.

Điền và chỉnh sửa các trường AcroForm

FormEditor thêm, xóa, đổi tên và thay đổi vị trí các trường AcroForm trên một tài liệu đã được bind. AddField(fieldType, fieldName, pageNum, llx, lly, urx, ury) tạo một trường mới với FieldType được cung cấp (Text, CheckBox, Radio, ComboBox, ListBox, PushButton, MultiLineText, Barcode, Signature, Image, Numeric, DateTime) tại tọa độ trang đã chỉ định. RemoveField, RenameField, MoveField và SetFieldAttribute quản lý các trường hiện có, và SetFieldScript / AddFieldScript gắn các hành động JavaScript. SubmitFlag (một giá trị SubmitFormFlag — Fdf, Html, Xfdf, FdfWithComments, XfdfWithComments hoặc Pdf) điều khiển cách nút submit gửi dữ liệu biểu mẫu, và SetSubmitUrl đặt điểm cuối mục tiêu.

Hiển thị trực quan mà mỗi trường mới nhận được được điều khiển thông qua FormEditor.Facade(), nó trả về một FormFieldFacade. Thuộc tính Font của nó nhận một giá trị FontStyle (Helvetica, HelveticaBold, Courier, TimesRoman, Symbol, và các biến thể liên quan), TextEncoding nhận một EncodingType (Winansi, Macroman, Identity_h, Identity_v, Cp1250, Cp1252, Cp1257), và BorderStyle / BorderWidth đặt viền cho trường.

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

Quản lý đề mục với PdfBookmarkEditor

PdfBookmarkEditor tạo, trích xuất, sửa đổi và xóa các mục đề mục PDF. CreateBookmarks() ghi một bộ sưu tập Bookmarks (mỗi mục là một Bookmark với Title, PageNumber, Action, Level, Open và ChildItems cho các đề mục lồng nhau) vào tài liệu đã ràng buộc. ExtractBookmarks() đọc lại đề mục hiện có thành một bộ sưu tập Bookmarks, và DeleteBookmarks() — với bộ lọc tùy chọn title — xóa các mục. ExportBookmarksToXML / ImportBookmarksWithXML thực hiện vòng qua một đề mục qua tệp XML, và ExtractBookmarksToHTML / ExportBookmarksToHtml hiển thị đề mục dưới dạng trang HTML.

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

Chỉnh sửa chú thích với PdfAnnotationEditor

PdfAnnotationEditor làm phẳng và nhập chú thích trên toàn bộ tài liệu. FlatteningAnnotations() hợp nhất chú thích vào luồng nội dung trang để chúng hiển thị như nội dung tĩnh thay vì đối tượng tương tác; phiên bản overload nhận một phạm vi trang start/end và một loại chú thích sẽ giới hạn thao tác. ImportAnnotationsFromXfdf / ImportAnnotationsFromFdf đưa chú thích từ các tệp FDF/XFDF bên ngoài vào, và DeleteAnnotations() (hoặc DeleteAnnotations(annotType) cho một loại duy nhất) xóa chúng.

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

Viết lại nội dung trang với PdfContentEditor

PdfContentEditor chỉnh sửa luồng nội dung của một trang đã được tạo sẵn thay vì xây dựng lại trang. ReplaceText(srcText, destText) tìm và thay thế văn bản khớp trên toàn tài liệu, với các overload giới hạn việc thay thế trong một trang duy nhất. ReplaceImage(pageNum, imageNum, fileName) và DeleteImage(pageNum, imageNum) hoán đổi hoặc xóa một XObject hình ảnh hiện có. DeleteStampById / HideStampById / ShowStampById / MoveStampById quản lý các đối tượng tem trên một trang (nội dung nền của tem là Form hoặc Image, theo enum StampType), và AddDocumentAdditionalAction / AddDocumentAttachment đính kèm các hành động JavaScript cấp tài liệu và các tệp đính kèm.

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

Trích xuất văn bản và tệp đính kèm với PdfExtractor

PdfExtractor có thể được ràng buộc hoặc với BindPdf hoặc được tạo trực tiếp từ một Document đã mở sẵn. ExtractText() tiếp theo bởi HasNextPageText() / GetNextPageText(outputFile) duyệt tài liệu từng trang một. Đối với các tệp nhúng, GetAttachNames() liệt kê các tệp đính kèm hiện có và GetAttachment( outputPath) ghi tệp tiếp theo ra đĩa:

#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) trích xuất các hình raster nhúng theo cùng cách mà GetNextPageText duyệt các trang.

Ghép và tách các tệp bằng PdfFileEditor

PdfFileEditor hoạt động trên các đường dẫn tệp thay vì một Document đã ràng buộc, vì vậy mọi phương thức đều nhận tên tệp đầu vào/đầu ra trực tiếp. Concatenate (và phiên bản không ném ngoại lệ TryConcatenate) hợp nhất hai hoặc nhiều tệp; Append chèn một phạm vi trang từ một tệp vào tệp khác; Extract lấy một phạm vi trang hoặc một trang đơn vào một tệp mới; Delete loại bỏ một trang; và SplitFromFirst / SplitToEnd / SplitToPages / SplitToBulks chia tài liệu tại một trang, theo trang, hoặc thành các khối có kích thước cố định. MakeBooklet và MakeNUp sắp xếp lại các trang cho in booklet hoặc N-up, và ResizeContents / AddMargins / AddPageBreak điều chỉnh hình học trang trong toàn bộ tệp. Hầu hết các thao tác có một phiên bản tiền tố Try trả về false thay vì ném ngoại lệ khi thất bại.

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

Kết xuất các trang thành hình ảnh với PdfConverter

PdfConverter kết xuất các trang tài liệu đã ràng buộc thành các định dạng raster. DoConvert() chuẩn bị phạm vi trang (StartPage / EndPage) để lặp; HasNextImage () / GetNextImage(outputFile) sau đó duyệt qua các trang từng cái một. SaveAsTIFF ghi toàn bộ phạm vi vào một tệp TIFF đa trang duy nhất, với các overload cho độ phân giải, nén và TiffSettings. RenderingOptions và Resolution kiểm soát chất lượng rasterization, và ImageMergeMode (Vertical, Horizontal, Center) quyết định cách các hình ảnh trang đã kết xuất nhiều cái được kết hợp khi người gọi hợp nhất chúng thành một hình ảnh.

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

Mã hóa tài liệu bằng PdfFileSecurity

PdfFileSecurity ràng buộc một tệp nguồn và áp dụng hoặc gỡ bỏ mã hóa. EncryptFile(userPassword, ownerPassword, privilege, keySize) mã hóa bằng một DocumentPrivilege (được tạo bằng hàm khởi tạo mặc định và các setter boolean như AllowPrint, AllowCopy, AllowModifyContents) và một KeySize (x40, x128 hoặc x256); overload nhận đối số cipher thứ năm chọn Algorithm (RC4 hoặc AES) một cách rõ ràng. DecryptFile( ownerPassword), ChangePassword, và SetPrivilege bao phủ các trường hợp quản lý mật khẩu còn lại, mỗi trường hợp có một biến thể tiền tố Try không ném ngoại lệ.

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

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

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

Ký và xác thực bằng PdfFileSignature

PdfFileSignature ký, chứng nhận và kiểm tra chữ ký số trên tài liệu đã ràng buộc. Sign(sigName, reason, contact, location, signature) áp dụng chữ ký mới vào trường chữ ký hiện có; Certify áp dụng chữ ký chứng nhận. GetSignatureNames(onlyEmpty) và GetBlankSignatureNames() trả về các trường chữ ký của tài liệu dưới dạng giá trị SignatureName, và VerifySignature(sigName) / IsCoversWholeDocument (sigName) kiểm tra tính hợp lệ và phạm vi. RemoveSignature và RemoveSignatures() loại bỏ các chữ ký hiện có, và SetCertificate(pfxFile, password) cung cấp thông tin xác thực ký trước khi gọi Sign.

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

Ghi dấu tiêu đề, chân trang và số trang bằng PdfFileStamp

PdfFileStamp chồng lên nội dung lặp lại trên mỗi trang của tệp đã ràng buộc. AddPageNumber(format) ghi dấu nhãn số trang bằng cách sử dụng số bắt đầu và tùy chọn tọa độ rõ ràng; AddHeader(text, topMargin) và AddFooter(text, bottomMargin) thêm văn bản tiêu đề/chân trang lặp lại tại lề nhất định, với các phiên bản quá tải cho lề trái/phải. KeepSecurity giữ nguyên bất kỳ mã hóa nào hiện có trên tệp đầu ra, và Close() hoàn thiện và phát hành tài liệu đã ràng buộc.

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

Đọc và ghi thông tin tài liệu bằng PdfFileInfo

PdfFileInfo đọc và ghi lại từ điển /Info cổ điển của PDF và hình học cơ bản theo trang mà không mở toàn bộ mô hình đối tượng. Author, Title, Subject, Keywords, CreationDate và ModDate là các thuộc tính đọc/ghi; Producer và GetPdfVersion() chỉ đọc. GetPageWidth, GetPageHeight và GetPageRotation trả về hình học theo trang dựa trên số trang, và IsEncrypted() / HasOpenPassword() / HasEditPassword() báo cáo trạng thái bảo vệ của tài liệu. SaveNewInfo(outputFile) ghi các thay đổi trở lại.

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

Định vị lại các trang bằng PdfPageEditor

PdfPageEditor di chuyển, thay đổi kích thước và xoay nội dung trang như một khối. MovePosition(offsetX, offsetY) dịch chuyển nội dung trên các trang được chọn bởi ProcessPages; Zoom thu phóng nó. Alignment (một AlignmentType — Left, Center hoặc Right, mỗi cái được lấy từ phương thức tĩnh tương ứng) và VerticalAlignment (một VerticalAlignmentType — Top, Center, Bottom) kiểm soát cách nội dung được đặt trong PageSize mục tiêu khi ApplyChanges() chạy. GetPageRotation đọc góc xoay hiện tại của trang tính tính bằng độ.

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

Quản lý siêu dữ liệu XMP bằng PdfXmpMetadata

PdfXmpMetadata là một facade dạng bản đồ cho gói XMP của tài liệu. Add(key, value), Remove(key), Contains(key) / ContainsKey(key), và TryGetValue(key, value) quản lý các mục riêng lẻ; Keys() và Values() liệt kê toàn bộ gói. RegisterNamespaceURI(prefix, namespaceURI) khai báo một không gian tên XMP tùy chỉnh trước khi bạn thêm các thuộc tính vào đó. Các tên thuộc tính đã được biết rộng rãi được liệt kê trong DefaultMetadataProperties (CreateDate, CreatorTool, Identifier, ModifyDate, Nickname, Thumbnails, và các tên khác), và PropertyFlag (ReadOnly, Required, NoExport) mô tả các ràng buộc lược đồ của một thuộc tính đã đăng ký.

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

Mẹo và Thực hành Tốt nhất

• Mỗi facade tuân theo cùng một BindPdf (hoặc một hàm khởi tạo nhận tên tệp) → thực thi → chuỗi Save/Close — việc học một facade sẽ chuyển trực tiếp sang facade tiếp theo.
• Ưu tiên các phương thức có tiền tố Try trên PdfFileEditor và PdfFileSecurity khi xử lý tệp từ nguồn không tin cậy hoặc không thể dự đoán — chúng sẽ trả về false khi thất bại thay vì ném lỗi.
• Các phương thức PdfFileEditor nhận đường dẫn tệp, không phải một Document đã ràng buộc — bạn không cần mở tệp nguồn thủ công trước khi gọi Concatenate, Extract hoặc SplitFromFirst.
• Các facade bao bọc mô hình đối tượng cốt lõi thay vì thay thế nó: Facade cho phép truy cập Document() nền tảng cho các trường hợp mà phương thức của facade không bao phủ.
• Gọi Close() (hoặc để facade ra khỏi phạm vi, nếu được hỗ trợ) khi bạn đã hoàn thành với một tài liệu đã ràng buộc để giải phóng tay cầm tệp nền tảng.

Vấn đề Thường gặp

FAQ

Sự khác nhau giữa facade và Document API lõi là gì?

Facade cung cấp một bề mặt phương pháp nhỏ, hướng nhiệm vụ cho một công việc — điền mẫu, hợp nhất tệp, dán dấu lên trang. API lõi (Document, Page, Annotation) cung cấp quyền truy cập đầy đủ vào mọi đối tượng PDF. Các facade mà tiết lộ Document() (thông qua lớp cơ sở Facade) cho phép bạn quay lại mô hình lõi cho bất kỳ điều gì mà phương pháp facade không bao phủ.

Tôi có cần gọi BindPdf trước mỗi phương pháp facade không?

Có, đối với các facade thực thi IFacade — BindPdf (hoặc một overload constructor tương đương, như với PdfExtractor(doc)) phải được chạy trước bất kỳ thao tác nào đọc hoặc sửa đổi tài liệu đã liên kết.

Các thao tác PdfFileEditor có thể được nối chuỗi không?

Mỗi phương pháp PdfFileEditor đọc tệp đầu vào riêng của nó và ghi tệp đầu ra riêng, vì vậy bạn nối chuỗi các thao tác bằng cách đưa tệp đầu ra của một phương pháp làm đầu vào cho cuộc gọi tiếp theo — chẳng hạn, Concatenate vào merged.pdf, sau đó Extract từ merged.pdf.

Facade nào hỗ trợ chế độ lỗi không ném?

PdfFileEditor (TryConcatenate, TryAppend, TryExtract, TrySplitFromFirst, và các phương thức Try* liên quan) và PdfFileSecurity (TryEncryptFile, TryDecryptFile, TrySetPrivilege, TryChangePassword) đều cung cấp các tùy chọn có tiền tố Try trả về bool thay vì ném lỗi.

API Reference Tóm tắt

Xem thêm

• Aspose.PDF — Enterprise Documentation