Arbeiten mit Shapes mithilfe der Excel-JavaScript-API

Excel definiert Shapes als jedes Objekt, das sich auf der Zeichnungsebene von Excel befindet. Das bedeutet, dass alles außerhalb einer Zelle eine Form ist. In diesem Artikel wird beschrieben, wie geometrische Formen, Linien und Bilder in Verbindung mit den Shape- und ShapeCollection-APIs verwendet werden. Diagramme werden im eigenen Artikel Arbeiten mit Diagrammen mithilfe der Excel-JavaScript-API behandelt.

Die folgende Abbildung zeigt Formen, die ein Thermometer bilden.

Erstellen von Shapes

Shapes werden über die Shape-Auflistung eines Arbeitsblatts (Worksheet.shapes) 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 für den einfachen Abruf mit der ShapeCollection.getItem(name) -Methode festgelegt werden.

Die folgenden Formentypen werden mithilfe der zugeordneten -Methode hinzugefügt.

Form	Add-Methode	Signatur
Geometrische Form	addGeometricShape	addGeometricShape(geometricShapeType: Excel.GeometricShapeType): Excel.Shape
Bild (jpeg oder PNG)	Addimage	addImage(base64ImageString: string): Excel.Shape
Zeile	Addline	addLine(startLeft: number, startTop: number, endLeft: number, endTop: number, connectorType?: Excel.ConnectorType): Excel.Shape
Svg	addSvg	addSvg(xml: string): Excel.Shape
Textfeld	Addtextbox	addTextBox(text?: string): Excel.Shape

Geometrische Formen

Eine geometrische Form wird mit ShapeCollection.addGeometricShapeerstellt. Diese Methode akzeptiert eine GeometricShapeType-Enumeration als Argument.

Im folgenden Codebeispiel wird ein 150 x 150 Pixel großes Rechteck namens "Square" erstellt, das 100 Pixel von der oberen und linken Seite des Arbeitsblatts entfernt positioniert ist.

// This sample creates a rectangle positioned 100 pixels from the top and left sides
// of the worksheet and is 150x150 pixels.
await Excel.run(async (context) => {
    let shapes = context.workbook.worksheets.getItem("MyWorksheet").shapes;

    let rectangle = shapes.addGeometricShape(Excel.GeometricShapeType.rectangle);
    rectangle.left = 100;
    rectangle.top = 100;
    rectangle.height = 150;
    rectangle.width = 150;
    rectangle.name = "Square";

    await context.sync();
});

Bilder

JPEG-, PNG- und SVG-Bilder können als Formen in ein Arbeitsblatt eingefügt werden. Die ShapeCollection.addImage -Methode verwendet eine base64-codierte Zeichenfolge als Argument. Dies ist entweder ein JPEG- oder PNG-Bild in Zeichenfolgenform. ShapeCollection.addSvg akzeptiert auch eine Zeichenfolge, obwohl dieses Argument XML ist, das die Grafik definiert.

Das folgende Codebeispiel zeigt eine Bilddatei, die von einem FileReader als Zeichenfolge geladen wird. Die Zeichenfolge enthält die Metadaten "base64", die entfernt wurden, bevor das Shape erstellt wird.

// This sample creates an image as a Shape object in the worksheet.
let myFile = document.getElementById("selectedFile");
let reader = new FileReader();

reader.onload = (event) => {
    Excel.run(function (context) {
        let startIndex = reader.result.toString().indexOf("base64,");
        let myBase64 = reader.result.toString().substr(startIndex + 7);
        let sheet = context.workbook.worksheets.getItem("MyWorksheet");
        let image = sheet.shapes.addImage(myBase64);
        image.name = "Image";
        return context.sync();
    }).catch(errorHandlerFunction);
};

// Read in the image file as a data URL.
reader.readAsDataURL(myFile.files[0]);

Lines

Eine Zeile wird mit ShapeCollection.addLineerstellt. Diese Methode benötigt den linken und oberen Rand des Start- und Endpunkts der Linie. Außerdem wird eine ConnectorType-Enumeration benötigt, um anzugeben, wie die Linie zwischen Endpunkten verrenkt wird. Im folgenden Codebeispiel wird eine gerade Linie auf dem Arbeitsblatt erstellt.

// This sample creates a straight line from [200,50] to [300,150] on the worksheet.
await Excel.run(async (context) => {
    let shapes = context.workbook.worksheets.getItem("MyWorksheet").shapes;
    let line = shapes.addLine(200, 50, 300, 150, Excel.ConnectorType.straight);
    line.name = "StraightLine";
    await context.sync();
});

Linien können mit anderen Shape-Objekten verbunden werden. Die connectBeginShape Methoden und connectEndShape fügen den Anfang und das Ende einer Linie an Shapes an den angegebenen Verbindungspunkten an. Die Positionen dieser Punkte variieren je nach Form, aber die Shape.connectionSiteCount kann verwendet werden, um sicherzustellen, dass Ihr Add-In keine Verbindung mit einem Punkt herstellt, der außerhalb der Grenzen liegt. Eine Linie wird mit den disconnectBeginShape Methoden und disconnectEndShape von angefügten Shapes getrennt.

Im folgenden Codebeispiel wird die Zeile "MyLine" mit zwei Formen namens "LeftShape" und "RightShape" verbunden.

// This sample connects a line between two shapes at connection points '0' and '3'.
await Excel.run(async (context) => {
    let shapes = context.workbook.worksheets.getItem("MyWorksheet").shapes;
    let line = shapes.getItem("MyLine").line;
    line.connectBeginShape(shapes.getItem("LeftShape"), 0);
    line.connectEndShape(shapes.getItem("RightShape"), 3);
    await context.sync();
});

Verschieben und Ändern der Größe von Shapes

Shapes befinden sich oben auf dem Arbeitsblatt. Ihre Platzierung wird durch die - und top -leftEigenschaft definiert. Diese fungieren als Ränder der jeweiligen Ränder des Arbeitsblatts, wobei [0, 0] die obere linke Ecke ist. Diese können entweder direkt festgelegt oder von ihrer aktuellen Position aus mit den incrementLeft Methoden und incrementTop angepasst werden. Wie viel eine Form von der Standardposition gedreht wird, wird ebenfalls auf diese Weise festgelegt, wobei die rotation -Eigenschaft der absolute Betrag ist und die incrementRotation -Methode die vorhandene Drehung anpasst.

Die Tiefe eines Shapes relativ zu anderen Formen wird durch die zorderPosition -Eigenschaft definiert. Dies wird mithilfe der setZOrder -Methode festgelegt, die eine ShapeZOrder-Instanz annimmt. setZOrder passt die Reihenfolge der aktuellen Form relativ zu den anderen Formen an.

Ihr Add-In verfügt über mehrere Optionen zum Ändern der Höhe und Breite von Formen. Durch Festlegen der height -Eigenschaft oder width der -Eigenschaft wird die angegebene Dimension geändert, ohne die andere Dimension zu ändern. Die scaleHeight und scaleWidth passen die jeweiligen Abmessungen der Form relativ zur aktuellen oder ursprünglichen Größe an (basierend auf dem Wert des bereitgestellten ShapeScaleType). Ein optionaler ShapeScaleFrom-Parameter gibt an, von wo aus die Form skaliert wird (obere linke Ecke, mittlere oder untere rechte Ecke). Wenn die lockAspectRatio -Eigenschaft ist true, behalten die Skalierungsmethoden das aktuelle Seitenverhältnis des Shapes bei, indem sie auch die andere Dimension anpassen.

Hinweis

Direkte Änderungen an den height Eigenschaften und width wirken sich nur auf diese Eigenschaft aus, unabhängig vom Wert der lockAspectRatio Eigenschaft.

Das folgende Codebeispiel zeigt, wie eine Form auf das 1,25-Fache ihrer ursprünglichen Größe skaliert und um 30 Grad gedreht wird.

// In this sample, the shape "Octagon" is rotated 30 degrees clockwise
// and scaled 25% larger, with the upper-left corner remaining in place.
await Excel.run(async (context) => {
    let sheet = context.workbook.worksheets.getItem("MyWorksheet");

    let shape = sheet.shapes.getItem("Octagon");
    shape.incrementRotation(30);
    shape.lockAspectRatio = true;
    shape.scaleWidth(
        1.25,
        Excel.ShapeScaleType.currentSize,
        Excel.ShapeScaleFrom.scaleFromTopLeft);

    await context.sync();
});

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 "Wave" mit dem Text "Shape Text" erstellt. Außerdem werden die Form und die Textfarben angepasst und die horizontale Ausrichtung des Texts auf die Mitte festgelegt.

// This sample creates a light-blue wave shape and adds the purple text "Shape text" to the center.
await Excel.run(async (context) => {
    let shapes = context.workbook.worksheets.getItem("MyWorksheet").shapes;
    let wave = shapes.addGeometricShape(Excel.GeometricShapeType.wave);
    wave.left = 100;
    wave.top = 400;
    wave.height = 50;
    wave.width = 150;

    wave.name = "Wave";
    wave.fill.setSolidColor("lightblue");

    wave.textFrame.textRange.text = "Shape text";
    wave.textFrame.textRange.font.color = "purple";
    wave.textFrame.horizontalAlignment = Excel.ShapeTextHorizontalAlignment.center;

    await context.sync();
});

Die addTextBox -Methode von ShapeCollection erstellt einen GeometricShape vom Typ Rectangle mit weißem Hintergrund und schwarzem Text. Dies entspricht dem, was von der Excel-Schaltfläche Textfeld auf der Registerkarte Einfügen erstellt wird. addTextBox verwendet ein Zeichenfolgenargument, um den Text des TextRangefestzulegen.

Das folgende Codebeispiel zeigt die Erstellung eines Textfelds mit dem Text "Hello!".

// This sample creates a text box with the text "Hello!" and sizes it appropriately.
await Excel.run(async (context) => {
    let shapes = context.workbook.worksheets.getItem("MyWorksheet").shapes;
    let textbox = shapes.addTextBox("Hello!");
    textbox.left = 100;
    textbox.top = 100;
    textbox.height = 20;
    textbox.width = 45;
    textbox.name = "Textbox";
    await context.sync();
});

Shape-Gruppen

Shapes können gruppiert werden. Dies ermöglicht es einem Benutzer, sie als eine einzelne Entität für die Positionierung, Größenanpassung und andere verwandte Aufgaben zu behandeln. Eine ShapeGroup ist ein Typ von Shape, sodass das Add-In die Gruppe als einzelne Form behandelt.

Das folgende Codebeispiel zeigt drei Formen, die gruppiert werden. Das folgende Codebeispiel zeigt, dass die Shape-Gruppe um 50 Pixel nach rechts verschoben wird.

// This sample takes three previously-created shapes ("Square", "Pentagon", and "Octagon")
// and groups them into a single ShapeGroup.
await Excel.run(async (context) => {
    let shapes = context.workbook.worksheets.getItem("MyWorksheet").shapes;
    let square = shapes.getItem("Square");
    let pentagon = shapes.getItem("Pentagon");
    let octagon = shapes.getItem("Octagon");

    let shapeGroup = shapes.addGroup([square, pentagon, octagon]);
    shapeGroup.name = "Group";
    console.log("Shapes grouped");

    await context.sync();
});

// This sample moves the previously created shape group to the right by 50 pixels.
await Excel.run(async (context) => {
    let shapes = context.workbook.worksheets.getItem("MyWorksheet").shapes;
    let shapeGroup = shapes.getItem("Group");
    shapeGroup.incrementLeft(50);
    await context.sync();
});

Wichtig

Auf einzelne Shapes innerhalb der Gruppe wird über die ShapeGroup.shapes -Eigenschaft vom Typ GroupShapeCollection verwiesen. Auf sie kann nach der Gruppierung nicht mehr über die Shape-Sammlung des Arbeitsblatts zugegriffen werden. Wenn Ihr Arbeitsblatt beispielsweise drei Formen enthält und alle zusammen gruppiert sind, gibt die -Methode des Arbeitsblatts shapes.getCount die Anzahl 1 zurück.

Exportieren von Formen als Bilder

Jedes Shape Objekt kann in ein Bild konvertiert werden. Shape.getAsImage gibt base64-codierte Zeichenfolge zurück. Das Bildformat wird als PictureFormat-Enumeration angegeben, die an getAsImageübergeben wird.

await Excel.run(async (context) => {
    let shapes = context.workbook.worksheets.getItem("MyWorksheet").shapes;
    let shape = shapes.getItem("Image");
    let stringResult = shape.getAsImage(Excel.PictureFormat.png);

    await context.sync();

    console.log(stringResult.value);
    // Instead of logging, your add-in may use the base64-encoded string to save the image as a file or insert it in HTML.
});

Shapes löschen

Shapes werden mit der -Methode des delete Objekts aus dem Shape Arbeitsblatt entfernt. Es sind keine weiteren Metadaten erforderlich.

Im folgenden Codebeispiel werden alle Shapes aus MyWorksheet gelöscht.

// This deletes all the shapes from "MyWorksheet".
await Excel.run(async (context) => {
    let sheet = context.workbook.worksheets.getItem("MyWorksheet");
    let shapes = sheet.shapes;

    // We'll 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

• Grundlegende Konzepte der Programmierung mit der Excel JavaScript-API
• Arbeiten mit Diagrammen mithilfe der Excel-JavaScript-API