Gerenciar propriedades da apresentação em Python

Introdução

Aspose.Slides for Python via Java suporta incorporadas e personalizadas propriedades de documento. Use estas propriedades para ler e atualizar metadados da apresentação, como o autor, título e valores definidos pelo usuário.

Aspose.Slides permite trabalhar com propriedades de documento de apresentação através da classe DocumentProperties . Uma instância dessa classe é retornada por Presentation.getDocumentProperties . Os exemplos a seguir mostram como ler, modificar e gerenciar essas propriedades.

Gerenciar Propriedades da Apresentação

As propriedades de documento armazenam informações descritivas ao lado do conteúdo da apresentação. Elas se classificam em duas categorias:

  • Propriedades incorporadas 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 Python via Java fornece acesso a ambas as categorias. No PowerPoint, selecione File → Info → Properties → Advanced Properties para inspecionar os metadados do documento. O diálogo agrupa as informações em abas como Summary, Statistics, Contents e Custom. Use a aba 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 após chamar ProtectionManager.setEncryptDocumentProperties com False, suas propriedades de documento permanecem públicas. Uma aplicação pode então chamar LoadOptions.setOnlyLoadDocumentProperties com True e ler os metadados públicos sem fornecer a senha de abertura.

LoadOptions.setOnlyLoadDocumentProperties 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 ProtectionManager.isOnlyDocumentPropertiesLoaded e então lê as propriedades incorporadas através de Presentation.getDocumentProperties:

import jpype
import asposeslides

if not jpype.isJVMStarted():
    jpype.startJVM()

from asposeslides.api import Presentation, LoadOptions

load_options = LoadOptions()
load_options.setOnlyLoadDocumentProperties(True)

presentation = Presentation("public-properties-encrypted.pptx", load_options)
try:
    if presentation.getProtectionManager().isOnlyDocumentPropertiesLoaded():
        properties = presentation.getDocumentProperties()

        print("Author: ", properties.getAuthor())
        print("Title: ", properties.getTitle())
        print("Keywords: ", properties.getKeywords())
    else:
        print("The presentation was not loaded in document-properties-only mode.")

finally:
    presentation.dispose()

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

Atualizar Propriedades de uma Apresentação Criptografada

Para um arquivo PPTX criptografado, uma apresentação carregada após chamar LoadOptions.setOnlyLoadDocumentProperties com True destina‑se à leitura de metadados públicos. O Aspose.Slides não pode salvar propriedades alteradas desse objeto que contém apenas 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.setPassword, atualiza as propriedades incorporadas públicas e salva o resultado. Em seguida, usa PresentationInfo.isEncrypted para verificar que a criptografia foi preservada e reabre os metadados públicos sem senha para confirmar os novos valores:

import jpype
import asposeslides

if not jpype.isJVMStarted():
    jpype.startJVM()

from asposeslides.api import Presentation, LoadOptions, PresentationFactory, SaveFormat

input_path = "public-properties-encrypted.pptx"
output_path = "updated-public-properties-encrypted.pptx"

load_options = LoadOptions()
load_options.setPassword("open_password")

presentation = Presentation(input_path, load_options)
try:
    presentation.getDocumentProperties().setTitle("Updated Product Roadmap")
    presentation.getDocumentProperties().setKeywords("roadmap, planning, indexed")
    
    presentation.save(output_path, SaveFormat.Pptx)
finally:
    presentation.dispose()

presentation_info = PresentationFactory.getInstance().getPresentationInfo(output_path)
print("The presentation is encrypted: ", presentation_info.isEncrypted())

metadata_load_options = LoadOptions()
metadata_load_options.setOnlyLoadDocumentProperties(True)

metadata_presentation = Presentation(output_path, metadata_load_options)
try:
    if metadata_presentation.getProtectionManager().isOnlyDocumentPropertiesLoaded():
        print("Title: ", metadata_presentation.getDocumentProperties().getTitle())
        print("Keywords: ", metadata_presentation.getDocumentProperties().getKeywords())
    else:
        print("The presentation was not loaded in document-properties-only mode.")

finally:
    metadata_presentation.dispose()

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 Incorporadas

A classe DocumentProperties expõe metadados incorporados por meio de métodos getter, incluindo getAuthor, getTitle e getCreatedTime. 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.

import jpype
import asposeslides

if not jpype.isJVMStarted():
    jpype.startJVM()

from asposeslides.api import Presentation

presentation = Presentation("AccessBuiltInProperties.pptx")
try:
    document_properties = presentation.getDocumentProperties()

    print("Category:", document_properties.getCategory())
    print("Content status:", document_properties.getContentStatus())
    print("Creation date:", document_properties.getCreatedTime())
    print("Author:", document_properties.getAuthor())
    print("Comments:", document_properties.getComments())
    print("Keywords:", document_properties.getKeywords())
    print("Last modified by:", document_properties.getLastSavedBy())
    print("Manager:", document_properties.getManager())
    print("Modified date:", document_properties.getLastSavedTime())
    print("Presentation format:", document_properties.getPresentationFormat())
    print("Last print date:", document_properties.getLastPrinted())
    print("Is shared between producers:", document_properties.getSharedDoc())
    print("Subject:", document_properties.getSubject())
    print("Title:", document_properties.getTitle())
finally:
    presentation.dispose()

Modificar Propriedades Incorporadas

Para atualizar metadados incorporados, use os métodos setter no objeto retornado por Presentation.getDocumentProperties. Este exemplo abre uma apresentação existente, chama setAuthor, setTitle, setSubject, setComments e setManager, então salva a apresentação atualizada com Presentation.save. O PPTX salvo contém os novos metadados.

import jpype
import asposeslides

if not jpype.isJVMStarted():
    jpype.startJVM()

from asposeslides.api import Presentation, SaveFormat

presentation = Presentation("ModifyBuiltInProperties.pptx")
try:
    document_properties = presentation.getDocumentProperties()

    document_properties.setAuthor("Aspose.Slides for Python via Java")
    document_properties.setTitle("Manage PowerPoint Presentation Properties")
    document_properties.setSubject("Modify Built-in Properties")
    document_properties.setComments("Aspose description")
    document_properties.setManager("Aspose manager")

    presentation.save("DocumentProperties_output.pptx", SaveFormat.Pptx)
finally:
    presentation.dispose()

DocumentProperties.getHyperlinkBase retorna a base ao nível do documento para hiperlinks relativos. Use DocumentProperties.setHyperlinkBase para alterá‑la ou limpá‑la. Isso é útil ao mover uma apresentação e seus arquivos vinculados para outro local. É separado do Hyperlink.getExternalUrl de um hiperlink individual: mudar a base não reescreve os endereços de link armazenados nem altera destinos absolutos.

O exemplo requer uma apresentação contendo 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 de base e salva e reabre a apresentação para verificação do valor. Em seguida, limpa a base com uma string vazia e verifica o valor vazio em um arquivo salvo separadamente. Substitua o endereço de base do exemplo pela localização de seus arquivos vinculados.

import jpype
import asposeslides

if not jpype.isJVMStarted():
    jpype.startJVM()

from asposeslides.api import Presentation, SaveFormat

presentation = Presentation("hyperlinks.pptx")
try:
    print("Original base:", presentation.getDocumentProperties().getHyperlinkBase())

    new_base = "https://example.com/new/"
    presentation.getDocumentProperties().setHyperlinkBase(new_base)
    presentation.save("hyperlinks-updated.pptx", SaveFormat.Pptx)

    updated_presentation = Presentation("hyperlinks-updated.pptx")
    try:
        print("Base preserved:", new_base == updated_presentation.getDocumentProperties().getHyperlinkBase())

        updated_presentation.getDocumentProperties().setHyperlinkBase("")
        updated_presentation.save("hyperlinks-cleared.pptx", SaveFormat.Pptx)

        cleared_presentation = Presentation("hyperlinks-cleared.pptx")
        try:
            print("Base cleared:", "" == cleared_presentation.getDocumentProperties().getHyperlinkBase())
        finally:
            cleared_presentation.dispose()
    finally:
        updated_presentation.dispose()
finally:
    presentation.dispose()

As duas mensagens de verificação devem imprimir True. Limpar a base mantém 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 alterar sua base.

Adicionar Propriedades Personalizadas à Apresentação

Propriedades personalizadas armazenam metadados que não têm campo incorporado correspondente. O método DocumentProperties.set_Item 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 (usando jpype.JInt para passar um inteiro Java), e salva a apresentação com Presentation.save. Atribuir um valor a um nome existente substitui o valor dessa propriedade.

import jpype
import asposeslides

if not jpype.isJVMStarted():
    jpype.startJVM()

from asposeslides.api import Presentation, SaveFormat

presentation = Presentation()
try:
    document_properties = presentation.getDocumentProperties()

    document_properties.set_Item("Reviewed by", "John Smith")
    document_properties.set_Item("Confidentiality level", "Internal")
    document_properties.set_Item("Document version", jpype.JInt(2))

    presentation.save("CustomDocumentProperties_output.pptx", SaveFormat.Pptx)
finally:
    presentation.dispose()

Acessar e Modificar Propriedades Personalizadas

Este exemplo abre uma apresentação contendo propriedades personalizadas e usa getCountOfCustomProperties para iterar sobre elas. getCustomPropertyName aceita um índice baseado em zero e retorna o nome usado por DocumentProperties.set_Item. 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.

import jpype
import asposeslides

if not jpype.isJVMStarted():
    jpype.startJVM()

from asposeslides.api import Presentation, SaveFormat

presentation = Presentation("AccessAndModifyProperties.pptx")
try:
    document_properties = presentation.getDocumentProperties()

    for i in range(document_properties.getCountOfCustomProperties()):
        property_name = document_properties.getCustomPropertyName(i)
        property_value = document_properties.get_Item(property_name)

        print("Custom property name:", property_name)
        print("Custom property value:", property_value)

        document_properties.set_Item(property_name, f"New Value {i + 1}")

    presentation.save("CustomProperties_output.pptx", SaveFormat.Pptx)
finally:
    presentation.dispose()

Exemplo ao Vivo

Experimente o aplicativo online Visualizar e Editar Metadados do PowerPoint para ver como trabalhar com propriedades de documento usando a API Aspose.Slides:

Visualizar e Editar Metadados do PowerPoint

Perguntas Frequentes

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

As propriedades incorporadas são parte integral da apresentação e não podem ser removidas completamente. No entanto, você pode mudar 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 atual será sobrescrito pelo novo. Não é necessário remover ou verificar a propriedade previamente, 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 PresentationInfo.readDocumentProperties para ler os metadados armazenados do documento sem criar uma instância de Presentation . Consulte Criar um Inventário Leve de Apresentações 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 após chamar ProtectionManager.setEncryptDocumentProperties com False, e deve ser carregada após chamar LoadOptions.setOnlyLoadDocumentProperties com True.

Posso atualizar um arquivo PPTX criptografado no modo apenas‑propriedades‑do‑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.