Introdução
Este guia mostra como ler e atualizar o estado ao nível do documento em Aspose.PDF FOSS para C++ — as partes de um PDF que descrevem o próprio documento em vez do que é desenhado em suas páginas. Aspose.PDF FOSS para C++ centra-se na classe Aspose::Pdf::Document, que carrega um PDF existente a partir de um caminho de arquivo e o expõe tanto para edição de conteúdo quanto para a contabilidade ao nível do documento. A contabilidade ao nível do documento abrange o dicionário /Info, o fluxo de metadados XMP, a árvore de marcadores (outline) exibida no painel de navegação de um visualizador, destinos nomeados usados por links internos, anexos de arquivo incorporados no PDF e as sequências personalizadas de numeração de páginas que um documento pode definir.
Este post percorre a superfície API para cada uma dessas áreas: DocumentInfo para os campos clássicos do dicionário /Info (title, author, creator, subject, keywords), Metadata para o fluxo de metadados XMP, Outlines e OutlineItemCollection para a árvore de marcadores, NamedDestinationCollection para links nomeados, EmbeddedFileCollection e FileSpecification para anexos, e PageLabelCollection para numeração de páginas por intervalo. Cada seção combina a classe relevante com um exemplo funcional construído a partir de um objeto Document carregado.
Aspose.PDF FOSS para C++ é distribuído sob a licença MIT e vincula apenas à biblioteca padrão C++, portanto cada operação descrita aqui é executada sem um motor PDF proprietário ou dependência de terceiros. A biblioteca é compilada como um alvo estático (aspose_pdf_foss) adicionado via CMake.
O que está incluído
O dicionário /Info — DocumentInfo
Document.Info() devolve uma referência DocumentInfo vinculada ao dicionário /Info do PDF. Possui acessadores tipados para os campos padrão — Title(), Author(), Creator(), Subject(), Keywords(), Producer() e Trapped() — cada um com um setter correspondente, além de um par genérico Add(key, value) / Remove(key) para chaves personalizadas e IsPredefinedKey(key) para verificar se o nome de uma chave é um dos campos padrão. Document.SetTitle() é um atalho que grava o título diretamente no documento.
#include <aspose/pdf/document.hpp>
#include <aspose/pdf/document_info.hpp>
#include <iostream>
int main() {
Aspose::Pdf::Document doc("input.pdf");
auto& info = doc.Info();
std::cout << "Title: " << info.Title() << "\n";
std::cout << "Author: " << info.Author() << "\n";
info.Author("Demo author");
info.Creator("Aspose.PDF FOSS C++");
info.Add("Generated-By", "document-management sample");
doc.Save("output.pdf");
}
Metadados XMP — Metadata
Além do dicionário /Info, Document.Metadata() devolve um objeto Metadata sobre o fluxo de metadados XMP do documento. Ele se comporta como um contêiner associativo de entradas: Add(key, value), Contains(key), ContainsKey(key), TryGetValue(key, value), Remove(key), Keys(), Values() e Count(). Namespaces personalizados são registrados com RegisterNamespaceUri(prefix, namespaceUri) e resolvidos de ida e volta com GetNamespaceUriByPrefix() e GetPrefixByNamespaceUri().
#include <aspose/pdf/document.hpp>
#include <aspose/pdf/metadata.hpp>
#include <iostream>
int main() {
Aspose::Pdf::Document doc("input.pdf");
auto& metadata = doc.Metadata();
metadata.RegisterNamespaceUri("myapp", "http://example.com/myapp/1.0/");
metadata.Add("myapp:BatchId", "2026-07-run-42");
std::cout << "XMP entries: " << metadata.Count() << "\n";
doc.Save("output.pdf");
}
Marcadores e Contornos
Document.Outlines() retorna a OutlineCollection do documento — a raiz da árvore de marcadores exibida no painel de navegação de um visualizador. A coleção suporta Count(), Add(item), Clear(), Contains(item), Remove(item), Delete(), e os acessores de extremidade First() / Last(), que retornam nós OutlineItemCollection. Cada nó OutlineItemCollection contém um Title(), bandeiras de exibição Bold() / Italic(), um estado de expansão Open(), um Destination() ou Action(), e membros de travessia Next(), Prev(), HasNext(), Level(), e Parent() de volta à coleção Outlines proprietária.
#include <aspose/pdf/document.hpp>
#include <aspose/pdf/outlines.hpp>
#include <iostream>
int main() {
Aspose::Pdf::Document doc("input.pdf");
auto& outlines = doc.Outlines();
std::cout << "Top-level bookmarks: " << outlines.Count() << "\n";
if (outlines.Count() > 0) {
auto& first = outlines.First();
std::cout << "First bookmark: " << first.Title()
<< " (level " << first.Level() << ")\n";
}
}
Destinos Nomeados
Document.NamedDestinations() retorna uma NamedDestinationCollection, uma tabela de consulta que mapeia nomes definidos pela aplicação para destinos dentro do documento. Novas entradas são registradas com Add(name, appointment), onde appointment é uma implementação de IAppointment — a mesma interface usada por destinos de itens de contorno e ações de link. Entradas existentes são removidas com Remove(name), contadas com Count(), e enumeradas com Names().
#include <aspose/pdf/document.hpp>
#include <aspose/pdf/named_destination_collection.hpp>
#include <iostream>
int main() {
Aspose::Pdf::Document doc("input.pdf");
auto& destinations = doc.NamedDestinations();
std::cout << "Named destinations: " << destinations.Count() << "\n";
for (const auto& name : destinations.Names()) {
std::cout << " " << name << "\n";
}
}
Arquivos Incorporados e Anexos
Document.EmbeddedFiles() retorna uma EmbeddedFileCollection de anexos FileSpecification transportados dentro do PDF. Arquivos são adicionados com Add(file) ou Add(key, file), pesquisados por FindByName(name), removidos com Delete(name), DeleteByKey(key) ou Delete(), e enumerados através de Count() e Keys(). Cada FileSpecification informa seu Name(), Description(), MIMEType() e AFRelationship() — a classificação de relacionamento “Associated File” do PDF.
#include <aspose/pdf/document.hpp>
#include <aspose/pdf/file_specification.hpp>
#include <iostream>
int main() {
Aspose::Pdf::Document doc("input.pdf");
auto& files = doc.EmbeddedFiles();
std::cout << "Embedded files: " << files.Count() << "\n";
for (const auto& key : files.Keys()) {
auto spec = files.FindByName(key);
std::cout << " " << spec.Name() << " (" << spec.MIMEType() << ")\n";
}
}
Rótulos de página
Document.PageLabels() retorna uma PageLabelCollection para as sequências de numeração de páginas personalizadas que um visualizador exibe em vez dos números de página físicos — por exemplo, numerais romanos para um prefácio seguidos de numerais arábicos para o corpo. GetLabel(pageIndex) recupera o PageLabel em vigor para uma página; PageLabel expõe StartingValue(), NumberingStyle() (um valor Aspose::Pdf::NumberingStyle como NumeralsArabic ou NumeralsRomanLowercase) e Prefix(). UpdateLabel(pageIndex, pageLabel) atribui um rótulo a partir daquela página, RemoveLabel(pageIndex) remove um, e GetPages() lista cada índice de página que possui um rótulo personalizado.
#include <aspose/pdf/document.hpp>
#include <aspose/pdf/page_label.hpp>
#include <aspose/pdf/page_label_collection.hpp>
#include <iostream>
int main() {
Aspose::Pdf::Document doc("input.pdf");
auto& labels = doc.PageLabels();
for (int pageIndex : labels.GetPages()) {
auto label = labels.GetLabel(pageIndex);
std::cout << "Page " << pageIndex << " prefix: " << label.Prefix()
<< ", starts at " << label.StartingValue() << "\n";
}
auto preface = labels.GetLabel(1);
preface.NumberingStyle(Aspose::Pdf::NumberingStyle::NumeralsRomanLowercase);
preface.StartingValue(1);
labels.UpdateLabel(1, preface);
doc.Save("output.pdf");
}
Início rápido
Adicione a biblioteca como um subdiretório CMake e vincule ao alvo aspose_pdf_foss:
add_subdirectory(aspose.pdf-foss-for-cpp)
target_link_libraries(your_app PRIVATE aspose_pdf_foss)
Abra um documento, leia e atualize seus metadados /Info e salve o resultado:
#include <aspose/pdf/document.hpp>
#include <iostream>
int main() {
Aspose::Pdf::Document doc("input.pdf");
auto& info = doc.Info();
std::cout << "Title: " << info.Title() << "\n";
std::cout << "Author: " << info.Author() << "\n";
doc.SetTitle("Updated Report Title");
info.Author("Report Generator");
info.Add("Generated-By", "Aspose.PDF FOSS for C++");
doc.Save("output.pdf");
return 0;
}
Formatos suportados
| Formato | Extensão | Ler | Escrever |
|---|---|---|---|
| BMP | .bmp | — | ✓ |
| JPEG | .jpg | — | ✓ |
| TIFF | .tiff | — | ✓ |
| Text | .txt | — | ✓ |
| SVG | .svg | ✓ | — |
BMP, JPEG e TIFF são saídas de renderização de página produzidas por suas respectivas classes de dispositivo, e o texto é extraído via TextAbsorber. SVG é importado como conteúdo vetorial através do caminho de carregamento SVG da biblioteca. Nenhum dos tipos de gerenciamento de documentos abordados acima são conversores de formato — eles leem e escrevem apenas a estrutura PDF.
Código aberto e licenciamento
Aspose.PDF FOSS para C++ é distribuído sob a licença MIT, com o código-fonte completo disponível em github.com/aspose-pdf-foss/Aspose.PDF-FOSS-for-Cpp. A licença permite uso comercial, modificação e redistribuição sem um acordo separado.
