Arbeiten mit Tabellen mithilfe der PowerPoint-JavaScript-API

Erstellen Sie PowerPoint-Tabellen in Ihrem Add-In, und steuern Sie Werte, Formatierung, Größenanpassung und zusammengeführte Bereiche mithilfe der PowerPoint-JavaScript-API.

Verwenden Sie diesen Artikel, wenn Sie Tabellen programmgesteuert zur Erstellungszeit generieren möchten. Nachdem Sie eine Tabelle erstellt haben, können Sie den Zelltext aktualisieren, aber keine Formatierung oder Tabellenstruktur.

Erstellen einer leeren Tabelle

Um eine leere Tabelle zu erstellen, rufen Sie die ShapeCollection.addTable()- Methode auf, und geben Sie an, wie viele Zeilen und Spalten die Tabelle benötigt. Im folgenden Codebeispiel wird gezeigt, wie Sie eine Tabelle mit 3 Zeilen und 4 Spalten erstellen.

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

Im vorherigen Beispiel werden keine Optionen angegeben, sodass die Tabelle standardmäßig auf die von PowerPoint bereitgestellte Formatierung festgelegt wird. Die folgende Abbildung zeigt ein Beispiel für eine leere Tabelle, die in PowerPoint mit Standardformatierung erstellt wurde.

Angeben von Werten

Sie können die Tabelle beim Erstellen mit Zeichenfolgenwerten auffüllen. Stellen Sie dazu ein zweidimensionales Array von Werten im TableAddOptions-Objekt bereit. Im folgenden Codebeispiel wird eine Tabelle mit Zeichenfolgenwerten von "1" bis "12" erstellt. Beachten Sie Folgendes:

• Sie müssen eine leere Zelle als leere Zeichenfolge "" angeben. Wenn ein Wert nicht definiert ist oder fehlt, addTable löst einen Fehler aus.
• Das äußere Array enthält eine Liste von Zeilen. Jede Zeile ist ein inneres Array, das eine Liste von Zeichenfolgenzellenwerten enthält.
• Die Funktion namens insertTableOnCurrentSlide wird in anderen Beispielen in diesem Artikel verwendet.

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

Im vorherigen Beispiel wird eine Tabelle mit Werten erstellt, wie in der folgenden Abbildung dargestellt.

Zellenformatierung angeben

Sie können beim Erstellen einer Tabelle zellenformatieren, einschließlich Rahmenart, Füllformat, Schriftschnitt, horizontaler Ausrichtung, Einzugsebene und vertikaler Ausrichtung. Verwenden Sie das TableCellProperties-Objekt , um diese Formate anzugeben.

Einheitliche Zellformatierung

Einheitliche Zellformatierung gilt für die gesamte Tabelle. Wenn Sie beispielsweise die einheitliche Schriftfarbe auf Weiß festlegen, verwenden alle Tabellenzellen die weiße Schriftart. Verwenden Sie einheitliche Zellenformatierung, um die gewünschte Standardformatierung für die gesamte Tabelle zu steuern.

Legen Sie mithilfe der TableAddOptions.uniformCellProperties-Eigenschaft eine einheitliche Zellformatierung für die gesamte Tabelle fest. Das folgende Codebeispiel zeigt, wie Sie alle Tabellenzellen auf eine dunkle schieferblaue Füllfarbe und eine fettweiße Schriftart festlegen.

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

Im vorherigen Beispiel wird eine Tabelle erstellt, wie in der folgenden Abbildung dargestellt.

Spezifische Zellformatierung

Spezifische Zellformatierungen gelten für einzelne Zellen und überschreiben ggf. die einheitliche Zellformatierung. Legen Sie die Formatierung einzelner Zellen mithilfe der TableAddOptions.specificCellProperties-Eigenschaft fest. Im folgenden Codebeispiel wird gezeigt, wie die Füllfarbe für die Zelle in Zeile 1, Spalte 1 auf Schwarz festgelegt wird.

Beachten Sie, dass specificCellProperties ein 2D-Array sein muss, das genau der Tabellengröße entspricht. Im Beispiel wird zunächst das gesamte leere 2D-Array von Objekten erstellt. Anschließend wird das spezifische Zellenformat in Zeile 1, Spalte 1, festgelegt, nachdem das Optionsobjekt erstellt wurde.

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

Im vorherigen Beispiel wird eine Tabelle mit einem bestimmten Format erstellt, das auf die Zelle in Zeile 1, Spalte 1 angewendet wird, wie in der folgenden Abbildung dargestellt.

Im vorherigen Beispiel wird die Font-Eigenschaft vom Typ FontProperties verwendet. Mit font der -Eigenschaft können Sie viele Eigenschaften angeben, z. B. Fett, Kursiv, Name, Farbe und mehr. Im folgenden Codebeispiel wird gezeigt, wie Mehrere Eigenschaften für eine Schriftart für eine Zelle angegeben werden.

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

Sie können auch eine Fülleigenschaft vom Typ FillProperties angeben. Die fill -Eigenschaft kann eine Farbe und den Transparenzprozentsatz angeben. Im folgenden Codebeispiel wird gezeigt, wie eine Füllung für alle Tabellenzellen mit der Farbe "dunkelrot" und einer Transparenz von 50 % erstellt wird.

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

Rahmen

Verwenden Sie das TableCellProperties.borders-Objekt , um Rahmen für Zellen in der Tabelle zu definieren. Im folgenden Codebeispiel wird gezeigt, wie Sie einen roten Rahmen mit der Gewichtung 3 für die Zelle in Zeile 1, Spalte 1 festlegen.

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

Horizontale und vertikale Ausrichtung

Verwenden Sie die TableCellProperties.horizontalAlignment-Eigenschaft , um die Textausrichtung in einer Zelle zu steuern. Das folgende Beispiel zeigt, wie die horizontale Ausrichtung für drei Zellen in einer Tabelle auf links, rechts und zentrieren festgelegt wird. Eine Liste aller Ausrichtungsoptionen finden Sie unter ParagraphHorizontalAlignment-Enumeration .

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

Im vorherigen Beispiel wird eine Tabelle mit links/oben, zentriert und rechts/unten textausrichtung erstellt, wie in der folgenden Abbildung dargestellt.

Angeben von Zeilen- und Spaltenbreiten

Geben Sie Zeilen- und Spaltenbreiten mithilfe der Eigenschaften TableAddOptions.rows und TableAddOptions.columns an. Die rows -Eigenschaft ist ein Array von TableRowProperties , das Sie zum Festlegen der rowHeight-Eigenschaft jeder Zeile verwenden. Ebenso ist die columns -Eigenschaft ein Array von TableColumnProperties , das Sie zum Festlegen der columnWidth-Eigenschaft jeder Spalte verwenden. Die Breite oder Höhe ist in Punkten festgelegt.

PowerPoint berücksichtigt möglicherweise nicht die von Ihnen festgelegte Höhe oder Breite, wenn sie in den Text passen muss. Wenn der Text beispielsweise für eine Spalte zu breit ist, erhöht PowerPoint die Zeilenhöhe, sodass der Text in die nächste Zeile umgebrochen werden kann. Ebenso erhöht sich die Spaltenbreite, wenn die angegebene Größe kleiner als ein einzelnes Zeichen im angegebenen Schriftgrad ist.

Das folgende Codebeispiel zeigt, wie Die Zeilenhöhe und Spaltenbreite für eine neue Tabelle festgelegt wird. Legen Sie die rows Eigenschaften und columns auf Arrays von Objekten fest, die jeder Anzahl entsprechen.

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

Im vorherigen Beispiel wird eine Tabelle mit drei benutzerdefinierten Spaltenbreiten und einer benutzerdefinierten Zeilenhöhe erstellt, wie in der folgenden Abbildung dargestellt.

Angeben zusammengeführter Bereiche

Ein zusammengeführter Bereich besteht aus zwei oder mehr Zellen, die so kombiniert werden, dass sie einen einzelnen Wert und ein einzelnes Format gemeinsam haben. In der Darstellung erstreckt sich der zusammengeführte Bereich über mehrere Zeilen oder Spalten. Indizieren Sie einen zusammengeführten Bereich anhand der Position der oberen linken Tabellenzelle (Zeile, Spalte), wenn Sie seinen Wert oder sein Format festlegen. Verwenden Sie immer die obere linke Zelle des zusammengeführten Bereichs, um den Wert und die Formatierung festzulegen. Alle anderen Zellen im zusammengeführten Bereich müssen leere Zeichenfolgen ohne angewendete Formatierung sein.

Um einen zusammengeführten Bereich anzugeben, geben Sie die Position oben links an, an der der Bereich beginnt (Zeile, Spalte) und die Länge des Bereichs in Zeilen und Spalten. Das folgende Diagramm zeigt ein Beispiel für diese Werte für einen zusammengeführten Bereich, der 3 Zeilen mal 2 Spalten groß ist. Beachten Sie, dass sich zusammengeführte Bereiche nicht überlappen können.

Verwenden Sie die TableAddOptions.mergedAreas-Eigenschaft , um einen oder mehrere zusammengeführte Bereiche anzugeben. Im folgenden Codebeispiel wird veranschaulicht, wie Sie eine Tabelle mit zwei zusammengeführten Bereichen erstellen. Beachten Sie zum Codebeispiel die folgenden Punkte.

• Die values -Eigenschaft darf nur den Wert für die obere linke Ecke des zusammengeführten Bereichs angeben. Alle anderen Zellwerte im zusammengeführten Bereich müssen leere Zeichenfolgen ("") angeben.

• Jeder zusammengeführte Bereich muss die Position der oberen linken Ecke (Zeile, Spalte) und die Länge in Zellen des zusammengeführten Bereichs in Bezug auf Zeilenanzahl und Spaltenanzahl angeben.

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

Im vorherigen Beispiel wird eine Tabelle mit zwei zusammengeführten Bereichen erstellt, wie in der folgenden Abbildung dargestellt.

Abrufen und Festlegen von Tabellenzellenwerten

Nachdem Sie eine Tabelle erstellt haben, können Sie Zeichenfolgenwerte in den Zellen abrufen oder festlegen. Dies ist der einzige Teil einer Tabelle, den Sie ändern können. Rahmen, Schriftarten, Breiten oder andere Zelleneigenschaften können nicht geändert werden. Wenn Sie die Formatierung oder Struktur aktualisieren müssen, löschen Sie die Tabelle, und erstellen Sie sie neu. Im folgenden Codebeispiel wird gezeigt, wie Sie eine vorhandene Tabelle finden und einen neuen Wert für eine Zelle festlegen.

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

Sie können auch die folgenden schreibgeschützten Eigenschaften aus der Tabelle abrufen.

• Rowcount
• Columncount

Im folgenden Beispiel wird gezeigt, wie Sie die Tabelleneigenschaften abrufen und in der Konsole protokollieren. Das Beispiel zeigt auch, wie die zusammengeführten Bereiche in der Tabelle abgerufen werden.

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

Siehe auch

• PowerPoint-JavaScript-Objektmodell in Office-Add-Ins
• Arbeiten mit Shapes mithilfe der PowerPoint-JavaScript-API
• Binden an Formen in einer PowerPoint-Präsentation
• JavaScript-API-Referenz für PowerPoint