Gestire le proprietà della presentazione in Python

Introduzione

Aspose.Slides per Python tramite Java supporta le proprietà dei documenti integrate e personalizzate. Utilizza queste proprietà per leggere e aggiornare i metadati della presentazione, ad esempio autore, titolo e valori definiti dall’utente.

Aspose.Slides consente di lavorare con le proprietà dei documenti della presentazione tramite la classe DocumentProperties. Un’istanza di questa classe viene restituita da Presentation.getDocumentProperties. Gli esempi seguenti mostrano come leggere, modificare e gestire queste proprietà.

Gestire le proprietà della presentazione

Le proprietà del documento memorizzano informazioni descrittive insieme al contenuto della presentazione. Si suddividono in due categorie:

  • Proprietà integrate contengono metadati standard, come titolo, autore e statistiche del documento.
  • Proprietà personalizzate memorizzano coppie nome/valore definite dall’utente.

Aspose.Slides per Python tramite Java fornisce l’accesso a entrambe le categorie. In PowerPoint, seleziona File → Info → Proprietà → Proprietà avanzate per esaminare i metadati del documento. La finestra raggruppa le informazioni in schede quali Riepilogo, Statistiche, Contenuti e Personalizzato. Usa la scheda Personalizzato per gestire le proprietà definite dall’utente.

Leggere le proprietà pubbliche da una presentazione crittografata

Una password di apertura protegge normalmente sia il contenuto della presentazione sia le proprietà del documento. Quando una presentazione viene crittografata dopo aver chiamato ProtectionManager.setEncryptDocumentProperties con False, le sue proprietà del documento rimangono pubbliche. Un’applicazione può quindi chiamare LoadOptions.setOnlyLoadDocumentProperties con True e leggere i metadati pubblici senza fornire la password di apertura.

LoadOptions.setOnlyLoadDocumentProperties controlla cosa Aspose.Slides carica; non decritta nulla. Se le proprietà erano incluse nella crittografia, il caricamento senza password fallisce. Se la presentazione non è crittografata, l’opzione è ignorata e l’intera presentazione viene caricata.

L’esempio richiede una presentazione crittografata le cui proprietà del documento sono state lasciate pubbliche. Verifica la modalità di caricamento tramite ProtectionManager.isOnlyDocumentPropertiesLoaded e poi legge le proprietà integrate mediante 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()

In questa modalità, il contenuto delle diapositive non viene caricato. Diapositive, master, layout, forme, media e altri oggetti della presentazione non sono disponibili. Le applicazioni dovrebbero sempre verificare ProtectionManager.isOnlyDocumentPropertiesLoaded prima di eseguire un’operazione che richiede l’intero modello a oggetti della presentazione.

Aggiornare le proprietà di una presentazione crittografata

Per un file PPTX crittografato, una presentazione caricata dopo aver chiamato LoadOptions.setOnlyLoadDocumentProperties con True è destinata alla lettura dei metadati pubblici. Aspose.Slides non può salvare le proprietà cambiate da quell’oggetto “solo metadati” perché le proprietà pubbliche devono rimanere coerenti con i dati corrispondenti all’interno della presentazione crittografata. Per aggiornarle è quindi necessario fornire la password di apertura corretta e caricare l’intera presentazione.

L’esempio richiede una presentazione PPTX crittografata con proprietà del documento pubbliche e una password di apertura nota. Apre la presentazione completa con LoadOptions.setPassword, aggiorna le proprietà integrate pubbliche e salva il risultato. Quindi utilizza PresentationInfo.isEncrypted per verificare che la crittografia sia mantenuta e riapre i metadati pubblici senza password per verificare i nuovi valori:

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 un’applicazione non è autorizzata a decrittare o a caricare il contenuto della presentazione, deve trattare le proprietà pubbliche di un file PPTX crittografato come sola lettura.

Accedere alle proprietà integrate

La classe DocumentProperties espone i metadati integrati tramite metodi getter, tra cui getAuthor, getTitle e getCreatedTime. Questo esempio apre una presentazione esistente e stampa i metadati memorizzati sulla console. I valori dipendono dalla presentazione di ingresso; alcuni campi possono essere vuoti.

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()

Modificare le proprietà integrate

Per aggiornare i metadati integrati, utilizza i metodi setter sull’oggetto restituito da Presentation.getDocumentProperties. Questo esempio apre una presentazione esistente, chiama setAuthor, setTitle, setSubject, setComments e setManager, quindi salva la presentazione aggiornata con Presentation.save. Il PPTX salvato contiene i nuovi metadati.

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()

Gestire la base dei collegamenti ipertestuali

DocumentProperties.getHyperlinkBase restituisce la base a livello di documento per i collegamenti ipertestuali relativi. Usa DocumentProperties.setHyperlinkBase per modificarla o cancellarla. È utile quando si sposta una presentazione e i suoi file collegati in un’altra posizione. È separata dal metodo Hyperlink.getExternalUrl di un singolo collegamento: la modifica della base non riscrive gli indirizzi dei collegamenti memorizzati né cambia le destinazioni assolute.

L’esempio richiede una presentazione contenente sia un collegamento relativo, ad es. target.html, sia un collegamento assoluto, ad es. https://example.org/absolute.html. Legge la base esistente, assegna una nuova base, salva e riapre la presentazione per verificare il valore. Quindi cancella la base impostandola a stringa vuota e verifica il valore vuoto in un file salvato separato. Sostituisci la base di esempio con il percorso dei tuoi file collegati.

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()

I due messaggi di verifica dovrebbero stampare True. Cancellare la base mantiene inalterati gli indirizzi dei singoli collegamenti ipertestuali.

Un collegamento relativo a target.pptx apriva old/target.pptx quando la base puntava alla cartella old. Dopo aver cambiato la base nella cartella new, salvato e riaperto la presentazione, lo stesso collegamento apriva new/target.pptx. Un collegamento assoluto continuava ad aprire lo stesso file. Prova i tuoi collegamenti relativi in PowerPoint prima e dopo aver spostato la presentazione o cambiato la sua base.

Aggiungere proprietà personalizzate alla presentazione

Le proprietà personalizzate memorizzano metadati che non hanno un campo integrato corrispondente. Il metodo DocumentProperties.set_Item consente di assegnare un valore tramite il nome della proprietà. Questo esempio crea una presentazione, aggiunge due valori di testo e un valore intero di versione (usando jpype.JInt per passare un intero Java) e salva la presentazione con Presentation.save. Assegnare un valore a un nome esistente sostituisce il valore della proprietà.

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()

Accedere e modificare le proprietà personalizzate

Questo esempio apre una presentazione contenente proprietà personalizzate e utilizza getCountOfCustomProperties per iterarle. getCustomPropertyName accetta un indice basato su zero e restituisce il nome usato da DocumentProperties.set_Item. L’esempio stampa ogni nome e valore originali, sostituisce ogni valore con una stringa numerata indipendentemente dal tipo originale e salva le modifiche. Se non ci sono proprietà personalizzate, il ciclo non apporta modifiche.

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()

Esempio live

Prova l’app online Visualizza e modifica i metadati PowerPoint per vedere come lavorare con le proprietà dei documenti usando l’API Aspose.Slides:

Visualizza e modifica i metadati PowerPoint

FAQ

Come posso rimuovere una proprietà integrata da una presentazione?

Le proprietà integrate fanno parte integrante della presentazione e non possono essere rimosse del tutto. Tuttavia, è possibile modificarne i valori oppure impostarle a vuoto se la proprietà lo consente.

Cosa succede se aggiungo una proprietà personalizzata che esiste già?

Se aggiungi una proprietà personalizzata già presente, il valore esistente verrà sovrascritto con quello nuovo. Non è necessario rimuovere o verificare la proprietà in anticipo, poiché Aspose.Slides aggiorna automaticamente il valore della proprietà.

Posso accedere alle proprietà della presentazione senza caricarla completamente?

Sì. Usa PresentationFactory.getPresentationInfo e poi PresentationInfo.readDocumentProperties per leggere i metadati del documento memorizzati senza creare un’istanza di Presentation. Vedi Build a Lightweight Presentation Inventory per un esempio completo di reporting e per le limitazioni specifiche del formato.

Posso leggere le proprietà pubbliche di una presentazione crittografata senza la sua password di apertura?

Sì. La presentazione deve essere stata crittografata dopo aver chiamato ProtectionManager.setEncryptDocumentProperties con False, e deve essere caricata dopo aver chiamato LoadOptions.setOnlyLoadDocumentProperties con True.

Posso aggiornare un file PPTX crittografato in modalità “solo proprietà del documento”?

No. I dati delle proprietà pubbliche e crittografate devono rimanere coerenti, quindi aggiornare un file PPTX crittografato richiede il caricamento completo della presentazione con la password di apertura corretta.