Gerenciar Propriedades da Apresentação em C++

Introdução

Aspose.Slides for C++ oferece suporte a propriedades de documento integradas e personalizadas. Use essas propriedades para ler e atualizar os metadados da apresentação, como autor, título e valores definidos pelo usuário.

Aspose.Slides permite trabalhar com as propriedades de documento da apresentação através da interface IDocumentProperties. Uma instância dessa interface é retornada por IPresentation::get_DocumentProperties. Os exemplos a seguir mostram como ler, modificar e gerenciar essas propriedades.

Gerenciar Propriedades da Apresentação

Propriedades de documento armazenam informações descritivas juntamente com o conteúdo da apresentação. Elas se dividem em duas categorias:

  • Propriedades integradas contêm metadados padrão, como título, autor e estatísticas do documento.
  • Propriedades personalizadas armazenam pares nome/valor definidos pelo usuário.

Aspose.Slides for C++ fornece acesso a ambas as categorias. No PowerPoint, selecione File → Info → Properties → Advanced Properties para inspecionar os metadados do documento. A caixa de diálogo agrupa as informações em guias como Summary, Statistics, Contents e Custom. Use a guia Custom para gerenciar propriedades definidas pelo usuário.

Ler Propriedades Públicas de uma Apresentação Criptografada

Uma senha de abertura normalmente protege tanto o conteúdo da apresentação quanto as propriedades do documento. Quando uma apresentação é criptografada passando false para IProtectionManager::set_EncryptDocumentProperties, suas propriedades de documento permanecem públicas. Uma aplicação pode então passar true para LoadOptions::set_OnlyLoadDocumentProperties e ler os metadados públicos sem fornecer a senha de abertura.

LoadOptions::set_OnlyLoadDocumentProperties controla o que o Aspose.Slides carrega; não descriptografa nada. Se as propriedades foram incluídas na criptografia, carregá‑las sem a senha falha. Se a apresentação não estiver criptografada, a opção é ignorada e a apresentação completa é carregada.

O exemplo requer uma apresentação criptografada cujas propriedades de documento foram deixadas públicas. Ele verifica o modo de carregamento através de IProtectionManager::get_IsOnlyDocumentPropertiesLoaded, e então lê as propriedades integradas através de IPresentation::get_DocumentProperties:

#include <DOM/IDocumentProperties.h>
#include <DOM/Presentation.h>
#include <system/console.h>
#include <DOM/LoadOptions.h>
#include <DOM/IProtectionManager.h>

using namespace Aspose::Slides;

auto loadOptions = System::MakeObject<LoadOptions>();
loadOptions->set_OnlyLoadDocumentProperties(true);

auto presentation = System::MakeObject<Presentation>(u"public-properties-encrypted.pptx", loadOptions);

if (presentation->get_ProtectionManager()->get_IsOnlyDocumentPropertiesLoaded())
{
    auto documentProperties = presentation->get_DocumentProperties();

    System::Console::WriteLine(u"Author: {0}", documentProperties->get_Author());
    System::Console::WriteLine(u"Title: {0}", documentProperties->get_Title());
    System::Console::WriteLine(u"Keywords: {0}", documentProperties->get_Keywords());
}
else
{
    System::Console::WriteLine(u"The presentation was not loaded in document-properties-only mode.");
}

Nesse modo, o conteúdo dos slides não é carregado. Slides, mestres, layouts, formas, mídias e outros objetos da apresentação ficam indisponíveis. As aplicações devem sempre verificar IProtectionManager::get_IsOnlyDocumentPropertiesLoaded antes de executar uma operação que requer o modelo de objeto completo da apresentação.

Atualizar Propriedades de uma Apresentação Criptografada

Para um arquivo PPTX criptografado, uma apresentação carregada passando true para LoadOptions::set_OnlyLoadDocumentProperties destina‑se a ler metadados públicos. O Aspose.Slides não pode salvar propriedades alteradas desse objeto somente‑metadados porque as propriedades públicas devem permanecer consistentes com os dados correspondentes dentro da apresentação criptografada. Atualizá‑las, portanto, requer a senha de abertura correta e um carregamento completo.

O exemplo requer uma apresentação PPTX criptografada com propriedades de documento públicas e uma senha de abertura conhecida. Ele abre a apresentação completa com LoadOptions::set_Password, atualiza as propriedades integradas públicas e salva o resultado. Em seguida, usa IPresentationInfo::get_IsEncrypted para verificar que a criptografia foi preservada e reabre os metadados públicos sem senha para conferir os novos valores:

#include <DOM/IDocumentProperties.h>
#include <DOM/Presentation.h>
#include <system/console.h>
#include <DOM/LoadOptions.h>
#include <DOM/IProtectionManager.h>
#include <DOM/PresentationFactory.h>
#include <DOM/IPresentationInfo.h>
#include <Export/SaveFormat.h>

using namespace Aspose::Slides;
using namespace Aspose::Slides::Export;

const System::String inputPath = u"public-properties-encrypted.pptx";
const System::String outputPath = u"updated-public-properties-encrypted.pptx";

auto loadOptions = System::MakeObject<LoadOptions>();
loadOptions->set_Password(u"open_password");

auto presentation = System::MakeObject<Presentation>(inputPath, loadOptions);

auto documentProperties = presentation->get_DocumentProperties();
documentProperties->set_Title(u"Updated Product Roadmap");
documentProperties->set_Keywords(u"roadmap, planning, indexed");

presentation->Save(outputPath, SaveFormat::Pptx);

auto presentationInfo = PresentationFactory::get_Instance()->GetPresentationInfo(outputPath);
System::Console::WriteLine(u"The presentation is encrypted: {0}", presentationInfo->get_IsEncrypted());

auto metadataLoadOptions = System::MakeObject<LoadOptions>();
metadataLoadOptions->set_OnlyLoadDocumentProperties(true);

auto metadataPresentation = System::MakeObject<Presentation>(outputPath, metadataLoadOptions);

if (metadataPresentation->get_ProtectionManager()->get_IsOnlyDocumentPropertiesLoaded())
{
    System::Console::WriteLine(u"Title: {0}", metadataPresentation->get_DocumentProperties()->get_Title());
    System::Console::WriteLine(u"Keywords: {0}", metadataPresentation->get_DocumentProperties()->get_Keywords());
}
else
{
    System::Console::WriteLine(u"The presentation was not loaded in document-properties-only mode.");
}

Se uma aplicação não tem permissão para descriptografar ou carregar o conteúdo da apresentação, ela deve tratar as propriedades públicas de um arquivo PPTX criptografado como somente leitura.

Acessar Propriedades Integradas

A interface IDocumentProperties expõe metadados integrados por meio de getters tipados, incluindo get_Author, get_Title e get_CreatedTime. Este exemplo abre uma apresentação existente e imprime seus metadados armazenados no console. Os valores dependem da apresentação de entrada; alguns campos podem estar vazios.

#include <DOM/IDocumentProperties.h>
#include <DOM/Presentation.h>
#include <system/console.h>

using namespace Aspose::Slides;

auto presentation = System::MakeObject<Presentation>(u"AccessBuiltInProperties.pptx");

auto documentProperties = presentation->get_DocumentProperties();

System::Console::WriteLine(u"Category: {0}", documentProperties->get_Category());
System::Console::WriteLine(u"Content status: {0}", documentProperties->get_ContentStatus());
System::Console::WriteLine(u"Creation date: {0}", documentProperties->get_CreatedTime());
System::Console::WriteLine(u"Author: {0}", documentProperties->get_Author());
System::Console::WriteLine(u"Comments: {0}", documentProperties->get_Comments());
System::Console::WriteLine(u"Keywords: {0}", documentProperties->get_Keywords());
System::Console::WriteLine(u"Last modified by: {0}", documentProperties->get_LastSavedBy());
System::Console::WriteLine(u"Manager: {0}", documentProperties->get_Manager());
System::Console::WriteLine(u"Modified date: {0}", documentProperties->get_LastSavedTime());
System::Console::WriteLine(u"Presentation format: {0}", documentProperties->get_PresentationFormat());
System::Console::WriteLine(u"Last print date: {0}", documentProperties->get_LastPrinted());
System::Console::WriteLine(u"Is shared between producers: {0}", documentProperties->get_SharedDoc());
System::Console::WriteLine(u"Subject: {0}", documentProperties->get_Subject());
System::Console::WriteLine(u"Title: {0}", documentProperties->get_Title());

Modificar Propriedades Integradas

Para atualizar metadados integrados, use os setters no objeto retornado por IPresentation::get_DocumentProperties. Este exemplo abre uma apresentação existente, chama set_Author, set_Title, set_Subject, set_Comments e set_Manager, então salva a apresentação atualizada com Presentation::Save. O PPTX salvo contém os novos metadados.

#include <DOM/IDocumentProperties.h>
#include <DOM/Presentation.h>
#include <system/console.h>
#include <Export/SaveFormat.h>

using namespace Aspose::Slides;
using namespace Aspose::Slides::Export;

auto presentation = System::MakeObject<Presentation>(u"ModifyBuiltInProperties.pptx");

auto documentProperties = presentation->get_DocumentProperties();

documentProperties->set_Author(u"Aspose.Slides for C++");
documentProperties->set_Title(u"Manage PowerPoint Presentation Properties");
documentProperties->set_Subject(u"Modify Built-in Properties");
documentProperties->set_Comments(u"Aspose description");
documentProperties->set_Manager(u"Aspose manager");

presentation->Save(u"DocumentProperties_output.pptx", SaveFormat::Pptx);

IDocumentProperties::get_HyperlinkBase lê a base ao nível do documento para hiperlinks relativos. Isso é útil ao mover uma apresentação e seus arquivos vinculados para outro local. É independente do IHyperlink::get_ExternalUrl de um hiperlink individual: alterar a base não reescreve os endereços de link armazenados nem altera destinos absolutos.

O exemplo requer uma apresentação que contenha tanto um link relativo, como target.html, quanto um link absoluto, como https://example.org/absolute.html. Ele lê a base existente, atribui um novo endereço base com IDocumentProperties::set_HyperlinkBase, salva e reabre a apresentação para verificar o valor. Em seguida, limpa a base com u"" e verifica o valor vazio em um arquivo salvo separado. Substitua o endereço base do exemplo pela localização dos seus arquivos vinculados.

#include <DOM/IDocumentProperties.h>
#include <DOM/Presentation.h>
#include <system/console.h>
#include <Export/SaveFormat.h>

using namespace Aspose::Slides;
using namespace Aspose::Slides::Export;

auto presentation = System::MakeObject<Presentation>(u"hyperlinks.pptx");

System::Console::WriteLine(u"Original base: {0}", presentation->get_DocumentProperties()->get_HyperlinkBase());

const System::String newBase = u"https://example.com/new/";
presentation->get_DocumentProperties()->set_HyperlinkBase(newBase);
presentation->Save(u"hyperlinks-updated.pptx", SaveFormat::Pptx);

auto updatedPresentation = System::MakeObject<Presentation>(u"hyperlinks-updated.pptx");
System::Console::WriteLine(u"Base preserved: {0}", (updatedPresentation->get_DocumentProperties()->get_HyperlinkBase() == newBase));

updatedPresentation->get_DocumentProperties()->set_HyperlinkBase(u"");
updatedPresentation->Save(u"hyperlinks-cleared.pptx", SaveFormat::Pptx);

auto clearedPresentation = System::MakeObject<Presentation>(u"hyperlinks-cleared.pptx");
System::Console::WriteLine(u"Base cleared: {0}", (clearedPresentation->get_DocumentProperties()->get_HyperlinkBase() == u""));

As duas mensagens de verificação devem imprimir True. Limpar a base deixa os endereços de hiperlink individuais intactos.

Um link relativo para target.pptx abriu old/target.pptx quando a base apontava para a pasta old. Após mudar a base para a pasta new, salvar e reabrir a apresentação, o mesmo link abriu new/target.pptx. Um link absoluto continuou a abrir o mesmo arquivo. Teste seus links relativos no PowerPoint antes e depois de mover a apresentação ou mudar sua base.

Adicionar Propriedades Personalizadas à Apresentação

As propriedades personalizadas armazenam metadados que não têm um campo integrado correspondente. IDocumentProperties::idx_set permite atribuir um valor pelo nome da propriedade. Este exemplo cria uma apresentação, adiciona dois valores de texto e um valor inteiro de versão, e salva a apresentação com Presentation::Save. Atribuir um valor a um nome existente substitui o valor daquela propriedade.

#include <DOM/IDocumentProperties.h>
#include <DOM/Presentation.h>
#include <system/console.h>
#include <Export/SaveFormat.h>
#include <system/object_ext.h>

using namespace Aspose::Slides;
using namespace Aspose::Slides::Export;

auto presentation = System::MakeObject<Presentation>();

auto documentProperties = presentation->get_DocumentProperties();

documentProperties->idx_set(u"Reviewed by", System::ObjectExt::Box<System::String>(u"John Smith"));
documentProperties->idx_set(u"Confidentiality level", System::ObjectExt::Box<System::String>(u"Internal"));
documentProperties->idx_set(u"Document version", System::ObjectExt::Box(2));

presentation->Save(u"CustomDocumentProperties_output.pptx", SaveFormat::Pptx);

Acessar e Modificar Propriedades Personalizadas

Este exemplo abre uma apresentação contendo propriedades personalizadas e usa get_CountOfCustomProperties para iterar sobre elas. GetCustomPropertyName aceita um índice baseado em zero e retorna o nome usado por IDocumentProperties::idx_get e idx_set. O exemplo imprime cada nome e valor original, substitui cada valor por uma string numerada independentemente do tipo original, e salva as alterações. Se não houver propriedades personalizadas, o loop não faz alterações.

#include <DOM/IDocumentProperties.h>
#include <DOM/Presentation.h>
#include <system/console.h>
#include <Export/SaveFormat.h>
#include <system/object_ext.h>

using namespace Aspose::Slides;
using namespace Aspose::Slides::Export;

auto presentation = System::MakeObject<Presentation>(u"AccessAndModifyProperties.pptx");

auto documentProperties = presentation->get_DocumentProperties();

for (auto i = 0; i < documentProperties->get_CountOfCustomProperties(); i++)
{
    auto propertyName = documentProperties->GetCustomPropertyName(i);
    auto propertyValue = documentProperties->idx_get(propertyName);

    System::Console::WriteLine(u"Custom property name: {0}", propertyName);
    System::Console::WriteLine(u"Custom property value: {0}", propertyValue);

    documentProperties->idx_set(propertyName, System::ObjectExt::Box(System::String::Format(u"New Value {0}", i + 1)));
}

presentation->Save(u"CustomProperties_output.pptx", SaveFormat::Pptx);

Exemplo ao Vivo

Tente o aplicativo online View & Edit PowerPoint Metadata para ver como trabalhar com propriedades de documento usando a API Aspose.Slides:

Visualizar & Editar Metadados do PowerPoint

Perguntas Frequentes

Como posso remover uma propriedade integrada de uma apresentação?

As propriedades integradas são parte integrante da apresentação e não podem ser removidas totalmente. No entanto, você pode alterar seus valores ou defini‑las como vazias, se a propriedade específica permitir.

O que acontece se eu adicionar uma propriedade personalizada que já existe?

Se você adicionar uma propriedade personalizada que já existe, seu valor existente será sobrescrito pelo novo. Não é necessário remover ou verificar a propriedade antecipadamente, pois o Aspose.Slides atualiza automaticamente o valor da propriedade.

Posso acessar as propriedades da apresentação sem carregar totalmente a apresentação?

Sim. Use PresentationFactory::GetPresentationInfo e então IPresentationInfo::ReadDocumentProperties para ler os metadados do documento armazenados sem criar uma instância de Presentation. Consulte Build a Lightweight Presentation Inventory para um exemplo completo de relatório e limitações específicas de formato.

Posso ler propriedades públicas de uma apresentação criptografada sem sua senha de abertura?

Sim. A apresentação deve ter sido criptografada passando false para IProtectionManager::set_EncryptDocumentProperties, e deve ser carregada passando true para LoadOptions::set_OnlyLoadDocumentProperties.

Posso atualizar um arquivo PPTX criptografado no modo somente‑propriedades‑de‑documento?

Não. Os dados de propriedades públicas e criptografadas devem permanecer consistentes, portanto, atualizar um arquivo PPTX criptografado requer carregar a apresentação completa com a senha de abertura correta.