Fachadas API

Fachadas API

A facade es un contenedor simplificado, orientado a tareas, sobre el núcleo Document / Page / Annotation modelo de objetos. En lugar de recorrer tú mismo el árbol de páginas, enlazas una fachada a un PDF de origen, llamas a un pequeño conjunto de métodos de alto nivel y guardas el resultado. Cada fachada en Aspose::Pdf::Facades implementa el mismo contrato mínimo definido por IFacade (BindPdf, Close) y, donde la fachada produce salida, ISaveableFacade (Save). Las clases base abstractas Facade and SaveableFacade clases base proporcionan la implementación predeterminada de bind/close/save que los editores concretos a continuación utilizan: PdfAnnotationEditor, PdfBookmarkEditor, PdfContentEditor, PdfConverter, PdfExtractor, PdfFileEditor, PdfFileInfo, PdfFileSecurity, PdfFileSignature, PdfFileStamp, PdfPageEditor, PdfXmpMetadata, y el centrado en formularios FormEditor / FormFieldFacade par.

Clases base de fachada y el ciclo de vida bind/save

IFacade declara BindPdf(srcFile) (también sobrecargado para aceptar un Document en memoria) y Close(). ISaveableFacade añade Save(destFile) para fachadas que generan salida. Facade implementa IFacade y expone el Document() enlazado para que puedas volver al modelo de objetos central cuando un método de fachada no cubre lo que necesitas; SaveableFacade extiende Facade con la implementación Save. Cada editor concreto a continuación hereda esta forma, por lo que el mismo patrón bind → operate → save se aplica a lo largo de todo Fachadas API.

Rellenado y edición de campos AcroForm

FormEditor agrega, elimina, renombra y reposiciona campos AcroForm en un documento ya enlazado. AddField(fieldType, fieldName, pageNum, llx, lly, urx, ury) crea un nuevo campo del FieldType especificado (Text, CheckBox, Radio, ComboBox, ListBox, PushButton, MultiLineText, Barcode, Signature, Image, Numeric, DateTime) en las coordenadas de página indicadas. RemoveField, RenameField, MoveField y SetFieldAttribute gestionan los campos existentes, y SetFieldScript / AddFieldScript adjuntan acciones JavaScript. SubmitFlag (un valor SubmitFormFlag — Fdf, Html, Xfdf, FdfWithComments, XfdfWithComments o Pdf) controla cómo un botón de envío publica los datos del formulario, y SetSubmitUrl establece el punto final de destino.

La apariencia visual que recibe cada nuevo campo se controla a través de FormEditor.Facade(), que devuelve un FormFieldFacade. Su propiedad Font acepta un valor FontStyle (Helvetica, HelveticaBold, Courier, TimesRoman, Symbol y variantes relacionadas), TextEncoding acepta un EncodingType (Winansi, Macroman, Identity_h, Identity_v, Cp1250, Cp1252, Cp1257), y BorderStyle / BorderWidth establecen el borde del campo.

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

Gestionando marcadores con PdfBookmarkEditor

PdfBookmarkEditor crea, extrae, modifica y elimina entradas del esquema PDF. CreateBookmarks() escribe una colección Bookmarks (cada entrada es un Bookmark con Title, PageNumber, Action, Level, Open y ChildItems para esquemas anidados) en el documento vinculado. ExtractBookmarks() lee el esquema existente y lo devuelve como una colección Bookmarks, y DeleteBookmarks() — con un filtro opcional title — elimina entradas. ExportBookmarksToXML / ImportBookmarksWithXML hacen un viaje de ida y vuelta de un esquema a través de un archivo XML, y ExtractBookmarksToHTML / ExportBookmarksToHtml renderizan el esquema como una página HTML.

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

Editando anotaciones con PdfAnnotationEditor

PdfAnnotationEditor aplana e importa anotaciones en todo el documento. FlatteningAnnotations() fusiona anotaciones en el flujo de contenido de la página para que se rendericen como contenido estático en lugar de objetos interactivos; la sobrecarga que toma un rango de páginas start/end y un tipo de anotación limita la operación. ImportAnnotationsFromXfdf / ImportAnnotationsFromFdf traen anotaciones desde archivos FDF/XFDF externos, y DeleteAnnotations() (o DeleteAnnotations(annotType) para un solo tipo) las elimina.

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

Reescribiendo el contenido de la página con PdfContentEditor

PdfContentEditor edita el flujo de contenido de una página ya generada en lugar de reconstruir la página. ReplaceText(srcText, destText) busca y reemplaza texto coincidente en todo el documento, con sobrecargas que limitan el reemplazo a una sola página. ReplaceImage(pageNum, imageNum, fileName) y DeleteImage(pageNum, imageNum) intercambian o eliminan un XObject de imagen existente. DeleteStampById / HideStampById / ShowStampById / MoveStampById gestionan objetos de sello en una página (el contenido subyacente de un sello es Form o Image, según el enumerado StampType), y AddDocumentAdditionalAction / AddDocumentAttachment adjuntan acciones de nivel de documento JavaScript y archivos adjuntos.

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

Extrayendo texto y adjuntos con PdfExtractor

PdfExtractor puede enlazarse tanto con BindPdf como construirse directamente a partir de un Document ya abierto. ExtractText() seguido de HasNextPageText() / GetNextPageText(outputFile) recorre el documento página por página. Para archivos incrustados, GetAttachNames() enumera los adjuntos presentes y GetAttachment( outputPath) escribe el siguiente en disco:

#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) extrae imágenes raster incrustadas de la misma manera en que GetNextPageText recorre páginas.

Ensamblar y dividir archivos con PdfFileEditor

PdfFileEditor opera sobre rutas de archivo en lugar de un Document vinculado, por lo que cada método recibe directamente los nombres de archivo de entrada/salida. Concatenate (y el TryConcatenate que no lanza excepciones) fusiona dos o más archivos; Append inserta un rango de páginas de un archivo en otro; Extract extrae un rango de páginas o una sola página a un nuevo archivo; Delete elimina una página; y SplitFromFirst / SplitToEnd / SplitToPages / SplitToBulks dividen un documento en una página, página a página, o en fragmentos de tamaño fijo. MakeBooklet y MakeNUp reorganizan páginas para impresión en folleto o N-up, y ResizeContents / AddMargins / AddPageBreak ajustan la geometría de página a lo largo de un archivo. La mayoría de las operaciones tienen una contraparte con prefijo Try que devuelve false en lugar de lanzar una excepción al fallar.

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

Renderizar páginas a imágenes con PdfConverter

PdfConverter renderiza páginas de documentos vinculados a formatos raster. DoConvert() prepara el rango de páginas (StartPage / EndPage) para la iteración; HasNextImage () / GetNextImage(outputFile) luego avanzan por las páginas una a una. SaveAsTIFF escribe todo el rango en un único TIFF multipágina, con sobrecargas para resolución, compresión y TiffSettings. RenderingOptions y Resolution controlan la calidad de rasterización, y ImageMergeMode (Vertical, Horizontal, Center) determina cómo se combinan múltiples imágenes de página renderizadas cuando el llamador las fusiona en una sola imagen.

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

Cifrar documentos con PdfFileSecurity

PdfFileSecurity enlaza un archivo fuente y aplica o elimina el cifrado. EncryptFile(userPassword, ownerPassword, privilege, keySize) cifra con un DocumentPrivilege (creado con el constructor por defecto y setters booleanos como AllowPrint, AllowCopy, AllowModifyContents) y un KeySize (x40, x128 o x256); la sobrecarga que recibe un quinto argumento cipher selecciona explícitamente el Algorithm (RC4 o AES). DecryptFile( ownerPassword), ChangePassword y SetPrivilege cubren los casos restantes de gestión de contraseñas, cada uno con una variante con prefijo Try que no lanza excepciones.

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

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

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

Firmar y verificar con PdfFileSignature

PdfFileSignature firma, certifica e inspecciona firmas digitales en un documento enlazado. Sign(sigName, reason, contact, location, signature) aplica una nueva firma a un campo de firma existente; Certify aplica una firma certificadora. GetSignatureNames(onlyEmpty) y GetBlankSignatureNames() devuelven los campos de firma del documento como valores SignatureName, y VerifySignature(sigName) / IsCoversWholeDocument (sigName) verifican la validez y la cobertura. RemoveSignature y RemoveSignatures() eliminan firmas existentes, y SetCertificate(pfxFile, password) proporciona la credencial de firma antes de llamar a Sign.

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

Estampando encabezados, pies de página y números de página con PdfFileStamp

PdfFileStamp superpone contenido repetido en cada página de un archivo enlazado. AddPageNumber(format) estampa una etiqueta de número de página usando un número inicial y coordenadas explícitas opcionales; AddHeader(text, topMargin) y AddFooter(text, bottomMargin) añaden texto recurrente de encabezado/pie de página en un margen dado, con sobrecargas para márgenes izquierdo/derecho. KeepSecurity conserva cualquier cifrado existente en el archivo de salida, y Close() finaliza y libera el documento enlazado.

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

Leyendo y escribiendo información del documento con PdfFileInfo

PdfFileInfo lee y reescribe el clásico diccionario PDF /Info y la geometría básica por página sin abrir el modelo completo de objetos. Author, Title, Subject, Keywords, CreationDate y ModDate son propiedades de lectura/escritura; Producer y GetPdfVersion() son solo de lectura. GetPageWidth, GetPageHeight y GetPageRotation devuelven la geometría por página según el número de página, y IsEncrypted() / HasOpenPassword() / HasEditPassword() informan del estado de protección del documento. SaveNewInfo(outputFile) escribe los cambios de nuevo.

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

Reposicionando páginas con PdfPageEditor

PdfPageEditor mueve, redimensiona y rota el contenido de la página como un bloque. MovePosition(offsetX, offsetY) desplaza el contenido en las páginas seleccionadas por ProcessPages; Zoom lo escala. Alignment (un AlignmentType — Left, Center o Right, cada uno obtenido del método estático correspondiente) y VerticalAlignment (un VerticalAlignmentType — Top, Center, Bottom) controlan cómo se posiciona el contenido dentro del PageSize objetivo una vez que se ejecuta ApplyChanges(). GetPageRotation lee la rotación actual de una página en grados.

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

Gestionando metadatos XMP con PdfXmpMetadata

PdfXmpMetadata es una fachada similar a un mapa sobre el paquete XMP de un documento. Add(key, value), Remove(key), Contains(key) / ContainsKey(key) y TryGetValue(key, value) gestionan entradas individuales; Keys() y Values() enumeran todo el paquete. RegisterNamespaceURI(prefix, namespaceURI) declara un espacio de nombres XMP personalizado antes de que añadas propiedades en él. Los nombres de propiedades bien conocidos se enumeran en DefaultMetadataProperties (CreateDate, CreatorTool, Identifier, ModifyDate, Nickname, Thumbnails y otros), y PropertyFlag (ReadOnly, Required, NoExport) describe las restricciones de esquema de una propiedad registrada.

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

Consejos y Mejores Prácticas

• Cada fachada sigue el mismo BindPdf (o un constructor que recibe un nombre de archivo) → operar → secuencia Save/Close — aprender una fachada se transfiere directamente a la siguiente.
• Prefiere los métodos con prefijo Try en PdfFileEditor y PdfFileSecurity al procesar archivos de una fuente no fiable o impredecible — devuelven false en caso de error en lugar de lanzar una excepción.
• Los métodos PdfFileEditor aceptan rutas de archivo, no un Document vinculado — no necesitas abrir el archivo fuente tú mismo antes de llamar a Concatenate, Extract o SplitFromFirst.
• Las fachadas envuelven el modelo de objeto central en lugar de reemplazarlo: Facade expone el Document() subyacente para los casos que un método de fachada no cubre.
• Llama a Close() (o deja que la fachada salga del ámbito, donde sea compatible) una vez que hayas terminado con un documento vinculado para liberar el descriptor de archivo subyacente.

Problemas Comunes

FAQ

¿Cuál es la diferencia entre una fachada y el núcleo Document API?

Las fachadas proporcionan una pequeña superficie de métodos orientada a tareas para un trabajo — rellenar un formulario, combinar archivos, estampar páginas. El núcleo API (Document, Page, Annotation) brinda acceso completo a cada objeto PDF. Las fachadas que exponen Document() (a través de la clase base Facade) le permiten volver al modelo central para cualquier cosa que un método de fachada no cubra.

¿Necesito llamar a BindPdf antes de cada método de fachada?

Sí, para las fachadas que implementan IFacade — BindPdf (o una sobrecarga de constructor equivalente, como con PdfExtractor(doc)) debe ejecutarse antes de cualquier operación que lea o modifique el documento enlazado.

¿Pueden encadenarse las operaciones PdfFileEditor?

Cada método PdfFileEditor lee su propio archivo de entrada y escribe su propio archivo de salida, por lo que encadena operaciones alimentando el archivo de salida de un método como archivo de entrada de la siguiente llamada — por ejemplo, Concatenate a merged.pdf, luego Extract desde merged.pdf.

¿Qué fachadas admiten un modo de error sin lanzar excepciones?

PdfFileEditor (TryConcatenate, TryAppend, TryExtract, TrySplitFromFirst, y métodos relacionados Try*) y PdfFileSecurity (TryEncryptFile, TryDecryptFile, TrySetPrivilege, TryChangePassword) ambos ofrecen alternativas con prefijo Try que devuelven bool en lugar de lanzar.

API Reference Resumen

Ver también

• Aspose.PDF — Enterprise Documentation