Arbeiten mit Tabellen mithilfe der PowerPoint-JavaScript-API

Dieser Artikel enthält Codebeispiele, die zeigen, wie Tabellen erstellt und die Formatierung mithilfe der PowerPoint-JavaScript-API gesteuert wird.

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:

• Eine leere Zelle muss als leere Zeichenfolge "" angegeben werden. 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. Diese Formate werden vom TableCellProperties-Objekt angegeben.

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. Einheitliche Zellenformatierung ist nützlich, um die gewünschte Standardformatierung für die gesamte Tabelle zu steuern.

Geben Sie mithilfe der TableAddOptions.uniformCellProperties-Eigenschaft eine einheitliche Zellenformatierung für die gesamte Tabelle an. 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.

specificCellProperties Beachten Sie, dass ein 2D-Array sein muss, das genau mit der 2D-Größe der Tabelle übereinstimmt. 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;
// 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);

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. Das folgende Codebeispiel zeigt, wie die Rahmen einer Zelle in Zeile 1 nach Spalte 1 auf einen roten Rahmen mit der Gewichtung 3 festgelegt werden.

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

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

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.

Die von Ihnen festgelegte Höhe oder Breite wird von PowerPoint möglicherweise nicht berücksichtigt, wenn sie dem Text entsprechen 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. Beachten Sie, dass die Zeilen- und Spalteneigenschaften auf ein Array von Objekten festgelegt werden müssen, das ihrer Anzahl entspricht.

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

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. Ein zusammengeführter Bereich wird durch die Position der oberen linken Tabellenzelle (Zeile, Spalte) beim Festlegen des Werts oder Formats indiziert. Die obere linke Zelle des zusammengeführten Bereichs wird immer verwendet, 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 folgendes zum Codebeispiel:

• 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 obere linke 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 eine Tabelle erstellt wurde, können Sie Zeichenfolgenwerte in den Zellen abrufen oder festlegen. Beachten Sie, dass dies der einzige Teil einer Tabelle ist, den Sie ändern können. Rahmen, Schriftarten, Breiten oder andere Zelleneigenschaften können nicht geändert werden. Wenn Sie eine Tabelle aktualisieren müssen, löschen Sie sie, und erstellen Sie sie neu. Das folgende Codebeispiel zeigt, wie Sie eine vorhandene Tabelle finden und einen neuen Wert für eine Zelle in der Tabelle 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);
});