Gestire i segnaposto di presentazione in Java
Panoramica
Un segnaposto è una forma che riserva una posizione per un particolare tipo di contenuto in un modello di presentazione. Esempi comuni sono i segnaposto per titolo, corpo, immagine, grafico e contenuto di uso generale. A differenza di una forma ordinaria, un segnaposto può ereditare la sua posizione, dimensione, formattazione e altre impostazioni da una diapositiva di layout o da una diapositiva master.
Aspose.Slides espone le informazioni sui segnaposto tramite il metodo IShape.getPlaceholder. Il metodo restituisce un oggetto IPlaceholder o null per una forma normale. Utilizza IPlaceholder.getType per determinare cosa il segnaposto è destinato a contenere.
L’interfaccia della forma è ancora importante dopo aver conosciuto il tipo di segnaposto:
- Un segnaposto vuoto di testo, immagine, grafico o contenuto è comunemente rappresentato da un IAutoShape.
- Un segnaposto immagine popolato può essere rappresentato da un IPictureFrame.
- Un segnaposto grafico popolato può essere rappresentato da un IChart.
- Un segnaposto di contenuto può contenere diversi tipi di contenuto. Controlla sia IPlaceholder.getType sia l’interfaccia della forma a runtime invece di presumere che ogni segnaposto sia un IAutoShape.
Warning
IPlaceholder.getType descrive il ruolo di un segnaposto; non garantisce il tipo di forma a runtime. Usa sempre un controllo di tipo prima di accedere a membri specifici di testo, immagine, grafico, tabella o media.Comprendere l’Ereditarietà dei Segnaposto
I segnaposto formano una gerarchia:
- Una diapositiva master definisce stili riutilizzabili e, in alcuni casi, segnaposto a livello master.
- Una diapositiva di layout definisce la disposizione utilizzata da una o più diapositive normali e può ereditare dal master.
- Una diapositiva normale contiene i segnaposto per quella diapositiva e può ereditare dal suo layout.
Chiama IShape.getBasePlaceholder per spostarti di un livello verso l’alto in questa gerarchia. Un segnaposto di diapositiva normalmente restituisce il suo segnaposto di layout; un segnaposto di layout può restituire il suo segnaposto master. Il metodo restituisce null quando la forma non ha un segnaposto base.
Il seguente esempio elenca i segnaposto nella prima diapositiva e segnala i loro segnaposto base:
import com.aspose.slides.*;
Presentation presentation = new Presentation("template.pptx");
try {
ISlide slide = presentation.getSlides().get_Item(0);
for (IShape shape : slide.getShapes()) {
IPlaceholder placeholder = shape.getPlaceholder();
if (placeholder == null) {
continue;
}
byte placeholderType = placeholder.getType();
String typeName = shape.getClass().getSimpleName();
String slidePlaceholderMessage = "Slide placeholder: " + placeholderType + "; shape interface: " + typeName;
System.out.println(slidePlaceholderMessage);
IShape layoutPlaceholder = shape.getBasePlaceholder();
if (layoutPlaceholder != null) {
IPlaceholder layoutPlaceholderInfo = layoutPlaceholder.getPlaceholder();
Byte layoutPlaceholderType = layoutPlaceholderInfo == null ? null : layoutPlaceholderInfo.getType();
String layoutPlaceholderMessage = " Layout placeholder: " + layoutPlaceholderType;
System.out.println(layoutPlaceholderMessage);
IShape masterPlaceholder = layoutPlaceholder.getBasePlaceholder();
if (masterPlaceholder != null) {
IPlaceholder masterPlaceholderInfo = masterPlaceholder.getPlaceholder();
Byte masterPlaceholderType = masterPlaceholderInfo == null ? null : masterPlaceholderInfo.getType();
String masterPlaceholderMessage = " Master placeholder: " + masterPlaceholderType;
System.out.println(masterPlaceholderMessage);
}
}
}
} finally {
presentation.dispose();
}
Modificare un segnaposto su una diapositiva normale crea o modifica una sovrascrittura locale per quella diapositiva. Modificare il layout o il master correlato può influire su tutte le diapositive che ancora ereditano quella impostazione. Una forma locale ordinaria non ha un segnaposto base e non inizia a ereditare solo perché occupa le stesse coordinate.
Rimuovere lo Stato di Segnaposto
Quando si adatta un modello, usa IShape.removePlaceholder per mantenere un oggetto esistente come una forma ordinaria. Il suo metodo getPlaceholder restituisce null, ma la forma rimane nella collezione della diapositiva. Al contrario, IShapeCollection.remove elimina la forma da quella collezione.
Il seguente esempio richiede template.pptx con almeno una diapositiva e un segnaposto di testo non vuoto sulla prima diapositiva. Usa un segnaposto con formattazione ereditata dal suo layout o master per vedere l’effetto della rimozione di tale relazione. L’esempio verifica che la stessa forma rimanga, chiama nuovamente il metodo sulla forma ora ordinaria e salva il risultato.
Warning
Rimuovere lo stato di segnaposto non preserva automaticamente le impostazioni di aspetto ereditate. L’esempio seguente lascia deliberatamente quelle impostazioni invariate, quindi l’output potrebbe apparire diverso. Una forma la cui posizione e dimensione sono interamente ereditate può avere coordinate e dimensioni zero dopo la chiamata e diventare invisibile anche se rimane nella collezione.import com.aspose.slides.*;
Presentation presentation = new Presentation("template.pptx");
try {
ISlide slide = presentation.getSlides().get_Item(0);
boolean found = false;
for (int index = 0; index < slide.getShapes().size(); index++) {
IShape candidate = slide.getShapes().get_Item(index);
if (!(candidate instanceof IAutoShape)) {
continue;
}
IAutoShape shape = (IAutoShape) candidate;
ITextFrame textFrame = shape.getTextFrame();
if (shape.getPlaceholder() == null ||
textFrame == null ||
textFrame.getText() == null ||
textFrame.getText().isEmpty()) {
continue;
}
int shapeCount = slide.getShapes().size();
shape.removePlaceholder();
System.out.println("Placeholder removed: " + (shape.getPlaceholder() == null));
System.out.println("Same shape retained: " + (slide.getShapes().get_Item(index) == shape));
System.out.println("Shape count unchanged: " + (slide.getShapes().size() == shapeCount));
// Chiamare il metodo su una forma ordinaria non ha alcun effetto.
shape.removePlaceholder();
found = true;
break;
}
if (found) {
presentation.save("placeholder-status-removed.pptx", SaveFormat.Pptx);
} else {
System.out.println("No nonempty text placeholder was found on the first slide.");
}
} finally {
presentation.dispose();
}
Per un segnaposto corrispondente, tutti e tre i controlli stampano true. Il testo rimane, ma la posizione, dimensione, rotazione, carattere, allineamento dei paragrafi, margini del riquadro di testo, ancoraggio verticale, riempimento e impostazioni di linea ereditate possono cambiare quando la relazione del segnaposto viene rimossa. Ad esempio, la formattazione del titolo ereditata può tornare alla formattazione del testo ordinario. Vedi Slide Layout per ulteriori dettagli sui layout.
Per preservare l’aspetto previsto, cattura la posizione, dimensione e rotazione risolte prima della chiamata e copia i valori di formattazione effettiva richiesti in variabili separate. Recupera tali valori tramite IPortionFormat.getEffective, IParagraphFormat.getEffective, ITextFrameFormat.getEffective, IFillFormat.getEffective, e ILineFormat.getEffective. Non fare affidamento sul mantenimento solo degli oggetti di formattazione effettiva, poiché i loro valori di formattazione del testo possono cambiare dopo la rimozione della relazione. Applica esplicitamente i valori catturati alla forma ordinaria successivamente, includendo la famiglia di caratteri, dimensione, stile, colore, impostazioni di paragrafo, impostazioni del riquadro di testo, riempimento e linea usati dal tuo modello.
Anche la geometria della forma ereditata potrebbe dover essere assegnata esplicitamente tramite IGeometryShape.setShapeType. Per un segnaposto di testo rettangolare, ciò significa assegnare ShapeType.Rectangle; ripristinare solo il riempimento e la linea potrebbe non ripristinare il rettangolo visibile. I modelli con effetti aggiuntivi o formattazione più complessa richiedono che tali impostazioni vengano gestite anch’esse.
Modificare il Testo in un Segnaposto
I segnaposto per titolo, titolo centrato, sottotitolo, corpo e testo normalmente supportano il testo. Verifica la presenza di IAutoShape prima di usare il suo metodo getTextFrame.
Questo esempio aggiorna il primo segnaposto di titolo sulla prima diapositiva e salva il risultato:
import com.aspose.slides.*;
Presentation presentation = new Presentation("template.pptx");
try {
ISlide slide = presentation.getSlides().get_Item(0);
IAutoShape titleShape = null;
for (IShape shape : slide.getShapes()) {
if (!(shape instanceof IAutoShape)) {
continue;
}
IAutoShape autoShape = (IAutoShape) shape;
IPlaceholder placeholder = autoShape.getPlaceholder();
if (placeholder == null) {
continue;
}
byte placeholderType = placeholder.getType();
if (placeholderType == PlaceholderType.Title || placeholderType == PlaceholderType.CenteredTitle) {
titleShape = autoShape;
break;
}
}
if (titleShape == null) {
throw new IllegalStateException("The first slide does not contain a title placeholder.");
}
titleShape.getTextFrame().setText("Quarterly Business Review");
presentation.save("title-placeholder-updated.pptx", SaveFormat.Pptx);
} finally {
presentation.dispose();
}
Questo schema evita di fare cast di segnaposto immagine, grafico, tabella o media a IAutoShape. Identifica inoltre il segnaposto per scopo invece di fare affidamento su un indice di forma fragile.
Impostare il Testo di Prompt su un Layout
Il testo di prompt è l’istruzione di design-time visualizzata in un segnaposto vuoto, ad esempio Fare clic per aggiungere il titolo. Imposta un testo di prompt personalizzato sul segnaposto del layout invece di cercare di raggiungerlo tramite la collezione di forme di una diapositiva normale. Accedi al layout tramite ISlide.getLayoutSlide e itera sulla collezione restituita da ILayoutSlide.getShapes.
Il seguente esempio modifica i prompt di titolo e sottotitolo sul layout usato dalla prima diapositiva:
import com.aspose.slides.*;
Presentation presentation = new Presentation("template.pptx");
try {
ILayoutSlide layoutSlide = presentation.getSlides().get_Item(0).getLayoutSlide();
for (IShape shape : layoutSlide.getShapes()) {
if (!(shape instanceof IAutoShape)) {
continue;
}
IAutoShape autoShape = (IAutoShape) shape;
IPlaceholder placeholder = autoShape.getPlaceholder();
if (placeholder == null) {
continue;
}
byte placeholderType = placeholder.getType();
if (placeholderType == PlaceholderType.Title || placeholderType == PlaceholderType.CenteredTitle) {
autoShape.getTextFrame().setText("Enter a concise slide title");
} else if (placeholderType == PlaceholderType.Subtitle) {
autoShape.getTextFrame().setText("Enter a subtitle or reporting period");
}
}
presentation.save("custom-placeholder-prompts.pptx", SaveFormat.Pptx);
} finally {
presentation.dispose();
}
Il testo di prompt non è contenuto di una diapositiva normale. È destinato a segnaposto vuoti nelle applicazioni di editing come PowerPoint. Una volta che un utente o un programma fornisce contenuto reale, il prompt non viene più mostrato. Modificare un prompt non sostituisce nemmeno il testo esistente sulle diapositive che usano il layout.
Aggiornare un Segnaposto Immagine
Ci sono due casi da gestire:
- Se il segnaposto immagine è già popolato e rappresentato da un IPictureFrame, sostituisci l’immagine tramite IPictureFillFormat.getPicture e ISlidesPicture.setImage.
- Se è ancora un segnaposto vuoto, aggiungi un riquadro immagine alle coordinate del segnaposto con IShapeCollection.addPictureFrame e rimuovi il segnaposto vuoto.
Il prossimo esempio supporta entrambi i casi e salva la presentazione:
import com.aspose.slides.*;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.Paths;
Presentation presentation = new Presentation("picture-template.pptx");
try {
ISlide slide = presentation.getSlides().get_Item(0);
IShape picturePlaceholder = null;
for (IShape shape : slide.getShapes()) {
IPlaceholder placeholder = shape.getPlaceholder();
if (placeholder != null && placeholder.getType() == PlaceholderType.Picture) {
picturePlaceholder = shape;
break;
}
}
if (picturePlaceholder == null) {
throw new IllegalStateException("The first slide does not contain a picture placeholder.");
}
Path imagePath = Paths.get("replacement.png");
byte[] imageBytes = Files.readAllBytes(imagePath);
IPPImage image = presentation.getImages().addImage(imageBytes);
if (picturePlaceholder instanceof IPictureFrame) {
IPictureFrame pictureFrame = (IPictureFrame) picturePlaceholder;
pictureFrame.getPictureFormat().getPicture().setImage(image);
} else {
slide.getShapes().addPictureFrame(ShapeType.Rectangle, picturePlaceholder.getX(), picturePlaceholder.getY(), picturePlaceholder.getWidth(), picturePlaceholder.getHeight(), image);
slide.getShapes().remove(picturePlaceholder);
}
presentation.save("picture-placeholder-updated.pptx", SaveFormat.Pptx);
} finally {
presentation.dispose();
}
La sostituzione creata per un segnaposto vuoto è un riquadro immagine locale, non un nuovo segnaposto, perché IShape.getPlaceholder non fornisce un setter. Mantiene la posizione riservata ma non eredita più il comportamento specifico del segnaposto. Se mantenere la relazione del segnaposto è essenziale, prepara e popola il segnaposto in PowerPoint prima, poi aggiorna il risultato IPictureFrame con Aspose.Slides.
Per la trasparenza dell’immagine, il ritaglio e altri effetti specifici dell’immagine, vedi Manage Picture Frames. Queste operazioni appartengono al riquadro immagine o al riempimento immagine, non ai metadati del segnaposto.
Lavorare con Segnaposto Grafico e di Contenuto
Un segnaposto grafico popolato può essere rappresentato da un IChart. Questo esempio trova tale grafico sia per tipo di segnaposto sia per interfaccia a runtime, ne cambia il titolo e salva il file:
import com.aspose.slides.*;
Presentation presentation = new Presentation("chart-template.pptx");
try {
ISlide slide = presentation.getSlides().get_Item(0);
IChart placeholderChart = null;
for (IShape shape : slide.getShapes()) {
if (!(shape instanceof IChart)) {
continue;
}
IChart chart = (IChart) shape;
IPlaceholder placeholder = chart.getPlaceholder();
if (placeholder != null && placeholder.getType() == PlaceholderType.Chart) {
placeholderChart = chart;
break;
}
}
if (placeholderChart == null) {
throw new IllegalStateException("The first slide does not contain a populated chart placeholder.");
}
placeholderChart.setTitle(true);
placeholderChart.getChartTitle().addTextFrameForOverriding("Quarterly Revenue");
presentation.save("chart-placeholder-updated.pptx", SaveFormat.Pptx);
} finally {
presentation.dispose();
}
Un segnaposto di contenuto generico solitamente ha PlaceholderType.Object. In PowerPoint funge da lanciatore per diversi tipi di contenuto, tra cui grafici, tabelle, diagrammi, immagini e media. Dopo essere stato popolato, ispeziona l’effettiva interfaccia della forma per capire cosa contiene. I layout specializzati possono anche esporre PlaceholderType.Chart, PlaceholderType.Table, PlaceholderType.Picture, PlaceholderType.Media, o PlaceholderType.Diagram.
Aspose.Slides non converte un segnaposto vuoto IAutoShape in un IChart semplicemente cambiando IPlaceholder.getType; il tipo non può essere modificato tramite l’interfaccia. Per riempire programmaticamente un’area grafico o di contenuto vuota, aggiungi l’oggetto richiesto alle coordinate del segnaposto e poi rimuovi il segnaposto vuoto. Il seguente esempio lo fa per un grafico:
import com.aspose.slides.*;
Presentation presentation = new Presentation("content-template.pptx");
try {
ISlide slide = presentation.getSlides().get_Item(0);
IShape targetPlaceholder = null;
for (IShape shape : slide.getShapes()) {
IPlaceholder placeholder = shape.getPlaceholder();
if (placeholder == null) {
continue;
}
byte placeholderType = placeholder.getType();
if (placeholderType == PlaceholderType.Chart || placeholderType == PlaceholderType.Object) {
targetPlaceholder = shape;
break;
}
}
if (targetPlaceholder == null) {
throw new IllegalStateException("The first slide does not contain a chart or content placeholder.");
}
IChart chart = slide.getShapes().addChart(ChartType.ClusteredColumn, targetPlaceholder.getX(), targetPlaceholder.getY(), targetPlaceholder.getWidth(), targetPlaceholder.getHeight());
chart.setTitle(true);
chart.getChartTitle().addTextFrameForOverriding("Quarterly Revenue");
slide.getShapes().remove(targetPlaceholder);
presentation.save("content-placeholder-replaced-with-chart.pptx", SaveFormat.Pptx);
} finally {
presentation.dispose();
}
Il grafico aggiunto è un grafico locale ordinario. Occupa l’area del segnaposto ma non eredita dal segnaposto del layout. Usa gli articoli di gestione dei grafici quando è necessario sostituire le sue categorie, serie o dati della cartella di lavoro.
Esempio Completo: Aggiornare Testo o Immagine
Il seguente esempio end-to-end apre un modello, cerca nella prima diapositiva un segnaposto di titolo o immagine, controlla i tipi di segnaposto e di forma, aggiorna il contenuto appropriato e salva l’output. L’esempio evita deliberatamente di presumere un indice di forma o di fare cast di tutti i segnaposto alla stessa interfaccia.
import com.aspose.slides.*;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.Paths;
Presentation presentation = new Presentation("template.pptx");
try {
ISlide slide = presentation.getSlides().get_Item(0);
boolean updated = false;
for (IShape shape : slide.getShapes()) {
IPlaceholder placeholder = shape.getPlaceholder();
if (placeholder == null) {
continue;
}
byte placeholderType = placeholder.getType();
if ((placeholderType == PlaceholderType.Title || placeholderType == PlaceholderType.CenteredTitle) && shape instanceof IAutoShape) {
IAutoShape titleShape = (IAutoShape) shape;
titleShape.getTextFrame().setText("Quarterly Business Review");
updated = true;
break;
}
if (placeholderType == PlaceholderType.Picture) {
Path imagePath = Paths.get("replacement.png");
byte[] imageBytes = Files.readAllBytes(imagePath);
IPPImage image = presentation.getImages().addImage(imageBytes);
if (shape instanceof IPictureFrame) {
IPictureFrame pictureFrame = (IPictureFrame) shape;
pictureFrame.getPictureFormat().getPicture().setImage(image);
} else {
slide.getShapes().addPictureFrame(ShapeType.Rectangle, shape.getX(), shape.getY(), shape.getWidth(), shape.getHeight(), image);
slide.getShapes().remove(shape);
}
updated = true;
break;
}
}
if (!updated) {
throw new IllegalStateException("No supported title or picture placeholder was found on the first slide.");
}
presentation.save("placeholder-content-updated.pptx", SaveFormat.Pptx);
} finally {
presentation.dispose();
}
FAQ
Che cos’è un segnaposto base?
Un segnaposto base è la forma corrispondente nel layout o nel master da cui un altro segnaposto eredita. Usa IShape.getBasePlaceholder per recuperarlo. Una forma locale ordinaria restituisce null perché non fa parte della gerarchia dei segnaposto.
Posso modificare tutti i titoli delle diapositive modificando un segnaposto di layout?
Puoi cambiare la formattazione ereditata o il testo di prompt tramite un layout, ma il contenuto del titolo esistente è memorizzato sulle diapositive normali. Per sostituire il testo del titolo reale in tutta la presentazione, itera sulle diapositive e aggiorna ciascun segnaposto di titolo.
Come gestisco i segnaposto data, numero-di-diapositiva, intestazione e piè di pagina?
Usa i gestori di intestazione e piè di pagina nello scope appropriato di diapositiva, layout, master, note o dispensa. Vedi Manage Presentation Header and Footer per esempi completi.