Trabalhar com tabelas usando a API JavaScript do PowerPoint

Crie tabelas do PowerPoint no seu suplemento e controle valores, formatação, dimensionamento e áreas mescladas usando a API JavaScript do PowerPoint.

Use este artigo quando quiser gerar tabelas programaticamente no momento da criação. Depois de criar uma tabela, você pode atualizar o texto da célula, mas não a formatação ou a estrutura da tabela.

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 exemplo de código a seguir 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, portanto, a tabela usa como padrão a formatação fornecida pelo PowerPoint. A imagem a seguir mostra um exemplo de uma tabela vazia criada com formatação padrão no PowerPoint.

Especificar valores

Você pode preencher a tabela com valores de cadeia de caracteres ao criá-la. Para fazer isso, forneça uma matriz bidimensional de valores no objeto TableAddOptions . O exemplo de código a seguir cria uma tabela com valores de cadeia de caracteres de "1" a "12". Observe o seguinte:

• Você deve especificar uma célula vazia como uma cadeia de caracteres vazia "". Se um valor for indefinido ou ausente, addTable gera um erro.
• A matriz externa contém uma lista de linhas. Cada linha é uma matriz interna contendo uma lista de valores de células de cadeia de caracteres.
• A função nomeada insertTableOnCurrentSlide é usada em outros exemplos deste 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 os valores mostrados na imagem a seguir.

Especificar a formatação das células

Você pode especificar a formatação da célula ao criar uma tabela, incluindo estilo de borda, estilo de preenchimento, estilo de fonte, alinhamento horizontal, nível de recuo e alinhamento vertical. Use o objeto TableCellProperties para especificar esses formatos.

Formatação uniforme de células

A formatação uniforme de célula se aplica a toda a tabela. Por exemplo, se você definir a cor da fonte uniforme como branca, todas as células da tabela usarão a fonte branca. Use a formatação uniforme de célula para controlar a formatação padrão desejada em toda a tabela.

Defina a formatação uniforme da célula para toda a tabela usando a propriedade TableAddOptions.uniformCellProperties . O exemplo de código a seguir mostra como definir todas as células da tabela como azul ardósia escuro, cor de preenchimento e fonte branca em 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 a seguir.

Formatação específica de célula

A formatação de célula específica se aplica a células individuais e substitui a formatação uniforme da célula, se houver. Definir a formatação de célula individual usando a propriedade TableAddOptions.specificCellProperties . O exemplo de código a seguir mostra como definir a cor de preenchimento como preta para a célula na linha 1, coluna 1.

Observe que specificCellProperties deve ser uma matriz 2D que corresponda exatamente ao tamanho da tabela. O exemplo primeiro cria toda a matriz 2D vazia de objetos. Em seguida, ele define o formato de célula específico na linha 1, coluna 1, depois que o objeto de opções é criado.

const rowCount = 3;
const columnCount = 4;
const specificCellProperties = createCellArray(rowCount, columnCount);
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);

// Helper function to create a 2D array filled with empty and distinct objects.
function createCellArray(rowCount: number, columnCount: number): PowerPoint.TableCellProperties[][] {
    // Using Array.from() with a factory callback ensures each cell gets its own object reference.
    return Array.from({ length: rowCount }, () => Array.from({ length: columnCount }, () => ({})));
}

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

O exemplo anterior usa a propriedade font que é do tipo FontProperties. A font propriedade permite que você especifique muitas propriedades, como negrito, itálico, nome, cor e muito mais. O exemplo de código a seguir mostra como especificar várias propriedades de uma fonte para uma célula.

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

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

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

Bordas

Use o objeto TableCellProperties.borders para definir bordas para células na tabela. O exemplo de código a seguir mostra como definir uma borda vermelha com peso 3 para a célula na linha 1, coluna 1.

const columnCount = 3;
const rowCount = 3;
const specificCellProperties = createCellArray(rowCount, columnCount); // Helper function defined earlier.
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

Use a propriedade TableCellProperties.horizontalAlignment para controlar o alinhamento do texto em uma célula. O exemplo a seguir mostra como definir o alinhamento horizontal à esquerda, à direita e ao centro de três células em uma tabela. Para obter uma lista de todas as opções de alinhamento, consulte a enumeração ParagraphHorizontalAligning .

const rowCount = 3;
const columnCount = 3;
const specificCellProperties = createCellArray(rowCount, columnCount); // Helper function defined earlier.
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 esquerdo/superior, centralizado e direito/inferior, conforme mostrado na imagem a seguir.

Especificar larguras de linha e coluna

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

O PowerPoint pode não respeitar a altura ou largura que você definiu se ele precisar ajustar o texto. Por exemplo, se o texto for muito largo para uma coluna, o PowerPoint aumentará a altura da linha para que ele possa quebrar o texto para a próxima linha. Da mesma forma, a largura da coluna aumenta se o tamanho especificado for menor do que um único caractere no tamanho de fonte especificado.

O exemplo de código a seguir mostra como definir a altura da linha e a largura da coluna para uma nova tabela. Defina as rows propriedades and columns como matrizes de objetos que correspondam a cada 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(rowCount).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 a seguir.

Especificar áreas mescladas

Uma área mesclada consiste em duas ou mais células combinadas para que compartilhem um único valor e formato. Na aparência, a área mesclada abrange várias linhas ou colunas. Indexe uma área mesclada por sua localização na célula da tabela superior esquerda (linha, coluna) ao definir seu valor ou formato. Sempre use a célula superior esquerda da área mesclada para definir o valor e a formatação. Todas as outras células na área mesclada devem ser cadeias de caracteres vazias sem formatação aplicada.

Para especificar uma área mesclada, forneça o local superior esquerdo onde a área começa (linha, coluna) e o comprimento da área em linhas e colunas. O diagrama a seguir mostra um exemplo desses valores para uma área mesclada de 3 linhas por 2 colunas de tamanho. Observe que as áreas mescladas não podem se sobrepor.

Use a propriedade TableAddOptions.mergedAreas para especificar uma ou mais áreas mescladas. O exemplo de código a seguir mostra como criar uma tabela com duas áreas mescladas. Sobre a amostra de código, observe os seguintes pontos.

• A values propriedade deve especificar apenas o valor para o canto superior esquerdo da área mesclada. Todos os outros valores de célula na área mesclada devem especificar cadeias de caracteres vazias ("").

• Cada área mesclada deve especificar o local do canto superior esquerdo (linha, coluna) e o comprimento em células da área mesclada 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 mescladas, conforme mostrado na imagem a seguir.

Obter e definir valores de células da tabela

Depois de criar uma tabela, você pode obter ou definir valores de cadeia de caracteres nas células. Esta é a única parte de uma tabela que você pode alterar. Você não pode alterar bordas, fontes, larguras ou outras propriedades da célula. Se você precisar atualizar a formatação ou a estrutura, exclua a tabela e recrie-a. O exemplo de código a seguir mostra como localizar uma tabela existente e definir um novo valor para uma célula.

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

Você também pode obter as seguintes propriedades somente leitura da tabela.

• rowCount
• columnCount

O exemplo a seguir mostra como obter as propriedades da tabela e registrá-las no console. O exemplo também mostra como obter as áreas mescladas 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);
});

Confira também

• Modelo de objeto JavaScript do PowerPoint em Suplementos do Office
• Trabalhar com formas usando a API JavaScript do PowerPoint
• Associar a formas em uma apresentação do PowerPoint
• Referência da API JavaScript do PowerPoint