Trabalhar com tabelas com a API JavaScript do PowerPoint

Este artigo fornece exemplos de código que mostram como criar tabelas e controlar a formatação com a API JavaScript do PowerPoint.

Criar uma tabela vazia

Para criar uma tabela vazia, chame o método ShapeCollection.addTable() e especifique quantas linhas e colunas a tabela precisa. O seguinte exemplo de código mostra como criar uma tabela com 3 linhas e 4 colunas.

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();
});

O exemplo anterior não especifica nenhuma opção, pelo que a tabela é predefinida para formatação fornecida pelo PowerPoint. A imagem seguinte mostra um exemplo de uma tabela vazia criada com formatação predefinida no PowerPoint.

Especificar valores

Pode preencher a tabela com valores de cadeia quando a criar. Para tal, forneça uma matriz bidimensional de valores no objeto TableAddOptions . O seguinte exemplo de código cria uma tabela com valores de cadeia de carateres de "1" a "12". Observe o seguinte:

• Uma célula vazia tem de ser especificada como uma cadeia vazia "". Se um valor estiver indefinido ou em falta, addTable será apresentado um erro.
• A matriz externa contém uma lista de linhas. Cada linha é uma matriz interna que contém uma lista de valores de células de cadeia.
• A função com o nome insertTableOnCurrentSlide é utilizada noutros exemplos neste artigo.

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();
    });
}

O exemplo anterior cria uma tabela com valores, conforme mostrado na imagem seguinte.

Especificar formatação de células

Pode especificar a formatação de células quando cria uma tabela, incluindo estilo de limite, estilo de preenchimento, estilo do tipo de letra, alinhamento horizontal, nível de avanço e alinhamento vertical. Estes formatos são especificados pelo objeto TableCellProperties .

Formatação uniforme de células

A formatação uniforme de células aplica-se a toda a tabela. Por exemplo, se definir a cor do tipo de letra uniforme para branco, todas as células da tabela utilizarão o tipo de letra branco. A formatação uniforme de células é útil para controlar a formatação predefinida pretendida em toda a tabela.

Especifique a formatação uniforme de células para toda a tabela com a propriedade TableAddOptions.uniformCellProperties . O seguinte exemplo de código mostra como definir todas as células da tabela como cor de preenchimento azul ardósia escuro e tipo de letra branco a negrito.

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);

O exemplo anterior cria uma tabela, conforme mostrado na imagem seguinte.

Formatação de células específica

A formatação específica de células aplica-se a células individuais e substitui a formatação uniforme de células, se existir. Defina a formatação de células individuais com a propriedade TableAddOptions.specificCellProperties . O seguinte exemplo de código mostra como definir a cor de preenchimento para preto para a célula na linha 1, coluna 1.

Tenha em atenção que tem specificCellProperties de ser uma matriz 2D que corresponda exatamente ao tamanho 2D da tabela. O exemplo cria primeiro toda a matriz 2D vazia de objetos. Em seguida, define o formato de célula específico na linha 1, coluna 1, após a criação do objeto de opções.

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);

O exemplo anterior cria uma tabela com um formato específico aplicado à célula na linha 1, coluna 1, conforme mostrado na imagem seguinte.

O exemplo anterior utiliza a propriedade tipo de letra que é do tipo FontProperties. A font propriedade permite-lhe especificar muitas propriedades, como negrito, itálico, nome, cor e muito mais. O seguinte exemplo de código mostra como especificar várias propriedades para um tipo de letra para uma célula.

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

Também pode especificar uma propriedade de preenchimento do tipo FillProperties. A fill propriedade pode especificar uma cor e a percentagem de transparência. O seguinte exemplo de código mostra como criar um preenchimento para todas as células da tabela com a cor "vermelho escuro" e uma transparência de 50%.

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

Bordas

Utilize o objeto TableCellProperties.borders para definir limites para células na tabela. O seguinte exemplo de código mostra como definir os limites de uma célula na linha 1 pela coluna 1 para um limite vermelho com 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);

Alinhamento horizontal e vertical

Utilize a propriedade TableCellProperties.horizontalAlignment para controlar o alinhamento do texto numa célula. O exemplo seguinte mostra como definir o alinhamento horizontal para a esquerda, direita e centro para três células numa tabela. Para obter uma lista de todas as opções de alinhamento, consulte a enumeração 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);

O exemplo anterior cria uma tabela com alinhamento de texto à esquerda/superior, centrado e à direita/inferior, conforme mostrado na imagem seguinte.

Especificar larguras de linhas e colunas

Especifique as larguras das linhas e colunas com as propriedades TableAddOptions.rows e TableAddOptions.columns . A rows propriedade é uma matriz de TableRowProperties que utiliza para definir a propriedade rowHeight de cada linha. Da mesma forma, a columns propriedade é uma matriz de TableColumnProperties que utiliza para definir a propriedade columnWidth de cada coluna. A largura ou altura é definida em pontos.

A altura ou largura definida pelo PowerPoint poderá não ser respeitada se precisar de ajustar o texto. Por exemplo, se o texto for demasiado largo para uma coluna, o PowerPoint aumentará a altura da linha para que possa moldar o texto para a linha seguinte. Da mesma forma, a largura da coluna aumentará se o tamanho especificado for inferior a um único caráter no tamanho do tipo de letra especificado.

O seguinte exemplo de código mostra como definir a altura da linha e a largura da coluna para uma nova tabela. Tenha em atenção que as propriedades de linhas e colunas têm de ser definidas para uma matriz de objetos igual à respetiva contagem.

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);

O exemplo anterior cria uma tabela com três larguras de coluna personalizadas e uma altura de linha personalizada, conforme mostrado na imagem seguinte.

Especificar áreas unidas

Uma área unida é duas ou mais células combinadas para que partilhem um único valor e formato. No aspeto, a área unida abrange várias linhas ou colunas. Uma área unida é indexada pela localização da célula da tabela superior esquerda (linha, coluna) ao definir o respetivo valor ou formato. A célula superior esquerda da área unida é sempre utilizada para definir o valor e a formatação. Todas as outras células na área unida têm de ser cadeias vazias sem formatação aplicada.

Para especificar uma área unida, forneça a localização superior esquerda onde a área é iniciada (linha, coluna) e o comprimento da área em linhas e colunas. O diagrama seguinte mostra um exemplo destes valores para uma área unida com 3 linhas por 2 colunas de tamanho. Tenha em atenção que as áreas unidas não se podem sobrepor umas às outras.

Utilize a propriedade TableAddOptions.mergedAreas para especificar uma ou mais áreas unidas. O seguinte exemplo de código mostra como criar uma tabela com duas áreas unidas. Sobre o exemplo de código, tenha em atenção o seguinte:

• A propriedade values só tem de especificar o valor para o canto superior esquerdo da área unida. Todos os outros valores de células na área unida têm de especificar cadeias vazias ("").

• Cada área unida tem de especificar a localização do canto superior esquerdo (linha, coluna) e o comprimento nas células da área unida em termos de contagem de linhas e contagem de colunas.

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);

O exemplo anterior cria uma tabela com duas áreas unidas, conforme mostrado na imagem seguinte.

Obter e definir valores de células de tabela

Depois de criar uma tabela, pode obter ou definir valores de cadeia nas células. Tenha em atenção que esta é a única parte de uma tabela que pode alterar. Não pode alterar limites, tipos de letra, larguras ou outras propriedades de células. Se precisar de atualizar uma tabela, elimine-a e recrie-a. O seguinte exemplo de código mostra como localizar uma tabela existente e definir um novo valor para uma célula na tabela.

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";
});

Também pode obter as seguintes propriedades só de leitura da tabela.

• rowCount
• columnCount

O exemplo seguinte mostra como obter as propriedades da tabela e registá-las na consola. O exemplo também mostra como obter as áreas unidas na tabela.

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);
});