Introducción

Esta guía muestra cómo leer y actualizar el estado a nivel de documento en Aspose.PDF FOSS para C++ — las partes de un PDF que describen el propio documento en lugar de lo que se dibuja en sus páginas. Aspose.PDF FOSS para C++ se centra en la clase Aspose::Pdf::Document, que carga un PDF existente desde una ruta de archivo y lo expone tanto para la edición de contenido como para la contabilidad a nivel de documento. La contabilidad a nivel de documento cubre el diccionario /Info, el flujo de metadatos XMP, el árbol de marcadores (esquema) que se muestra en el panel de navegación de un visor, los destinos nombrados utilizados por enlaces internos, los archivos adjuntos incrustados en el PDF y las secuencias personalizadas de numeración de páginas que un documento puede definir.

Esta publicación recorre la superficie API para cada una de estas áreas: DocumentInfo para los campos clásicos del diccionario /Info (title, author, creator, subject, keywords), Metadata para el flujo de metadatos XMP, Outlines y OutlineItemCollection para el árbol de marcadores, NamedDestinationCollection para enlaces nombrados, EmbeddedFileCollection y FileSpecification para los archivos adjuntos, y PageLabelCollection para la numeración de páginas por rangos. Cada sección empareja la clase correspondiente con un ejemplo funcional construido a partir de un objeto Document cargado.

Aspose.PDF FOSS para C++ se publica bajo la licencia MIT y se enlaza únicamente con la biblioteca estándar de C++, de modo que cada operación descrita aquí se ejecuta sin un motor PDF propietario ni dependencias de terceros. La biblioteca se compila como un objetivo estático (aspose_pdf_foss) añadido mediante CMake.

Qué incluye

El diccionario /Info — DocumentInfo

Document.Info() devuelve una referencia DocumentInfo vinculada al diccionario /Info del PDF. Tiene accesores tipados para los campos estándar — Title(), Author(), Creator(), Subject(), Keywords(), Producer() y Trapped() — cada uno con su setter correspondiente, además de un par genérico Add(key, value) / Remove(key) para claves personalizadas y IsPredefinedKey(key) para comprobar si el nombre de una clave es uno de los campos estándar. Document.SetTitle() es un atajo que escribe el título directamente en el 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");
}

Metadatos XMP — Metadata

Más allá del diccionario /Info, Document.Metadata() devuelve un objeto Metadata sobre el flujo de metadatos XMP del documento. Se comporta como un contenedor asociativo de entradas: Add(key, value), Contains(key), ContainsKey(key), TryGetValue(key, value), Remove(key), Keys(), Values() y Count(). Los espacios de nombres personalizados se registran con RegisterNamespaceUri(prefix, namespaceUri) y se resuelven de ida y vuelta con GetNamespaceUriByPrefix() y 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 y Contornos

Document.Outlines() devuelve la OutlineCollection del documento — la raíz del árbol de marcadores que se muestra en el panel de navegación de un visor. La colección admite Count(), Add(item), Clear(), Contains(item), Remove(item), Delete(), y los accesores finales First() / Last(), que retornan nodos OutlineItemCollection. Cada nodo OutlineItemCollection contiene un Title(), banderas de visualización Bold() / Italic(), un estado de expansión Open(), un Destination() o Action(), y miembros de recorrido Next(), Prev(), HasNext(), Level(), y Parent() que vuelve a la colección propietaria Outlines.

#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 nombrados

Document.NamedDestinations() devuelve una NamedDestinationCollection, una tabla de búsqueda que asigna nombres definidos por la aplicación a destinos dentro del documento. Las nuevas entradas se registran con Add(name, appointment), donde appointment es una implementación de IAppointment — la misma interfaz utilizada por los destinos de elementos de esquema y las acciones de enlaces. Las entradas existentes se eliminan con Remove(name), se cuentan con Count() y se enumeran 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";
    }
}

Archivos incrustados y adjuntos

Document.EmbeddedFiles() devuelve una EmbeddedFileCollection de adjuntos FileSpecification que se llevan dentro del PDF. Los archivos se añaden con Add(file) o Add(key, file), se buscan mediante FindByName(name), se eliminan con Delete(name), DeleteByKey(key) o Delete(), y se enumeran a través de Count() y Keys(). Cada FileSpecification informa su Name(), Description(), MIMEType() y AFRelationship() — la clasificación de relación de archivo “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";
    }
}

Etiquetas de página

Document.PageLabels() devuelve una PageLabelCollection para las secuencias de numeración de página personalizadas que un visor muestra en lugar de los números de página físicos — por ejemplo, números romanos para una prefacio seguidos de números arábigos para el cuerpo. GetLabel(pageIndex) recupera el PageLabel en vigor para una página; PageLabel expone StartingValue(), NumberingStyle() (un valor Aspose::Pdf::NumberingStyle como NumeralsArabic o NumeralsRomanLowercase), y Prefix(). UpdateLabel(pageIndex, pageLabel) asigna una etiqueta a partir de esa página, RemoveLabel(pageIndex) la elimina, y GetPages() enumera cada índice de página que lleva una etiqueta personalizada.

#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");
}

Inicio rápido

Agregue la biblioteca como un subdirectorio de CMake y enlácela contra el objetivo aspose_pdf_foss:

add_subdirectory(aspose.pdf-foss-for-cpp)
target_link_libraries(your_app PRIVATE aspose_pdf_foss)

Abra un documento, lea y actualice sus metadatos /Info, y guarde el 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 compatibles

FormatoExtensiónLeerEscribir
BMP.bmp—✓
JPEG.jpg—✓
TIFF.tiff—✓
Text.txt—✓
SVG.svg✓—

BMP, JPEG y TIFF son salidas de renderizado de página producidas por sus respectivas clases de dispositivo, y el texto se extrae mediante TextAbsorber. SVG se importa como contenido vectorial a través de la ruta de carga SVG de la biblioteca. Ninguno de los tipos de gestión de documentos cubiertos arriba son convertidores de formato — solo leen y escriben la estructura PDF.

Código abierto y licencias

Aspose.PDF FOSS para C++ se distribuye bajo la licencia MIT, con el código fuente completo disponible en github.com/aspose-pdf-foss/Aspose.PDF-FOSS-for-Cpp. La licencia permite el uso comercial, la modificación y la redistribución sin un acuerdo separado.

Primeros pasos

Recursos relacionados