Trabajar con tablas mediante la API de JavaScript de PowerPoint

En este artículo se proporcionan ejemplos de código que muestran cómo crear tablas y controlar el formato mediante la API de JavaScript de PowerPoint.

Creación de una tabla vacía

Para crear una tabla vacía, llame al método ShapeCollection.addTable() y especifique cuántas filas y columnas necesita la tabla. En el ejemplo de código siguiente se muestra cómo crear una tabla con 3 filas y 4 columnas.

await PowerPoint.run(async (context) => {
    const shapes = context.presentation.getSelectedSlides().getItemAt(0).shapes;

    // Add a table (which is a type of Shape).
    const shape = shapes.addTable(3, 4);
    await context.sync();
});

El ejemplo anterior no especifica ninguna opción, por lo que la tabla tiene como valor predeterminado el formato proporcionado por PowerPoint. En la imagen siguiente se muestra un ejemplo de una tabla vacía creada con formato predeterminado en PowerPoint.

Especificar valores

Puede rellenar la tabla con valores de cadena al crearla. Para ello, proporcione una matriz 2 dimensiones de valores en el objeto TableAddOptions . En el ejemplo de código siguiente se crea una tabla con valores de cadena de "1" a "12". Tenga en cuenta lo siguiente:

• Una celda vacía debe especificarse como una cadena vacía "". Si un valor no está definido o falta, addTable se produce un error.
• La matriz externa contiene una lista de filas. Cada fila es una matriz interna que contiene una lista de valores de celda de cadena.
• La función denominada insertTableOnCurrentSlide se usa en otros ejemplos de este artículo.

async function run() {
    const options: PowerPoint.TableAddOptions = {
        values: [
            ["1", "2", "", "4"], // Cell 3 is blank.
            ["5", "6", "7", "8"],
            ["9", "10", "11", "12"]
        ],
    };

    await insertTableOnCurrentSlide(3, 4, options);
}

async function insertTableOnCurrentSlide(rowCount: number, columnCount: number, options: PowerPoint.TableAddOptions) {
    await PowerPoint.run(async (context) => {
        const shapes = context.presentation.getSelectedSlides().getItemAt(0).shapes;

        // Add a table (which is a type of Shape).
        const shape = shapes.addTable(rowCount, columnCount, options);
        await context.sync();
    });
}

En el ejemplo anterior se crea una tabla con valores como se muestra en la siguiente imagen.

Especificar el formato de celda

Puede especificar el formato de celda al crear una tabla, incluido el estilo de borde, el estilo de relleno, el estilo de fuente, la alineación horizontal, el nivel de sangría y la alineación vertical. El objeto TableCellProperties especifica estos formatos.

Formato uniforme de celda

El formato uniforme de celda se aplica a toda la tabla. Por ejemplo, si establece el color de fuente uniforme en blanco, todas las celdas de tabla usarán la fuente blanca. El formato uniforme de celda es útil para controlar el formato predeterminado que desea en toda la tabla.

Especifique el formato de celda uniforme para toda la tabla mediante la propiedad TableAddOptions.uniformCellProperties . En el ejemplo de código siguiente se muestra cómo establecer todas las celdas de tabla en color de relleno azul pizarra oscuro y fuente blanca en negrita.

const rowCount = 3;
const columnCount = 4;
const options: PowerPoint.TableAddOptions = {
    values: [
        ["1", "2", "", "4"],
        ["5", "6", "7", "8"],
        ["9", "10", "11", "12"]
    ],
    uniformCellProperties: {
        fill: { color: "darkslateblue" },
        font: { bold: true, color: "white" }
    }
};
await insertTableOnCurrentSlide(rowCount, columnCount, options);

En el ejemplo anterior se crea una tabla como se muestra en la siguiente imagen.

Formato de celda específico

El formato de celda específico se aplica a celdas individuales e invalida el formato uniforme de celda, si existe. Establezca el formato de celda individual mediante la propiedad TableAddOptions.specificCellProperties . En el ejemplo de código siguiente se muestra cómo establecer el color de relleno en negro para la celda de la fila 1, columna 1.

Tenga en cuenta que specificCellProperties debe ser una matriz 2D que coincida exactamente con el tamaño 2D de la tabla. En primer lugar, el ejemplo crea toda la matriz 2D vacía de objetos. A continuación, establece el formato de celda específico en la fila 1, columna 1, después de crear el objeto options.

const rowCount = 3;
const columnCount = 4;
// Compact syntax to create a 2D array filled with empty and distinct objects.
const specificCellProperties = Array(rowCount).fill("").map(_ => Array(columnCount).fill("").map(_ => ({})));
const options: PowerPoint.TableAddOptions = {
    values: [
        ["1", "2", "", "4"],
        ["5", "6", "7", "8"],
        ["9", "10", "11", "12"]
    ],
    uniformCellProperties: {
        fill: { color: "darkslateblue" },
        font: { bold: true, color: "white" }
    },
    specificCellProperties // Array values are empty objects at this point.
};
// Set fill color for specific cell at row 1, column 1.
options.specificCellProperties[1][1] = {
    fill: { color: "black" }
};
await insertTableOnCurrentSlide(rowCount, columnCount, options);

En el ejemplo anterior se crea una tabla con un formato específico aplicado a la celda de la fila 1, columna 1, como se muestra en la siguiente imagen.

En el ejemplo anterior se usa la propiedad font que es de tipo FontProperties. La font propiedad permite especificar muchas propiedades, como negrita, cursiva, nombre, color, etc. En el ejemplo de código siguiente se muestra cómo especificar varias propiedades para una fuente para una celda.

options.specificCellProperties[1][1] = {
    font: {
        color: "orange",
        name: "Arial",
        size: 50,
        allCaps: true,
        italic: true
    }
};

También puede especificar una propiedad fill que sea de tipo FillProperties. La fill propiedad puede especificar un color y el porcentaje de transparencia. En el ejemplo de código siguiente se muestra cómo crear un relleno para todas las celdas de tabla con el color "rojo oscuro" y una transparencia del 50 %.

uniformCellProperties: {
    fill: {
        color: "darkred",
        transparency: 0.5
    }
}

Borders

Utilice el objeto TableCellProperties.borders para definir bordes para las celdas de la tabla. En el ejemplo de código siguiente se muestra cómo establecer los bordes de una celda de la fila 1 por la columna 1 en un borde rojo con peso 3.

const columnCount = 3;
const rowCount = 3;
// Compact syntax to create a 2D array filled with empty and distinct objects.
const specificCellProperties = Array(rowCount).fill(undefined).map(_ => Array(columnCount).fill(undefined).map(_ => ({})));
const options: PowerPoint.TableAddOptions = {
    values: [
        ["1", "2", "3"],
        ["4", "5", "6"],
        ["7", "8", "9"]
    ],
    uniformCellProperties: {
        fill: {
            color: "lightcyan",
            transparency: 0.5
        },
    },
    specificCellProperties
};
options.specificCellProperties[1][1] = {
    font: {
        color: "red",
        name: "Arial",
        size: 50,
        allCaps: true,
        italic: true
    },
    borders: {
        bottom: {
            color: "red",
            weight: 3
        },
        left: {
            color: "red",
            weight: 3
        },
        right: {
            color: "red",
            weight: 3
        },
        top: {
            color: "red",
            weight: 3
        }
    }
};
await insertTableOnCurrentSlide(rowCount, columnCount, options);

Alineación horizontal y vertical

Utilice la propiedad TableCellProperties.horizontalAlignment para controlar la alineación del texto en una celda. En el ejemplo siguiente se muestra cómo establecer la alineación horizontal en izquierda, derecha y centro para tres celdas de una tabla. Para obtener una lista de todas las opciones de alineación, vea la enumeración ParagraphHorizontalAlignment .

const rowCount = 3;
const columnCount = 3;
// Compact syntax to create a 2D array filled with empty and distinct objects.
const specificCellProperties = Array(rowCount).fill("").map(_ => Array(columnCount).fill("").map(_ => ({})));
const options: PowerPoint.TableAddOptions = {
    values: [
        ["Left aligned, top", "\n\n", ""],
        ["Centered", "\n\n", ""],
        ["Right aligned, bottom", "\n\n", ""]
    ],
    uniformCellProperties: {
        fill: { color: "lightblue" },
        borders: {
            bottom: {
                color: "black",
                weight: 3
            },
            left: {
                color: "black",
                weight: 3
            },
            right: {
                color: "black",
                weight: 3
            },
            top: {
                color: "black",
                weight: 3
            }
        }
    },
    specificCellProperties // Array values are empty objects at this point.
};
options.specificCellProperties[0][0] = {
    horizontalAlignment: PowerPoint.ParagraphHorizontalAlignment.left,
    verticalAlignment: PowerPoint.TextVerticalAlignment.top
};
options.specificCellProperties[1][0] = {
    horizontalAlignment: PowerPoint.ParagraphHorizontalAlignment.center,
    verticalAlignment: PowerPoint.TextVerticalAlignment.middle
};
options.specificCellProperties[2][0] = {
    horizontalAlignment: PowerPoint.ParagraphHorizontalAlignment.right,
    verticalAlignment: PowerPoint.TextVerticalAlignment.bottom
};
await insertTableOnCurrentSlide(3, 3, options);

En el ejemplo anterior se crea una tabla con alineación de texto izquierda/superior, centrada y derecha/inferior, como se muestra en la siguiente imagen.

Especificar anchos de fila y columna

Especifique los anchos de fila y columna mediante las propiedades TableAddOptions.rows y TableAddOptions.columns . La rows propiedad es una matriz de TableRowProperties que se usa para establecer la propiedad rowHeight de cada fila. De forma similar, la columns propiedad es una matriz de TableColumnProperties que se usa para establecer la propiedad columnWidth de cada columna. El ancho o el alto se establecen en puntos.

Es posible que PowerPoint no respete el alto o el ancho establecidos si necesita ajustarse al texto. Por ejemplo, si el texto es demasiado ancho para una columna, PowerPoint aumentará el alto de fila para que pueda ajustar el texto a la siguiente línea. De forma similar, el ancho de columna aumentará si el tamaño especificado es menor que un solo carácter en el tamaño de fuente especificado.

En el ejemplo de código siguiente se muestra cómo establecer el alto de fila y el ancho de columna para una nueva tabla. Tenga en cuenta que las propiedades de filas y columnas deben establecerse en una matriz de objetos igual a su recuento.

const columnCount = 3;
const rowCount = 3;
const options: PowerPoint.TableAddOptions = {
    values: [
        ["Width 72pt", "Width 244pt", "Width 100pt"],
        ["", "", ""],
        ["", "^\n\nHeight 200 pt\n\nv", ""]
    ],
    // Initialize columns with an array of empty objects for each column.
    columns: Array(columnCount).fill("").map(_ => ({})),
    rows: Array(columnCount).fill("").map(_ => ({})),
    uniformCellProperties: {
        fill: { color: "lightcyan" },
        horizontalAlignment: PowerPoint.ParagraphHorizontalAlignment.center,
        verticalAlignment: PowerPoint.TextVerticalAlignment.middle,
        borders: {
            bottom: {
                color: "black",
                weight: 3
            },
            left: {
                color: "black",
                weight: 3
            },
            right: {
                color: "black",
                weight: 3
            },
            top: {
                color: "black",
                weight: 3
            }
        }
    }
};
options.columns[0].columnWidth = 72;
options.columns[1].columnWidth = 244;
options.columns[2].columnWidth = 100;
options.rows[2].rowHeight = 200;
await insertTableOnCurrentSlide(rowCount, columnCount, options);

En el ejemplo anterior se crea una tabla con tres anchos de columna personalizados y un alto de fila personalizado, como se muestra en la siguiente imagen.

Especificar áreas combinadas

Un área combinada es dos o más celdas combinadas para que compartan un único valor y formato. En apariencia, el área combinada abarca varias filas o columnas. Un área combinada se indexa por su ubicación de celda de la tabla superior izquierda (fila, columna) al establecer su valor o formato. La celda superior izquierda del área combinada siempre se usa para establecer el valor y el formato. Todas las demás celdas del área combinada deben ser cadenas vacías sin aplicar ningún formato.

Para especificar un área combinada, proporcione la ubicación superior izquierda donde se inicia el área (fila, columna) y la longitud del área en filas y columnas. En el diagrama siguiente se muestra un ejemplo de estos valores para un área combinada que tiene un tamaño de 3 filas por 2 columnas. Tenga en cuenta que las áreas combinadas no se pueden superponer entre sí.

Utilice la propiedad TableAddOptions.mergedAreas para especificar una o varias áreas combinadas. En el ejemplo de código siguiente se muestra cómo crear una tabla con dos áreas combinadas. Sobre el ejemplo de código, tenga en cuenta lo siguiente:

• La propiedad values solo debe especificar el valor de la esquina superior izquierda del área combinada. Todos los demás valores de celda del área combinada deben especificar cadenas vacías ("").

• Cada área combinada debe especificar la ubicación de la esquina superior izquierda (fila, columna) y la longitud en las celdas del área combinada en términos de recuento de filas y recuento de columnas.

const rowCount = 3;
const columnCount = 4;
// Compact syntax to create a 2D array filled with empty and distinct objects.
const specificCellProperties = Array(rowCount).fill("").map(_ => Array(columnCount).fill("").map(_ => ({})));
const options: PowerPoint.TableAddOptions = {
    values: [
        ["1", "This is a merged cell", "", "4"],
        ["5", "6", "This is also a merged cell", "8"],
        ["9", "10", "", "12"]
    ],
    uniformCellProperties: {
        fill: { color: "darkslateblue" },
        font: { bold: true, color: "white" },
        borders: {
            bottom: {
                color: "black",
                weight: 3
            },
            left: {
                color: "black",
                weight: 3
            },
            right: {
                color: "black",
                weight: 3
            },
            top: {
                color: "black",
                weight: 3
            }
        }
    },
    mergedAreas: [{ rowIndex: 0, columnIndex: 1, rowCount: 1, columnCount: 2 },
    { rowIndex: 1, columnIndex: 2, rowCount: 2, columnCount: 1 }
    ],
    specificCellProperties // Array values are empty objects at this point.
};
// Set fill color for specific cell at row 1, column 1.
options.specificCellProperties[1][1] = {
    fill: { color: "black" }
};
await insertTableOnCurrentSlide(rowCount, columnCount, options);

En el ejemplo anterior se crea una tabla con dos áreas combinadas, como se muestra en la siguiente imagen.

Obtener y establecer valores de celda de tabla

Después de crear una tabla, puede obtener o establecer valores de cadena en las celdas. Tenga en cuenta que esta es la única parte de una tabla que puede cambiar. No se pueden cambiar bordes, fuentes, anchos u otras propiedades de celda. Si necesita actualizar una tabla, elimínela y vuelva a crearla. En el ejemplo de código siguiente se muestra cómo buscar una tabla existente y establecer un nuevo valor para una celda de la tabla.

await PowerPoint.run(async (context) => {
    // Load shapes.
    const shapes = context.presentation.getSelectedSlides().getItemAt(0).shapes;
    shapes.load("items");
    await context.sync();
    // Find the first shape of type table.
    const shape = shapes.items.find((shape) => shape.type === PowerPoint.ShapeType.table)
    const table = shape.getTable();
    table.load();
    await context.sync();
    // Set the value of the specified table cell.
    const cell = table.getCellOrNullObject(1, 1);
    cell.text = "A new value";
});

También puede obtener las siguientes propiedades de solo lectura de la tabla.

• rowCount
• columnCount

En el ejemplo siguiente se muestra cómo obtener las propiedades de la tabla y registrarlas en la consola. En el ejemplo también se muestra cómo obtener las áreas combinadas de la tabla.

await PowerPoint.run(async (context) => {
    // Load shapes.
    const shapes = context.presentation.getSelectedSlides().getItemAt(0).shapes;
    shapes.load("items");
    await context.sync();
    // Find the first shape of type table.
    const shape = shapes.items.find((shape) => shape.type === PowerPoint.ShapeType.table)
    const table = shape.getTable();
    // Load row and column counts.
    table.load("rowCount, columnCount");
    // Load the merged areas.
    const mergedAreas = table.getMergedAreas();
    mergedAreas.load("items");
    await context.sync();
    // Log the table properties.
    console.log(mergedAreas);
    console.log(table.rowCount);
    console.log(table.columnCount);
});