Gestionar marcadores de posición de presentación en Java
Descripción general
Un marcador de posición es una forma que reserva una posición para un tipo particular de contenido en una plantilla de presentación. Los ejemplos más comunes son marcadores de título, cuerpo, imagen, gráfico y marcadores de contenido de propósito general. A diferencia de una forma ordinaria, un marcador de posición puede heredar su posición, tamaño, formato y otros ajustes de una diapositiva de diseño o de una diapositiva maestra.
Aspose.Slides expone la información de los marcadores de posición a través del método IShape.getPlaceholder . El método devuelve un objeto IPlaceholder o null para una forma normal. Utilice IPlaceholder.getType para determinar qué se pretende contener en el marcador de posición.
La interfaz de forma sigue siendo importante después de conocer el tipo de marcador de posición:
- Un marcador de posición vacío de texto, imagen, gráfico o contenido se representa comúnmente con un IAutoShape .
- Un marcador de posición de imagen poblado puede representarse con un IPictureFrame .
- Un marcador de posición de gráfico poblado puede representarse con un IChart .
- Un marcador de posición de contenido puede contener varios tipos de contenido. Compruebe tanto IPlaceholder.getType como la interfaz de forma en tiempo de ejecución en lugar de asumir que cada marcador de posición es un IAutoShape .
Warning
IPlaceholder.getType describe el rol de un marcador de posición; no garantiza el tipo en tiempo de ejecución de la forma. Siempre realice una comprobación de tipo antes de acceder a miembros específicos de texto, imagen, gráfico, tabla o medios.Comprender la herencia de marcadores de posición
Los marcadores de posición forman una jerarquía:
- Una diapositiva maestra define estilos reutilizables y, en algunos casos, marcadores de nivel maestro.
- Una diapositiva de diseño define la disposición utilizada por una o más diapositivas normales y puede heredar de la maestra.
- Una diapositiva normal contiene los marcadores de posición para esa diapositiva y puede heredar de su diseño.
Llame a IShape.getBasePlaceholder para subir un nivel en esta jerarquía. Un marcador de posición de diapositiva normalmente devuelve su marcador de posición de diseño; un marcador de posición de diseño puede devolver su marcador de posición maestro. El método devuelve null cuando la forma no tiene marcador de posición base.
El siguiente ejemplo enumera los marcadores de posición en la primera diapositiva e informa de sus marcadores de posición 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();
}
Editar un marcador de posición en una diapositiva normal crea o modifica una anulación local para esa diapositiva. Editar el diseño o la maestra relacionados puede afectar a todas las diapositivas que aún heredan esa configuración. Una forma ordinaria local no tiene marcador de posición base y no comienza a heredar simplemente porque ocupa las mismas coordenadas.
Eliminar el estado de marcador de posición
Al adaptar una plantilla, use IShape.removePlaceholder para mantener un objeto existente como una forma ordinaria. Su método getPlaceholder devuelve null, pero la forma permanece en la colección de la diapositiva. En contraste, IShapeCollection.remove elimina la forma de esa colección.
El siguiente ejemplo requiere template.pptx con al menos una diapositiva y un marcador de posición de texto no vacío en la primera diapositiva. Utilice un marcador de posición con formato heredado de su diseño o maestro para ver el efecto de eliminar esa relación. El ejemplo verifica que la misma forma permanezca, llama al método nuevamente sobre la forma ahora ordinaria y guarda el resultado.
Warning
Eliminar el estado de marcador de posición no conserva automáticamente los ajustes de apariencia heredados. El ejemplo a continuación deja deliberadamente esos ajustes sin cambios, por lo que la salida puede verse diferente. Una forma cuya posición y tamaño son totalmente heredados puede tener coordenadas y dimensiones cero después de la llamada y volverse invisible aunque siga en la colección.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));
// Llamar al método sobre una forma ordinaria no tiene efecto.
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();
}
Para un marcador de posición coincidente, las tres comprobaciones imprimen true. El texto permanece, pero la posición, tamaño, rotación, fuente, alineación de párrafo, márgenes del marco de texto, anclaje vertical, relleno y ajustes de línea heredados pueden cambiar cuando se elimina la relación del marcador de posición. Por ejemplo, el formato del título heredado puede revertir al formato de texto ordinario. Consulte Diseño de diapositiva para más información sobre diseños.
Para preservar la apariencia prevista, capture la posición, tamaño y rotación resueltos antes de la llamada y copie los valores de formato efectivo requeridos en variables separadas. Obtenga esos valores a través de IPortionFormat.getEffective, IParagraphFormat.getEffective, ITextFrameFormat.getEffective, IFillFormat.getEffective, y ILineFormat.getEffective. No confíe solo en los objetos de formato efectivo, porque sus valores de formato de texto pueden cambiar después de eliminar la relación. Aplique explícitamente los valores capturados a la forma ordinaria posteriormente, incluyendo la familia, tamaño, estilo, color de fuente, ajustes de párrafo, ajustes del marco de texto, relleno y línea utilizados por su plantilla.
La geometría heredada de la forma también puede necesitar asignarse explícitamente mediante IGeometryShape.setShapeType. Para un marcador de posición rectangular de texto, esto significa asignar ShapeType.Rectangle; restaurar solo el relleno y la línea puede no restaurar el rectángulo visible. Las plantillas con efectos adicionales o formato más complejo requieren que esos ajustes también se gestionen.
Cambiar el texto en un marcador de posición
Los marcadores de título, título centrado, subtítulo, cuerpo y texto normalmente admiten texto. Verifique la existencia de un IAutoShape antes de usar su método getTextFrame .
Este ejemplo actualiza el primer marcador de posición de título en la primera diapositiva y guarda el resultado:
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();
}
Este patrón evita convertir a castings los marcadores de posición de imagen, gráfico, tabla o medios a IAutoShape . También identifica el marcador de posición por su propósito en lugar de confiar en un índice de forma frágil.
Establecer texto de sugerencia en un diseño
El texto de sugerencia es la instrucción de tiempo de diseño que se muestra en un marcador de posición vacío, como Haga clic para añadir título. Establezca texto de sugerencia personalizado en el marcador de posición del diseño en lugar de intentar alcanzarlo a través de la colección de formas de una diapositiva normal. Acceda al diseño mediante ISlide.getLayoutSlide e itere sobre la colección devuelta por ILayoutSlide.getShapes .
El siguiente ejemplo cambia las sugerencias de título y subtítulo en el diseño utilizado por la primera 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();
}
El texto de sugerencia no es contenido normal de diapositiva. Está destinado a marcadores de posición vacíos en aplicaciones de edición como PowerPoint. Una vez que un usuario o programa proporciona contenido real, la sugerencia deja de mostrarse. Cambiar una sugerencia tampoco sustituye el texto existente en las diapositivas que usan el diseño.
Actualizar un marcador de posición de imagen
Hay dos casos a manejar:
- Si el marcador de posición de imagen ya está poblado y representado por un IPictureFrame , reemplace la imagen mediante IPictureFillFormat.getPicture y ISlidesPicture.setImage .
- Si sigue siendo un marcador de posición vacío, añada un marco de imagen en las coordenadas del marcador de posición con IShapeCollection.addPictureFrame y elimine el marcador de posición vacío.
El siguiente ejemplo admite ambos casos y guarda la presentación:
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();
}
El sustituto creado para un marcador de posición vacío es un marco de imagen local, no un nuevo marcador de posición, porque IShape.getPlaceholder no ofrece un setter. Conserva la posición reservada pero ya no hereda el comportamiento específico del marcador de posición. Si es esencial conservar la relación del marcador de posición, prepare y llene el marcador de posición en PowerPoint primero, y luego actualice el IPictureFrame resultante con Aspose.Slides.
Para transparencia de imagen, recorte y otros efectos específicos de la imagen, consulte Administrar marcos de imagen . esas operaciones pertenecen al marco de imagen o al relleno de imagen, no a los metadatos del marcador de posición.
Trabajar con marcadores de posición de gráfico y contenido
Un marcador de posición de gráfico poblado puede representarse con un IChart . Este ejemplo encuentra dicho gráfico tanto por tipo de marcador de posición como por interfaz en tiempo de ejecución, cambia su título y guarda el archivo:
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 marcador de posición de contenido general suele tener PlaceholderType.Object . En PowerPoint actúa como lanzador para varios tipos de contenido, incluidos gráficos, tablas, diagramas, imágenes y medios. Después de que se haya poblado, inspeccione la interfaz de forma real para saber qué contiene. Los diseños especializados también pueden exponer PlaceholderType.Chart, PlaceholderType.Table, PlaceholderType.Picture, PlaceholderType.Media, o PlaceholderType.Diagram .
Aspose.Slides no convierte un marcador de posición vacío de IAutoShape en un IChart simplemente cambiando IPlaceholder.getType ; el tipo no puede modificarse a través de la interfaz. Para rellenar programáticamente un área de gráfico o contenido vacía, añada el objeto necesario en las coordenadas del marcador de posición y luego elimine el marcador de posición vacío. El siguiente ejemplo hace eso para un gráfico:
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();
}
El gráfico añadido es un gráfico local ordinario. Ocupa el área del marcador de posición pero no hereda del marcador de posición del diseño. Utilice los artículos de gestión de gráficos cuando necesite reemplazar sus categorías, series o datos del libro de trabajo.
Ejemplo completo: actualizar contenido de texto o imagen
El siguiente ejemplo de extremo a extremo abre una plantilla, busca en la primera diapositiva un marcador de posición de título o de imagen, comprueba los tipos de marcador de posición y de forma, actualiza el contenido correspondiente y guarda el resultado. El ejemplo evita deliberadamente asumir un índice de forma o convertir cada marcador de posición a la misma interfaz.
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();
}
Preguntas frecuentes
¿Qué es un marcador de posición base?
Un marcador de posición base es la forma correspondiente en el diseño o la maestra de la que otro marcador de posición hereda. Use IShape.getBasePlaceholder para recuperarlo. Una forma local ordinaria devuelve null porque no forma parte de la jerarquía de marcadores de posición.
¿Puedo cambiar todos los títulos de diapositiva editando un marcador de posición de diseño?
Puede cambiar el formato heredado o el texto de sugerencia a través de un diseño, pero el contenido real del título se almacena en las diapositivas normales. Para reemplazar el texto real del título en toda la presentación, itere sobre las diapositivas y actualice cada marcador de posición de título.
¿Cómo gestiono los marcadores de posición de fecha, número de diapositiva, encabezado y pie de página?
Utilice los gestores de encabezado y pie de página en el ámbito de la diapositiva, diseño, maestra, notas o folletos correspondiente. Consulte Gestionar encabezado y pie de página de la presentación para ejemplos completos.