Introduzione
Questa guida mostra come leggere e aggiornare lo stato a livello di documento in Aspose.PDF FOSS per C++ — le parti di un PDF che descrivono il documento stesso piuttosto che ciò che è disegnato nelle sue pagine. Aspose.PDF FOSS per C++ si concentra sulla classe Aspose::Pdf::Document, che carica un PDF esistente da un percorso file e lo espone sia per la modifica del contenuto sia per la gestione a livello di documento. La gestione a livello di documento copre il dizionario /Info, lo stream di metadati XMP, l’albero dei segnalibri (outline) mostrato nel pannello di navigazione di un visualizzatore, le destinazioni nominate usate dai collegamenti interni, gli allegati di file incorporati nel PDF e le sequenze di numerazione delle pagine personalizzate che un documento può definire.
Questo post esamina la superficie API per ciascuna di queste aree: DocumentInfo per i campi classici del dizionario /Info (title, author, creator, subject, keywords), Metadata per lo stream di metadati XMP, Outlines e OutlineItemCollection per l’albero dei segnalibri, NamedDestinationCollection per i collegamenti nominati, EmbeddedFileCollection e FileSpecification per gli allegati, e PageLabelCollection per la numerazione delle pagine per intervallo. Ogni sezione associa la classe pertinente a un esempio funzionante costruito a partire da un oggetto Document caricato.
Aspose.PDF FOSS per C++ è rilasciato sotto licenza MIT e si collega solo alla libreria standard C++, quindi ogni operazione descritta qui viene eseguita senza un motore PDF proprietario o dipendenze di terze parti. La libreria viene compilata come target statico (aspose_pdf_foss) aggiunto tramite CMake.
Cosa è incluso
Il dizionario /Info — DocumentInfo
Document.Info() restituisce un riferimento DocumentInfo collegato al dizionario /Info del PDF. Dispone di accessor tipizzati per i campi standard — Title(), Author(), Creator(), Subject(), Keywords(), Producer() e Trapped() — ognuno con il relativo setter, oltre a una coppia generica Add(key, value) / Remove(key) per chiavi personalizzate e IsPredefinedKey(key) per verificare se il nome di una chiave è uno dei campi standard. Document.SetTitle() è una scorciatoia che scrive il titolo direttamente sul 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");
}
Metadati XMP — Metadata
Oltre al dizionario /Info, Document.Metadata() restituisce un oggetto Metadata sul flusso di metadati XMP del documento. Si comporta come un contenitore associativo di voci: Add(key, value), Contains(key), ContainsKey(key), TryGetValue(key, value), Remove(key), Keys(), Values() e Count(). I namespace personalizzati vengono registrati con RegisterNamespaceUri(prefix, namespaceUri) e risolti avanti e indietro con 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");
}
Segnalibri e Contorni
Document.Outlines() restituisce la OutlineCollection del documento — la radice dell’albero dei segnalibri mostrato nel pannello di navigazione di un visualizzatore. La collezione supporta Count(), Add(item), Clear(), Contains(item), Remove(item), Delete(), e gli accessor finali First() / Last(), che restituiscono nodi OutlineItemCollection. Ogni nodo OutlineItemCollection contiene un Title(), flag di visualizzazione Bold() / Italic(), uno stato di espansione Open(), un Destination() o Action(), e membri di attraversamento Next(), Prev(), HasNext(), Level(), e Parent() che riportano alla collezione Outlines proprietaria.
#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";
}
}
Destinazioni Nominative
Document.NamedDestinations() restituisce una NamedDestinationCollection, una tabella di ricerca che mappa nomi definiti dall’applicazione a destinazioni all’interno del documento. Nuove voci vengono registrate con Add(name, appointment), dove appointment è un’implementazione di IAppointment — la stessa interfaccia usata dalle destinazioni degli outline-item e dalle azioni dei collegamenti. Le voci esistenti vengono rimosse con Remove(name), contate con Count() e enumerate con 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";
}
}
File Incorporati e Allegati
Document.EmbeddedFiles() restituisce una EmbeddedFileCollection di allegati FileSpecification contenuti nel PDF. I file vengono aggiunti con Add(file) o Add(key, file), cercati tramite FindByName(name), rimossi con Delete(name), DeleteByKey(key) o Delete(), e enumerati tramite Count() e Keys(). Ogni FileSpecification espone i metodi Name(), Description(), MIMEType() e AFRelationship() — la classificazione di relazione “Associated File” del 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";
}
}
Etichette di pagina
Document.PageLabels() restituisce una PageLabelCollection per le sequenze di numerazione di pagina personalizzate che un visualizzatore mostra al posto dei numeri di pagina fisici — ad esempio, numeri romani per una prefazione seguiti da numeri arabi per il corpo del testo. GetLabel(pageIndex) recupera la PageLabel in vigore per una pagina; PageLabel espone StartingValue(), NumberingStyle() (un valore Aspose::Pdf::NumberingStyle come NumeralsArabic o NumeralsRomanLowercase), e Prefix(). UpdateLabel(pageIndex, pageLabel) assegna un’etichetta a partire da quella pagina, RemoveLabel(pageIndex) la elimina, e GetPages() elenca tutti gli indici di pagina che possiedono un’etichetta personalizzata.
#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");
}
Avvio rapido
Aggiungi la libreria come sotto-directory CMake e collegala al target aspose_pdf_foss:
add_subdirectory(aspose.pdf-foss-for-cpp)
target_link_libraries(your_app PRIVATE aspose_pdf_foss)
Apri un documento, leggi e aggiorna i metadati /Info, quindi salva il risultato:
#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;
}
Formati supportati
| Formato | Estensione | Leggi | Scrivi |
|---|---|---|---|
| BMP | .bmp | — | ✓ |
| JPEG | .jpg | — | ✓ |
| TIFF | .tiff | — | ✓ |
| Text | .txt | — | ✓ |
| SVG | .svg | ✓ | — |
BMP, JPEG e TIFF sono output di rendering di pagina prodotti dalle rispettive classi di dispositivo, e il testo viene estratto tramite TextAbsorber. SVG viene importato come contenuto vettoriale tramite il percorso di caricamento SVG della libreria. Nessuno dei tipi di gestione documentale descritti sopra è un convertitore di formati — leggono e scrivono solo la struttura PDF.
Open Source & Licenze
Aspose.PDF FOSS per C++ è distribuito sotto licenza MIT, con il codice sorgente completo disponibile su github.com/aspose-pdf-foss/Aspose.PDF-FOSS-for-Cpp. La licenza consente l’uso commerciale, la modifica e la ridistribuzione senza un accordo separato.
