Freigeben über

Arbeiten mit Shapes mithilfe der PowerPoint-JavaScript-API

In diesem Artikel wird beschrieben, wie geometrische Formen, Linien und Textfelder in Verbindung mit den Shape- und ShapeCollection-APIs verwendet werden.

Erstellen von Shapes

Shapes werden über die Shape-Auflistungslide.shapes einer Folie () erstellt und gespeichert. ShapeCollection verfügt über mehrere .add* Methoden für diesen Zweck. Alle Shapes verfügen über Namen und IDs, die für sie generiert werden, wenn sie der Auflistung hinzugefügt werden. Dies sind die name Eigenschaften und id . name kann von Ihrem Add-In festgelegt werden.

Geometrische Formen

Eine geometrische Form wird mit einer der Überladungen von ShapeCollection.addGeometricShapeerstellt. Der erste Parameter ist entweder eine GeometricShapeType-Enumeration oder die Zeichenfolgenentsprechung eines der Enumerationswerte. Es gibt einen optionalen zweiten Parameter vom Typ ShapeAddOptions , der die Anfangsgröße des Shapes und seine Position relativ zur oberen und linken Seite der Folie in Punkt angeben kann. Oder diese Eigenschaften können festgelegt werden, nachdem die Form erstellt wurde.

Im folgenden Codebeispiel wird ein Rechteck mit dem Namen "Square" erstellt, das 100 Punkt von der oberen und linken Seite der Folie entfernt positioniert ist. Die -Methode gibt ein Shape -Objekt zurück.

// This sample creates a rectangle positioned 100 points from the top and left sides
// of the slide and is 150x150 points. The shape is put on the first slide.
await PowerPoint.run(async (context) => {
    const shapes = context.presentation.slides.getItemAt(0).shapes;
    const rectangle = shapes.addGeometricShape(PowerPoint.GeometricShapeType.rectangle);
    rectangle.left = 100;
    rectangle.top = 100;
    rectangle.height = 150;
    rectangle.width = 150;
    rectangle.name = "Square";
    await context.sync();
});

Lines

Eine Zeile wird mit einer der Überladungen von ShapeCollection.addLineerstellt. Der erste Parameter ist entweder eine ConnectorType-Enumeration oder die Zeichenfolgenentsprechung eines der Werte der Enumeration, um anzugeben, wie die Linie zwischen Endpunkten wechselt. Es gibt einen optionalen zweiten Parameter vom Typ ShapeAddOptions , der den Start- und Endpunkt der Linie angeben kann. Oder diese Eigenschaften können festgelegt werden, nachdem die Form erstellt wurde. Die -Methode gibt ein Shape -Objekt zurück.

Hinweis

Wenn es sich bei der Form um eine Linie handelt, geben die top Eigenschaften und left der Shape -Objekte und ShapeAddOptions den Anfangspunkt der Linie relativ zum oberen und linken Rand der Folie an. Die height Eigenschaften und width geben den Endpunkt der Linie relativ zum Startpunkt an. Der Endpunkt relativ zum oberen und linken Rand der Folie ist also (top + height) bis ().left + width Die Maßeinheit für alle Eigenschaften ist Punkte, und negative Werte sind zulässig.

Im folgenden Codebeispiel wird eine gerade Linie auf der Folie erstellt.

// This sample creates a straight line on the first slide.
await PowerPoint.run(async (context) => {
    const shapes = context.presentation.slides.getItemAt(0).shapes;
    const line = shapes.addLine(PowerPoint.ConnectorType.straight, {left: 200, top: 50, height: 300, width: 150});
    line.name = "StraightLine";
    await context.sync();
});

Textfelder

Ein Textfeld wird mit der addTextBox-Methode erstellt. Der erste Parameter ist der Text, der anfänglich im Feld angezeigt werden soll. Es gibt einen optionalen zweiten Parameter vom Typ ShapeAddOptions , der die Anfangsgröße des Textfelds und seine Position relativ zur oberen und linken Seite der Folie angeben kann. Oder diese Eigenschaften können festgelegt werden, nachdem die Form erstellt wurde.

Im folgenden Codebeispiel wird das Erstellen eines Textfelds auf der ersten Folie veranschaulicht.

// This sample creates a text box with the text "Hello!" and sizes it appropriately.
await PowerPoint.run(async (context) => {
    const shapes = context.presentation.slides.getItemAt(0).shapes;
    const textbox = shapes.addTextBox("Hello!");
    textbox.left = 100;
    textbox.top = 100;
    textbox.height = 300;
    textbox.width = 450;
    textbox.name = "Textbox";
    await context.sync();
});

Verschieben und Ändern der Größe von Shapes

Shapes befinden sich auf der Folie. Ihre Platzierung wird durch die left Eigenschaften und top definiert. Diese fungieren als Ränder der jeweiligen Folie, gemessen in Punkten, wobei left: 0 und top: 0 die obere linke Ecke ist. Die Formgröße wird durch die height Eigenschaften und width angegeben. Ihr Code kann die Form verschieben oder ihre Größe ändern, indem diese Eigenschaften zurückgesetzt werden. (Diese Eigenschaften haben eine etwas andere Bedeutung, wenn die Form eine Linie ist. Siehe Zeilen.)

Text in Formen

Geometrische Formen können Text enthalten. Shapes verfügen über eine textFrame Eigenschaft vom Typ TextFrame. Das TextFrame -Objekt verwaltet die Textanzeigeoptionen (z. B. Ränder und Textüberlauf). TextFrame.textRange ist ein TextRange-Objekt mit den Textinhalts- und Schriftarteinstellungen.

Im folgenden Codebeispiel wird eine geometrische Form namens "Klammern" mit dem Text "Shape text" erstellt. Außerdem werden die Form und die Textfarben angepasst und die vertikale Ausrichtung des Texts auf die Mitte festgelegt.

// This sample creates a light blue rectangle with braces ("{}") on the left and right ends
// and adds the purple text "Shape text" to the center.
await PowerPoint.run(async (context) => {
    const shapes = context.presentation.slides.getItemAt(0).shapes;
    const braces = shapes.addGeometricShape(PowerPoint.GeometricShapeType.bracePair);
    braces.left = 100;
    braces.top = 400;
    braces.height = 50;
    braces.width = 150;
    braces.name = "Braces";
    braces.fill.setSolidColor("lightblue");
    braces.textFrame.textRange.text = "Shape text";
    braces.textFrame.textRange.font.color = "purple";
    braces.textFrame.verticalAlignment = PowerPoint.TextVerticalAlignment.middleCentered;
    await context.sync();
});

Gruppierung und Aufheben der Gruppierung von Shapes

In PowerPoint können Sie mehrere Shapes gruppieren und wie eine einzelne Form behandeln. Anschließend können Sie die Gruppierung von gruppierten Shapes aufheben. Weitere Informationen zum Gruppieren von Objekten in der PowerPoint-Benutzeroberfläche finden Sie unter Gruppieren oder Aufheben der Gruppierung von Formen, Bildern oder anderen Objekten.

Gruppierungs-Shapes

Um Shapes mit der JavaScript-API zu gruppieren, verwenden Sie ShapeCollection.addGroup.

Im folgenden Codebeispiel wird gezeigt, wie vorhandene Shapes vom Typ GeometricShape auf der aktuellen Folie gruppiert werden.

// Groups the geometric shapes on the current slide.
await PowerPoint.run(async (context) => {
    // Get the shapes on the current slide.
    context.presentation.load("slides");
    const slide = context.presentation.getSelectedSlides().getItemAt(0);
    slide.load("shapes/items/type,shapes/items/id");
    await context.sync();

    const shapes = slide.shapes;
    const shapesToGroup = shapes.items.filter((item) => item.type === PowerPoint.ShapeType.geometricShape);
    if (shapesToGroup.length === 0) {
        console.warn("No shapes on the current slide, so nothing to group.");
        return;
    }

    // Group the geometric shapes.
    console.log(`Number of shapes to group: ${shapesToGroup.length}`);
    const group = shapes.addGroup(shapesToGroup);
    group.load("id");
    await context.sync();

    console.log(`Grouped shapes. Group ID: ${group.id}`);
});

Aufheben der Gruppierung von Shapes

Um die Gruppierung von Shapes mit der JavaScript-API aufzuheben, rufen Sie die Group-Eigenschaft aus dem Objekt der Gruppe Shape ab, und rufen Sie dann ShapeGroup.ungroup auf.

Im folgenden Codebeispiel wird gezeigt, wie die Gruppierung der ersten Formgruppe auf der aktuellen Folie aufgehoben wird.

// Ungroups the first shape group on the current slide.
await PowerPoint.run(async (context) => {
    // Get the shapes on the current slide.
    context.presentation.load("slides");
    const slide = context.presentation.getSelectedSlides().getItemAt(0);
    slide.load("shapes/items/type,shapes/items/id");
    await context.sync();

    const shapes = slide.shapes;
    const shapeGroups = shapes.items.filter((item) => item.type === PowerPoint.ShapeType.group);
    if (shapeGroups.length === 0) {
        console.warn("No shape groups on the current slide, so nothing to ungroup.");
        return;
    }

    // Ungroup the first grouped shapes.
    const firstGroupId = shapeGroups[0].id;
    const shapeGroupToUngroup = shapes.getItem(firstGroupId);
    shapeGroupToUngroup.group.ungroup();
    await context.sync();

    console.log(`Ungrouped shapes with group ID: ${firstGroupId}`);
});

Shapes löschen

Shapes werden mit der -Methode des delete Objekts aus der Shape Folie entfernt.

Im folgenden Codebeispiel wird gezeigt, wie Shapes gelöscht werden.

await PowerPoint.run(async (context) => {
    // Delete all shapes from the first slide.
    const shapes = context.presentation.slides.getItemAt(0).shapes;

    // Load all the shapes in the collection without loading their properties.
    shapes.load("items/$none");
    await context.sync();
        
    shapes.items.forEach(function (shape) {
        shape.delete();
    });
    await context.sync();
});

Siehe auch