Fachadas API

Facades API

A facade é um wrapper simplificado, orientado a tarefas, sobre o core Document / Page / Annotation modelo de objetos. Em vez de percorrer a árvore de páginas você mesmo, você vincula uma facade a um PDF de origem, chama um pequeno conjunto de métodos de alto nível e salva o resultado. Cada facade em Aspose::Pdf::Facades implementa o mesmo contrato mínimo definido por IFacade (BindPdf, Close) e, onde a facade produz saída, ISaveableFacade (Save). O abstrato Facade and SaveableFacade as classes base fornecem a implementação padrão de bind/close/save que os editores concretos abaixo utilizam: PdfAnnotationEditor, PdfBookmarkEditor, PdfContentEditor, PdfConverter, PdfExtractor, PdfFileEditor, PdfFileInfo, PdfFileSecurity, PdfFileSignature, PdfFileStamp, PdfPageEditor, PdfXmpMetadata, e o foco no formulário FormEditor / FormFieldFacade par.

Classes base de Facade e o ciclo de vida bind/save

IFacade declara BindPdf(srcFile) (também sobrecarregado para aceitar um Document em memória) e Close(). ISaveableFacade adiciona Save(destFile) para facades que escrevem saída. Facade implementa IFacade e expõe o Document() vinculado para que você possa retornar ao modelo de objetos central quando um método da facade não cobre o que você precisa; SaveableFacade estende Facade com a implementação Save. Cada editor concreto abaixo herda essa estrutura, portanto o mesmo padrão bind → operate → save se aplica a todo o Facades API.

Preenchendo e editando campos AcroForm

FormEditor adiciona, remove, renomeia e reposiciona campos AcroForm em um documento já vinculado. AddField(fieldType, fieldName, pageNum, llx, lly, urx, ury) cria um novo campo do FieldType especificado (Text, CheckBox, Radio, ComboBox, ListBox, PushButton, MultiLineText, Barcode, Signature, Image, Numeric, DateTime) nas coordenadas de página especificadas. RemoveField, RenameField, MoveField e SetFieldAttribute gerenciam campos existentes, e SetFieldScript / AddFieldScript anexam ações JavaScript. SubmitFlag (um valor SubmitFormFlag — Fdf, Html, Xfdf, FdfWithComments, XfdfWithComments ou Pdf) controla como um botão de envio envia os dados do formulário, e SetSubmitUrl define o endpoint de destino.

A aparência visual que cada novo campo recebe é controlada por FormEditor.Facade(), que devolve um FormFieldFacade. Sua propriedade Font aceita um valor FontStyle (Helvetica, HelveticaBold, Courier, TimesRoman, Symbol e variantes relacionadas), TextEncoding aceita um EncodingType (Winansi, Macroman, Identity_h, Identity_v, Cp1250, Cp1252, Cp1257), e BorderStyle / BorderWidth definem a borda do 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();

Gerenciando outlines com PdfBookmarkEditor

PdfBookmarkEditor cria, extrai, modifica e remove entradas de outline de PDF. CreateBookmarks() grava uma coleção Bookmarks (cada entrada um Bookmark com Title, PageNumber, Action, Level, Open e ChildItems para outlines aninhados) no documento vinculado. ExtractBookmarks() lê o outline existente de volta como uma coleção Bookmarks, e DeleteBookmarks() — com um filtro opcional title — remove entradas. ExportBookmarksToXML / ImportBookmarksWithXML fazem round-trip de um outline através de um arquivo XML, e ExtractBookmarksToHTML / ExportBookmarksToHtml renderizam o outline como uma página HTML.

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

Editando anotações com PdfAnnotationEditor

PdfAnnotationEditor achata e importa anotações em todo o documento. FlatteningAnnotations() mescla anotações no fluxo de conteúdo da página para que sejam renderizadas como conteúdo estático em vez de objetos interativos; a sobrecarga que recebe um intervalo de páginas start/end e um tipo de anotação limita a operação. ImportAnnotationsFromXfdf / ImportAnnotationsFromFdf trazem anotações de arquivos FDF/XFDF externos, e DeleteAnnotations() (ou DeleteAnnotations(annotType) para um único tipo) as remove.

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

Reescrevendo conteúdo de página com PdfContentEditor

PdfContentEditor edita o fluxo de conteúdo de uma página já gerada em vez de reconstruir a página. ReplaceText(srcText, destText) encontra e substitui textos correspondentes em todo o documento, com sobrecargas que limitam a substituição a uma única página. ReplaceImage(pageNum, imageNum, fileName) e DeleteImage(pageNum, imageNum) trocam ou removem um XObject de imagem existente. DeleteStampById / HideStampById / ShowStampById / MoveStampById gerenciam objetos de selo em uma página (o conteúdo subjacente de um selo é Form ou Image, conforme o enum StampType), e AddDocumentAdditionalAction / AddDocumentAttachment anexam ações de nível de documento JavaScript e anexos de arquivos.

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

Extraindo texto e anexos com PdfExtractor

PdfExtractor pode ser vinculado tanto com BindPdf quanto construído diretamente a partir de um Document já aberto. ExtractText() seguido por HasNextPageText() / GetNextPageText(outputFile) percorre o documento página por página. Para arquivos incorporados, GetAttachNames() lista os anexos presentes e GetAttachment( outputPath) grava o próximo no 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) extrai imagens raster incorporadas da mesma forma que GetNextPageText percorre páginas.

Montando e dividindo arquivos com PdfFileEditor

PdfFileEditor opera em caminhos de arquivos ao invés de um Document vinculado, portanto cada método recebe nomes de arquivos de entrada/saída diretamente. Concatenate (e o TryConcatenate que não lança exceção) mescla dois ou mais arquivos; Append insere um intervalo de páginas de um arquivo em outro; Extract extrai um intervalo de páginas ou página única para um novo arquivo; Delete remove uma página; e SplitFromFirst / SplitToEnd / SplitToPages / SplitToBulks dividem um documento em uma página, página a página, ou em blocos de tamanho fixo. MakeBooklet e MakeNUp reorganizam páginas para encadernação ou impressão N-up, e ResizeContents / AddMargins / AddPageBreak ajustam a geometria das páginas ao longo de um arquivo. A maioria das operações tem uma variante prefixada com Try que retorna false em vez de lançar exceção em caso de falha.

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

Renderizando páginas em imagens com PdfConverter

PdfConverter renderiza páginas de documentos vinculados para formatos raster. DoConvert() prepara o intervalo de páginas (StartPage / EndPage) para iteração; HasNextImage () / GetNextImage(outputFile) então avançam pelas páginas uma a uma. SaveAsTIFF grava todo o intervalo em um único TIFF multipágina, com sobrecargas para resolução, compressão e TiffSettings. RenderingOptions e Resolution controlam a qualidade da rasterização, e ImageMergeMode (Vertical, Horizontal, Center) determina como múltiplas imagens de páginas renderizadas são combinadas quando o chamador as mescla em uma única imagem.

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

Criptografando documentos com PdfFileSecurity

PdfFileSecurity vincula um arquivo fonte e aplica ou remove criptografia. EncryptFile(userPassword, ownerPassword, privilege, keySize) criptografa com um DocumentPrivilege (construído com o construtor padrão e definidores booleanos como AllowPrint, AllowCopy, AllowModifyContents) e um KeySize (x40, x128 ou x256); a sobrecarga que recebe um quinto argumento cipher seleciona explicitamente o Algorithm (RC4 ou AES). DecryptFile( ownerPassword), ChangePassword e SetPrivilege abrangem os casos restantes de gerenciamento de senhas, cada um com uma variante prefixada com Try que não lança exceção.

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

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

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

Assinando e verificando com PdfFileSignature

PdfFileSignature assina, certifica e inspeciona assinaturas digitais em um documento vinculado. Sign(sigName, reason, contact, location, signature) aplica uma nova assinatura a um campo de assinatura existente; Certify aplica uma assinatura certificadora. GetSignatureNames(onlyEmpty) e GetBlankSignatureNames() retornam os campos de assinatura do documento como valores SignatureName, e VerifySignature(sigName) / IsCoversWholeDocument (sigName) verificam a validade e a cobertura. RemoveSignature e RemoveSignatures() removem assinaturas existentes, e SetCertificate(pfxFile, password) fornece a credencial de assinatura antes de chamar Sign.

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

Aplicando cabeçalhos, rodapés e numeração de páginas com PdfFileStamp

PdfFileStamp sobrepõe conteúdo repetido em cada página de um arquivo vinculado. AddPageNumber(format) carimba um rótulo de número de página usando um número inicial e coordenadas explícitas opcionais; AddHeader(text, topMargin) e AddFooter(text, bottomMargin) adicionam texto de cabeçalho/rodapé recorrente em uma margem especificada, com sobrecargas para margens esquerda/direita. KeepSecurity preserva qualquer criptografia existente no arquivo de saída, e Close() finaliza e libera o documento vinculado.

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

Lendo e gravando informações do documento com PdfFileInfo

PdfFileInfo lê e reescreve o clássico dicionário PDF /Info e a geometria básica por página sem abrir o modelo completo de objetos. Author, Title, Subject, Keywords, CreationDate e ModDate são propriedades de leitura/escrita; Producer e GetPdfVersion() são somente leitura. GetPageWidth, GetPageHeight e GetPageRotation retornam a geometria por página a partir do número da página, e IsEncrypted() / HasOpenPassword() / HasEditPassword() relatam o estado de proteção do documento. SaveNewInfo(outputFile) grava as alterações de volta.

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

Reposicionando páginas com PdfPageEditor

PdfPageEditor move, redimensiona e gira o conteúdo da página como um bloco. MovePosition(offsetX, offsetY) desloca o conteúdo nas páginas selecionadas por ProcessPages; Zoom dimensiona-o. Alignment (um AlignmentType — Left, Center ou Right, cada um obtido do método estático correspondente) e VerticalAlignment (um VerticalAlignmentType — Top, Center ou Bottom) controlam como o conteúdo é posicionado dentro do PageSize alvo quando ApplyChanges() é executado. GetPageRotation lê a rotação atual de uma página em graus.

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

Gerenciando metadados XMP com PdfXmpMetadata

PdfXmpMetadata é uma fachada semelhante a um mapa sobre o pacote XMP de um documento. Add(key, value), Remove(key), Contains(key) / ContainsKey(key) e TryGetValue(key, value) gerenciam entradas individuais; Keys() e Values() enumeram todo o pacote. RegisterNamespaceURI(prefix, namespaceURI) declara um namespace XMP personalizado antes de você adicionar propriedades nele. Nomes de propriedades bem conhecidos estão listados em DefaultMetadataProperties (CreateDate, CreatorTool, Identifier, ModifyDate, Nickname, Thumbnails e outros), e PropertyFlag (ReadOnly, Required, NoExport) descreve as restrições de esquema de uma propriedade registrada.

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

Dicas e Melhores Práticas

• Toda fachada segue o mesmo BindPdf (ou um construtor que aceita nome de arquivo) → operar → sequência Save/Close — aprender uma fachada transfere-se diretamente para a próxima.
• Prefira os métodos com prefixo Try em PdfFileEditor e PdfFileSecurity ao processar arquivos de uma fonte não confiável ou imprevisível — eles retornam false em caso de falha ao invés de lançar exceção.
• Os métodos PdfFileEditor recebem caminhos de arquivo, não um Document vinculado — você não precisa abrir o arquivo de origem manualmente antes de chamar Concatenate, Extract ou SplitFromFirst.
• Fachadas envolvem o modelo de objeto central em vez de substituí-lo: Facade expõe o Document() subjacente para casos que um método da fachada não cobre.
• Chame Close() (ou deixe a fachada sair de escopo, onde for suportado) assim que terminar com um documento vinculado para liberar o identificador de arquivo subjacente.

Problemas Comuns

FAQ

Qual é a diferença entre uma facade e o core Document API?

Facades fornecem uma pequena superfície de métodos orientada a tarefas para um único trabalho — preencher um formulário, mesclar arquivos, carimbar páginas. O core API (Document, Page, Annotation) oferece acesso total a cada objeto PDF. Facades que expõem Document() (por meio da classe base Facade) permitem que você retorne ao modelo core para tudo o que um método de facade não cobre.

Preciso chamar BindPdf antes de cada método de facade?

Sim, para facades que implementam IFacade — BindPdf (ou uma sobrecarga de construtor equivalente, como em PdfExtractor(doc)) deve ser executado antes de qualquer operação que leia ou modifique o documento vinculado.

É possível encadear operações PdfFileEditor?

Cada método PdfFileEditor lê seu próprio arquivo de entrada e grava seu próprio arquivo de saída, portanto você encadeia operações alimentando o arquivo de saída de um método como arquivo de entrada da chamada seguinte — por exemplo, Concatenate em merged.pdf, então Extract a partir de merged.pdf.

Quais facades suportam um modo de erro que não lança exceções?

PdfFileEditor (TryConcatenate, TryAppend, TryExtract, TrySplitFromFirst, e métodos Try* relacionados) e PdfFileSecurity (TryEncryptFile, TryDecryptFile, TrySetPrivilege, TryChangePassword) ambos oferecem alternativas prefixadas com Try que retornam bool em vez de lançar.

API Reference Resumo

Ver também

• Aspose.PDF — Enterprise Documentation