Arbeiten mit Shapes mithilfe der Excel JavaScript-API

Excel definiert Formen als jedes Objekt, das sich auf der Zeichnungsebene von Excel befindet. Das bedeutet, dass es sich bei allen Außerhalb einer Zelle um eine Form handelt. In diesem Artikel wird die Verwendung geometrischer Formen, Linien und Bilder in Verbindung mit den Shape- und ShapeCollection-APIs beschrieben. Diagramme werden in ihrem eigenen Artikel "Arbeiten mit Diagrammen mithilfe der Excel JavaScript-API" behandelt.

Die folgende Abbildung zeigt Formen, die ein Thermometer bilden. Abbildung eines Inometers, das als Excel Form erstellt wurde.

Erstellen von Shapes

Shapes werden durch die Shape-Auflistung (Worksheet.shapes) eines Arbeitsblatts erstellt und gespeichert. ShapeCollection verfügt zu diesem Zweck über mehrere .add* Methoden. Alle Shapes haben Namen und IDs, die für sie generiert werden, wenn sie der Auflistung hinzugefügt werden. Dies sind jeweils die name Eigenschaften id . name kann von Ihrem Add-In für einen 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 verwendet 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 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 nimmt auch eine Zeichenfolge an, 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 werden, 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 die linken und oberen Ränder der Anfangs- und Endpunkte der Zeile. Außerdem wird eine ConnectorType-Enumeration benötigt, um anzugeben, wie die Linie zwischen Endpunkten konstiert 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 Methoden verbinden den Anfang und das Ende einer Linie an Shapes an den angegebenen Verbindungspunkten. Die Positionen dieser Punkte variieren je nach Form, können jedoch Shape.connectionSiteCount verwendet werden, um sicherzustellen, dass Ihr Add-In keine Verbindung mit einem Punkt herstellt, der außerhalb der Grenzen liegt. Eine Linie wird mithilfe der disconnectBeginShape disconnectEndShape Und-Methoden von allen angefügten Formen 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 Eigenschaft und top die left Eigenschaft definiert. Diese dienen als Ränder von den jeweiligen Rändern des Arbeitsblatts, wobei [0, 0] die obere linke Ecke ist. Diese können entweder direkt festgelegt oder an ihrer aktuellen Position mit den incrementLeft Methoden incrementTop angepasst werden. Wie stark eine Form von der Standardposition gedreht wird, wird ebenfalls auf diese Weise festgelegt, wobei die rotation Eigenschaft die absolute Menge ist und die incrementRotation Methode die vorhandene Drehung anpasst.

Die Tiefe eines Shapes im Verhältnis zu anderen Formen wird durch die zorderPosition Eigenschaft definiert. Dies wird mithilfe der setZOrder Methode festgelegt, die ein ShapeZOrder-Objekt verwendet. setZOrder passt die Reihenfolge der aktuellen Form relativ zu den anderen Formen an.

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

Hinweis

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

Das folgende Codebeispiel zeigt eine Form, die 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 haben 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 zum ShapeCollection Erstellen eines GeometricShape Typs Rectangle mit weißem Hintergrund und schwarzem Text. This is the same as what is created by Excel's Text Box button on the Insert tab. addTextBox takes a string argument to set the text of the TextRange.

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. Auf diese Weise kann ein Benutzer sie als eine einzelne Entität für positionierungs-, größen- und andere verwandte Aufgaben behandeln. Eine ShapeGroup ist ein Typ von Shape, sodass Ihr Add-In die Gruppe als einzelne Form behandelt.

Das folgende Codebeispiel zeigt drei Formen, die gruppiert werden. Das nachfolgende Codebeispiel zeigt, dass die Formgruppe 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 verwiesen, die vom Typ GroupShapeCollection ist. Auf sie kann nach der Gruppierung nicht mehr über die Shape-Auflistung des Arbeitsblatts zugegriffen werden. Wenn Ihr Arbeitsblatt beispielsweise drei Formen enthält und alle 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 Format des Bilds 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 Objekts delete 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