Gestionar marcadores de posición de presentación en JavaScript

De qué trata esta página

Aprenda a inspeccionar y editar marcadores de posición de texto, imagen, gráfico y contenido, y a comprender la herencia de marcadores de posición con Aspose.Slides para Node.js mediante Java.

Visión general

Un marcador de posición es una forma que reserva una posición para un tipo concreto de contenido en una plantilla de presentación. Los ejemplos más habituales son marcadores de título, cuerpo, imagen, gráfico y marcadores de contenido de uso general. A diferencia de una forma ordinaria, un marcador de posición puede heredar su posición, tamaño, formato y otras configuraciones 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 Shape.getPlaceholder. El método devuelve un objeto Placeholder o null para una forma normal. Utilice Placeholder.getType para determinar qué se pretende contener en el marcador de posición.

La clase 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 suele estar representado por un AutoShape.
Un marcador de posición de imagen poblado puede estar representado por un PictureFrame.
Un marcador de posición de gráfico poblado puede estar representado por un Chart.
Un marcador de posición de contenido puede contener varios tipos de contenido. Compruebe tanto Placeholder.getType como la clase de forma en tiempo de ejecución en lugar de asumir que todo marcador de posición es un AutoShape.

Warning

Placeholder.getType describe el papel 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 los miembros específicos de texto, imagen, gráfico, tabla o medios.

Entender 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 posición a nivel de 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 Shape.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 de 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 de la primera diapositiva e informa de sus marcadores de posición base:

const aspose = { slides: require("aspose.slides.via.java") };
const java = require("java");

function getShapeClassName(shape) {
    if (java.instanceOf(shape, "com.aspose.slides.IAutoShape")) {
        return "AutoShape";
    }

    if (java.instanceOf(shape, "com.aspose.slides.IPictureFrame")) {
        return "PictureFrame";
    }

    if (java.instanceOf(shape, "com.aspose.slides.IChart")) {
        return "Chart";
    }

    return "Shape";
}

const presentation = new aspose.slides.Presentation("template.pptx");
try {
    const slides = presentation.getSlides();
    const slide = slides.get_Item(0);
    const shapes = slide.getShapes();

    for (let i = 0; i < shapes.size(); i++) {
        const shape = shapes.get_Item(i);
        const placeholder = shape.getPlaceholder();
        if (placeholder == null) {
            continue;
        }

        const placeholderType = placeholder.getType();
        const shapeClassName = getShapeClassName(shape);
        const slidePlaceholderMessage = "Slide placeholder: " + placeholderType + "; shape class: " + shapeClassName;
        console.log(slidePlaceholderMessage);

        const layoutPlaceholder = shape.getBasePlaceholder();
        if (layoutPlaceholder != null) {
            const layoutPlaceholderInfo = layoutPlaceholder.getPlaceholder();
            const layoutPlaceholderType = layoutPlaceholderInfo == null ? null : layoutPlaceholderInfo.getType();
            const layoutPlaceholderMessage = "  Layout placeholder: " + layoutPlaceholderType;
            console.log(layoutPlaceholderMessage);

            const masterPlaceholder = layoutPlaceholder.getBasePlaceholder();
            if (masterPlaceholder != null) {
                const masterPlaceholderInfo = masterPlaceholder.getPlaceholder();
                const masterPlaceholderType = masterPlaceholderInfo == null ? null : masterPlaceholderInfo.getType();
                const masterPlaceholderMessage = "  Master placeholder: " + masterPlaceholderType;
                console.log(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 el maestro relacionado puede afectar a todas las diapositivas que todavía heredan esa configuración. Una forma ordinaria local no tiene marcador de posición base y no comienza a heredar solo porque ocupe las mismas coordenadas.

Eliminar el estado de marcador de posición

Al adaptar una plantilla, utilice Shape.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, ShapeCollection.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 observar el efecto de eliminar esa relación. El ejemplo verifica que la misma forma permanece, vuelve a llamar al método sobre la forma ya ordinaria y guarda el resultado.

Warning

Eliminar el estado de marcador de posición no preserva automáticamente los ajustes de apariencia heredados. El ejemplo siguiente deja deliberadamente esos ajustes sin cambios, por lo que la salida puede parecer diferente. Una forma cuya posición y tamaño se heredan completamente puede terminar con coordenadas y dimensiones cero tras la llamada y quedar invisible aunque siga en la colección.

const aspose = { slides: require("aspose.slides.via.java") };
const java = require("java");

const presentation = new aspose.slides.Presentation("template.pptx");
try {
    const slide = presentation.getSlides().get_Item(0);
    const shapes = slide.getShapes();
    let found = false;

    for (let index = 0; index < shapes.size(); index++) {
        const shape = shapes.get_Item(index);
        if (!java.instanceOf(shape, "com.aspose.slides.IAutoShape")) {
            continue;
        }

        const textFrame = shape.getTextFrame();
        if (shape.getPlaceholder() == null || textFrame == null) {
            continue;
        }

        const text = textFrame.getText();
        if (text == null || text.length === 0) {
            continue;
        }

        const shapeCount = shapes.size();
        shape.removePlaceholder();

        console.log("Placeholder removed: " + (shape.getPlaceholder() == null));
        const retainedShape = shapes.get_Item(index);
        console.log("Same shape retained: " + shape.equals(retainedShape));
        console.log("Shape count unchanged: " + (shapes.size() === shapeCount));

        // Llamar al método en una forma ordinaria no tiene efecto.
        shape.removePlaceholder();
        found = true;
        break;
    }

    if (found) {
        presentation.save("placeholder-status-removed.pptx", aspose.slides.SaveFormat.Pptx);
    } else {
        console.log("No nonempty text placeholder was found on the first slide.");
    }
} finally {
    presentation.dispose();
}

Para un marcador de posición coincidente, los tres controles 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 de título heredado puede volver al formato de texto ordinario. Consulte Slide Layout para más información sobre diseños.

Para conservar la apariencia prevista, capture la posición, tamaño y rotación resueltos antes de la llamada y copie los valores de formato efectivo necesarios en variables independientes. Obtenga esos valores mediante PortionFormat.getEffective, ParagraphFormat.getEffective, TextFrameFormat.getEffective, FillFormat.getEffective y LineFormat.getEffective. No confíe únicamente en los objetos de formato efectivo, ya que sus valores de formato de texto pueden cambiar tras eliminar la relación. Aplique explícitamente los valores capturados a la forma ordinaria posteriormente, incluyendo la familia de fuente, tamaño, estilo, color, ajustes de párrafo, ajustes del marco de texto, relleno y línea utilizados por su plantilla.

La geometría de la forma heredada también puede necesitar asignarse explícitamente mediante GeometryShape.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 devolver 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 posición de título, título centrado, subtítulo, cuerpo y texto normalmente admiten texto. Compruebe que se trata de un AutoShape 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:

const aspose = { slides: require("aspose.slides.via.java") };
const java = require("java");

const presentation = new aspose.slides.Presentation("template.pptx");
try {
    const slides = presentation.getSlides();
    const slide = slides.get_Item(0);
    const shapes = slide.getShapes();
    let titleShape = null;

    for (let i = 0; i < shapes.size(); i++) {
        const shape = shapes.get_Item(i);
        if (!java.instanceOf(shape, "com.aspose.slides.IAutoShape")) {
            continue;
        }

        const placeholder = shape.getPlaceholder();
        if (placeholder == null) {
            continue;
        }

        const placeholderType = placeholder.getType();
        if (placeholderType === aspose.slides.PlaceholderType.Title || placeholderType === aspose.slides.PlaceholderType.CenteredTitle) {
            titleShape = shape;
            break;
        }
    }

    if (titleShape == null) {
        throw new Error("The first slide does not contain a title placeholder.");
    }

    titleShape.getTextFrame().setText("Quarterly Business Review");
    presentation.save("title-placeholder-updated.pptx", aspose.slides.SaveFormat.Pptx);
} finally {
    presentation.dispose();
}

Este patrón evita tratar marcadores de posición de imagen, gráfico, tabla o medios como objetos AutoShape. Además identifica el marcador de posición por su finalidad en lugar de depender de 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 el título. Establezca un 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 Slide.getLayoutSlide y recorra la colección devuelta por BaseSlide.getShapes.

El siguiente ejemplo cambia las sugerencias de título y subtítulo en el diseño utilizado por la primera diapositiva:

const aspose = { slides: require("aspose.slides.via.java") };
const java = require("java");

const presentation = new aspose.slides.Presentation("template.pptx");
try {
    const slides = presentation.getSlides();
    const firstSlide = slides.get_Item(0);
    const layoutSlide = firstSlide.getLayoutSlide();
    const shapes = layoutSlide.getShapes();

    for (let i = 0; i < shapes.size(); i++) {
        const shape = shapes.get_Item(i);
        if (!java.instanceOf(shape, "com.aspose.slides.IAutoShape")) {
            continue;
        }

        const placeholder = shape.getPlaceholder();
        if (placeholder == null) {
            continue;
        }

        const placeholderType = placeholder.getType();

        if (placeholderType === aspose.slides.PlaceholderType.Title || placeholderType === aspose.slides.PlaceholderType.CenteredTitle) {
            shape.getTextFrame().setText("Enter a concise slide title");
        } else if (placeholderType === aspose.slides.PlaceholderType.Subtitle) {
            shape.getTextFrame().setText("Enter a subtitle or reporting period");
        }
    }

    presentation.save("custom-placeholder-prompts.pptx", aspose.slides.SaveFormat.Pptx);
} finally {
    presentation.dispose();
}

El texto de sugerencia no es contenido normal de la diapositiva. Está destinado a los 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 ya no se muestra. Cambiar una sugerencia tampoco sustituye el texto existente en las diapositivas que utilizan el diseño.

Actualizar un marcador de posición de imagen

Hay dos casos a gestionar:

Si el marcador de posición de imagen ya está poblado y representado por un PictureFrame, reemplace la imagen mediante PictureFrame.getPictureFormat, PictureFillFormat.getPicture y Picture.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 ShapeCollection.addPictureFrame y elimine el marcador de posición vacío.

El siguiente ejemplo admite ambos casos y guarda la presentación:

const aspose = { slides: require("aspose.slides.via.java") };
const java = require("java");

const presentation = new aspose.slides.Presentation("picture-template.pptx");
try {
    const slides = presentation.getSlides();
    const slide = slides.get_Item(0);
    const shapes = slide.getShapes();
    let picturePlaceholder = null;

    for (let i = 0; i < shapes.size(); i++) {
        const shape = shapes.get_Item(i);
        const placeholder = shape.getPlaceholder();
        if (placeholder != null && placeholder.getType() === aspose.slides.PlaceholderType.Picture) {
            picturePlaceholder = shape;
            break;
        }
    }

    if (picturePlaceholder == null) {
        throw new Error("The first slide does not contain a picture placeholder.");
    }

    const sourceImage = aspose.slides.Images.fromFile("replacement.png");
    try {
        const image = presentation.getImages().addImage(sourceImage);

        if (java.instanceOf(picturePlaceholder, "com.aspose.slides.IPictureFrame")) {
            picturePlaceholder.getPictureFormat().getPicture().setImage(image);
        } else {
            const x = picturePlaceholder.getX();
            const y = picturePlaceholder.getY();
            const width = picturePlaceholder.getWidth();
            const height = picturePlaceholder.getHeight();
            const frameX = java.newFloat(x);
            const frameY = java.newFloat(y);
            const frameWidth = java.newFloat(width);
            const frameHeight = java.newFloat(height);
            shapes.addPictureFrame(aspose.slides.ShapeType.Rectangle, frameX, frameY, frameWidth, frameHeight, image);
            shapes.remove(picturePlaceholder);
        }
    } finally {
        sourceImage.dispose();
    }

    presentation.save("picture-placeholder-updated.pptx", aspose.slides.SaveFormat.Pptx);
} finally {
    presentation.dispose();
}

El reemplazo creado para un marcador de posición vacío es un marco de imagen local, no un nuevo marcador de posición, porque Shape.getPlaceholder no ofrece un setter. Mantiene la posición reservada pero ya no hereda el comportamiento específico del marcador de posición. Si conservar la relación del marcador de posición es esencial, prepare y rellene el marcador de posición en PowerPoint primero, y luego actualice el PictureFrame resultante con Aspose.Slides.

Para la transparencia de la imagen, recorte y otros efectos específicos de la imagen, consulte Manage Picture Frames. 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 estar representado por un Chart. Este ejemplo encuentra dicho gráfico tanto por tipo de marcador de posición como por clase en tiempo de ejecución, cambia su título y guarda el archivo:

const aspose = { slides: require("aspose.slides.via.java") };
const java = require("java");

const presentation = new aspose.slides.Presentation("chart-template.pptx");
try {
    const slides = presentation.getSlides();
    const slide = slides.get_Item(0);
    const shapes = slide.getShapes();
    let placeholderChart = null;

    for (let i = 0; i < shapes.size(); i++) {
        const shape = shapes.get_Item(i);
        if (!java.instanceOf(shape, "com.aspose.slides.IChart")) {
            continue;
        }

        const placeholder = shape.getPlaceholder();
        if (placeholder != null && placeholder.getType() === aspose.slides.PlaceholderType.Chart) {
            placeholderChart = shape;
            break;
        }
    }

    if (placeholderChart == null) {
        throw new Error("The first slide does not contain a populated chart placeholder.");
    }

    placeholderChart.setTitle(true);
    placeholderChart.getChartTitle().addTextFrameForOverriding("Quarterly Revenue");
    presentation.save("chart-placeholder-updated.pptx", aspose.slides.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. Tras poblarlo, inspeccione la clase real de la forma 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 AutoShape vacío en un Chart simplemente cambiando Placeholder.getType; el tipo no puede modificarse mediante el objeto. Para rellenar programáticamente un gráfico o área de contenido vacío, añada el objeto requerido 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:

const aspose = { slides: require("aspose.slides.via.java") };
const java = require("java");

const presentation = new aspose.slides.Presentation("content-template.pptx");
try {
    const slides = presentation.getSlides();
    const slide = slides.get_Item(0);
    const shapes = slide.getShapes();
    let targetPlaceholder = null;

    for (let i = 0; i < shapes.size(); i++) {
        const shape = shapes.get_Item(i);
        const placeholder = shape.getPlaceholder();
        if (placeholder == null) {
            continue;
        }

        const placeholderType = placeholder.getType();
        if (placeholderType === aspose.slides.PlaceholderType.Chart || placeholderType === aspose.slides.PlaceholderType.Object) {
            targetPlaceholder = shape;
            break;
        }
    }

    if (targetPlaceholder == null) {
        throw new Error("The first slide does not contain a chart or content placeholder.");
    }

    const x = targetPlaceholder.getX();
    const y = targetPlaceholder.getY();
    const width = targetPlaceholder.getWidth();
    const height = targetPlaceholder.getHeight();
    const chartX = java.newFloat(x);
    const chartY = java.newFloat(y);
    const chartWidth = java.newFloat(width);
    const chartHeight = java.newFloat(height);
    const chart = shapes.addChart(aspose.slides.ChartType.ClusteredColumn, chartX, chartY, chartWidth, chartHeight);
    chart.setTitle(true);
    chart.getChartTitle().addTextFrameForOverriding("Quarterly Revenue");
    shapes.remove(targetPlaceholder);
    presentation.save("content-placeholder-replaced-with-chart.pptx", aspose.slides.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 dedicados a la gestión de gráficos chart management articles cuando necesite sustituir 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 suponer un índice de forma o tratar todos los marcadores de posición como la misma clase.

const aspose = { slides: require("aspose.slides.via.java") };
const java = require("java");

const presentation = new aspose.slides.Presentation("template.pptx");
try {
    const slides = presentation.getSlides();
    const slide = slides.get_Item(0);
    const shapes = slide.getShapes();
    let updated = false;

    for (let i = 0; i < shapes.size(); i++) {
        const shape = shapes.get_Item(i);
        const placeholder = shape.getPlaceholder();
        if (placeholder == null) {
            continue;
        }

        const placeholderType = placeholder.getType();
        const isTitlePlaceholder = placeholderType === aspose.slides.PlaceholderType.Title || placeholderType === aspose.slides.PlaceholderType.CenteredTitle;

        if (isTitlePlaceholder && java.instanceOf(shape, "com.aspose.slides.IAutoShape")) {
            shape.getTextFrame().setText("Quarterly Business Review");
            updated = true;
            break;
        }

        if (placeholderType === aspose.slides.PlaceholderType.Picture) {
            const sourceImage = aspose.slides.Images.fromFile("replacement.png");
            try {
                const image = presentation.getImages().addImage(sourceImage);

                if (java.instanceOf(shape, "com.aspose.slides.IPictureFrame")) {
                    shape.getPictureFormat().getPicture().setImage(image);
                } else {
                    const x = shape.getX();
                    const y = shape.getY();
                    const width = shape.getWidth();
                    const height = shape.getHeight();
                    const frameX = java.newFloat(x);
                    const frameY = java.newFloat(y);
                    const frameWidth = java.newFloat(width);
                    const frameHeight = java.newFloat(height);
                    shapes.addPictureFrame(aspose.slides.ShapeType.Rectangle, frameX, frameY, frameWidth, frameHeight, image);
                    shapes.remove(shape);
                }
            } finally {
                sourceImage.dispose();
            }

            updated = true;
            break;
        }
    }

    if (!updated) {
        throw new Error("No supported title or picture placeholder was found on the first slide.");
    }

    presentation.save("placeholder-content-updated.pptx", aspose.slides.SaveFormat.Pptx);
} finally {
    presentation.dispose();
}

FAQ

¿Qué es un marcador de posición base?

Un marcador de posición base es la forma correspondiente en el diseño o maestro de la que otro marcador de posición hereda. Utilice Shape.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 mediante un diseño, pero el contenido real del título se almacena en las diapositivas normales. Para sustituir el texto del título en toda la presentación, recorra 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, maestro, notas o folleto correspondiente. Consulte Manage Presentation Header and Footer para ejemplos completos.

Visor de presentaciones