Trabajar con formas mediante la API de JavaScript de PowerPoint

En este artículo se describe cómo usar formas geométricas, líneas y cuadros de texto junto con las API Shape y ShapeCollection .

Crear formas

Las formas se crean y almacenan en la colección de formas de una diapositiva (slide.shapes). ShapeCollection tiene varios .add* métodos para este propósito. Todas las formas tienen nombres e identificadores generados para ellas cuando se agregan a la colección. Estas son las name propiedades y id , respectivamente. name puede establecerlo el complemento.

Formas geométricas

Se crea una forma geométrica con una de las sobrecargas de ShapeCollection.addGeometricShape. El primer parámetro es una enumeración GeometricShapeType o la cadena equivalente a uno de los valores de la enumeración. Hay un segundo parámetro opcional de tipo ShapeAddOptions que puede especificar el tamaño inicial de la forma y su posición en relación con los lados superior e izquierdo de la diapositiva, medidos en puntos. O bien, estas propiedades se pueden establecer después de crear la forma.

En el ejemplo de código siguiente se crea un rectángulo denominado "Cuadrado" que se coloca a 100 puntos de los lados superior e izquierdo de la diapositiva. El método devuelve un Shape objeto .

// This sample creates a rectangle positioned 100 points from the top and left sides
// of the slide and is 150x150 points. The shape is put on the first slide.
await PowerPoint.run(async (context) => {
    const shapes = context.presentation.slides.getItemAt(0).shapes;
    const rectangle = shapes.addGeometricShape(PowerPoint.GeometricShapeType.rectangle);
    rectangle.left = 100;
    rectangle.top = 100;
    rectangle.height = 150;
    rectangle.width = 150;
    rectangle.name = "Square";
    await context.sync();
});

Lines

Se crea una línea con una de las sobrecargas de ShapeCollection.addLine. El primer parámetro es una enumeración ConnectorType o la cadena equivalente a uno de los valores de la enumeración para especificar cómo la línea contorsiona entre los puntos de conexión. Hay un segundo parámetro opcional de tipo ShapeAddOptions que puede especificar los puntos inicial y final de la línea. O bien, estas propiedades se pueden establecer después de crear la forma. El método devuelve un Shape objeto .

Nota:

Cuando la forma es una línea, las top propiedades y left de los Shape objetos y ShapeAddOptions especifican el punto inicial de la línea en relación con los bordes superior e izquierdo de la diapositiva. Las height propiedades y width especifican el punto de conexión de la línea en relación con el punto inicial. Por lo tanto, el punto final relativo a los bordes superior e izquierdo de la diapositiva es (top + height) por ().left + width La unidad de medida de todas las propiedades es de puntos y se permiten valores negativos.

En el ejemplo de código siguiente se crea una línea recta en la diapositiva.

// This sample creates a straight line on the first slide.
await PowerPoint.run(async (context) => {
    const shapes = context.presentation.slides.getItemAt(0).shapes;
    const line = shapes.addLine(PowerPoint.ConnectorType.straight, {left: 200, top: 50, height: 300, width: 150});
    line.name = "StraightLine";
    await context.sync();
});

Cuadros de texto

Se crea un cuadro de texto con el método addTextBox . El primer parámetro es el texto que debe aparecer en el cuadro inicialmente. Hay un segundo parámetro opcional de tipo ShapeAddOptions que puede especificar el tamaño inicial del cuadro de texto y su posición en relación con los lados superior e izquierdo de la diapositiva. O bien, estas propiedades se pueden establecer después de crear la forma.

En el ejemplo de código siguiente se muestra cómo crear un cuadro de texto en la primera diapositiva.

// This sample creates a text box with the text "Hello!" and sizes it appropriately.
await PowerPoint.run(async (context) => {
    const shapes = context.presentation.slides.getItemAt(0).shapes;
    const textbox = shapes.addTextBox("Hello!");
    textbox.left = 100;
    textbox.top = 100;
    textbox.height = 300;
    textbox.width = 450;
    textbox.name = "Textbox";
    await context.sync();
});

Mover y cambiar el tamaño de las formas

Las formas se colocan encima de la diapositiva. Su ubicación se define mediante las left propiedades y top . Estos actúan como márgenes de los bordes respectivos de la diapositiva, medidos en puntos, con left: 0 y top: 0 siendo la esquina superior izquierda. El tamaño de la forma se especifica mediante las height propiedades y width . El código puede mover o cambiar el tamaño de la forma restableciendo estas propiedades. (Estas propiedades tienen un significado ligeramente diferente cuando la forma es una línea. Vea Líneas).

Texto en formas

Las formas geométricas pueden contener texto. Las formas tienen una textFrame propiedad de tipo TextFrame. El TextFrame objeto administra las opciones de visualización de texto (como márgenes y desbordamiento de texto). TextFrame.textRange es un objeto TextRange con la configuración de contenido de texto y fuente.

En el ejemplo de código siguiente se crea una forma geométrica denominada "Llaves" con el texto "Texto de forma". También ajusta la forma y los colores del texto, así como establece la alineación vertical del texto en el centro.

// This sample creates a light blue rectangle with braces ("{}") on the left and right ends
// and adds the purple text "Shape text" to the center.
await PowerPoint.run(async (context) => {
    const shapes = context.presentation.slides.getItemAt(0).shapes;
    const braces = shapes.addGeometricShape(PowerPoint.GeometricShapeType.bracePair);
    braces.left = 100;
    braces.top = 400;
    braces.height = 50;
    braces.width = 150;
    braces.name = "Braces";
    braces.fill.setSolidColor("lightblue");
    braces.textFrame.textRange.text = "Shape text";
    braces.textFrame.textRange.font.color = "purple";
    braces.textFrame.verticalAlignment = PowerPoint.TextVerticalAlignment.middleCentered;
    await context.sync();
});

Eliminar formas

Las formas se quitan de la diapositiva con el Shape método del delete objeto.

En el ejemplo de código siguiente se muestra cómo eliminar formas.

await PowerPoint.run(async (context) => {
    // Delete all shapes from the first slide.
    const shapes = context.presentation.slides.getItemAt(0).shapes;

    // Load all the shapes in the collection without loading their properties.
    shapes.load("items/$none");
    await context.sync();
        
    shapes.items.forEach(function (shape) {
        shape.delete();
    });
    await context.sync();
});