Utiliser des formes à l’aide de l’API JavaScript Excel
Excel définit les formes comme tout objet qui se trouve sur la couche de dessin d’Excel. Cela signifie que tout ce qui est en dehors d’une cellule est une forme. Cet article explique comment utiliser des formes géométriques, des lignes et des images conjointement avec les API Shape et ShapeCollection . Les graphiques sont abordés dans leur propre article, Utiliser des graphiques à l’aide de l’API JavaScript Excel.
L’image suivante montre des formes qui forment un thermomètre.
Créer des formes
Les formes sont créées et stockées dans la collection de formes d’une feuille de calcul (Worksheet.shapes). ShapeCollection a plusieurs .add* méthodes à cet effet. Toutes les formes ont des noms et des ID générés lorsqu’ils sont ajoutés à la collection. Il s’agit respectivement des name propriétés et id . name peut être défini par votre complément pour faciliter la récupération avec la ShapeCollection.getItem(name) méthode .
Les types de formes suivants sont ajoutés à l’aide de la méthode associée.
| Forme | Add, méthode | Signature |
|---|---|---|
| Forme géométrique | addGeometricShape | addGeometricShape(geometricShapeType: Excel.GeometricShapeType): Excel.Shape |
| Image (JPEG ou PNG) | addImage | addImage(base64ImageString: string): Excel.Shape |
| Trait | addLine | addLine(startLeft: number, startTop: number, endLeft: number, endTop: number, connectorType?: Excel.ConnectorType): Excel.Shape |
| Svg | addSvg | addSvg(xml: string): Excel.Shape |
| Zone de texte | addTextBox | addTextBox(text?: string): Excel.Shape |
Formes géométriques
Une forme géométrique est créée avec ShapeCollection.addGeometricShape. Cette méthode prend une énumération GeometricShapeType comme argument.
L’exemple de code suivant crée un rectangle de 150 x 150 pixels nommé « Square » placé à 100 pixels des côtés supérieur et gauche de la feuille de calcul.
// 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();
});
Des images
Les images JPEG, PNG et SVG peuvent être insérées dans une feuille de calcul sous forme de formes. La ShapeCollection.addImage méthode prend une chaîne encodée en base64 comme argument. Il s’agit d’une image JPEG ou PNG sous forme de chaîne. ShapeCollection.addSvg accepte également une chaîne, bien que cet argument soit XML qui définit le graphique.
L’exemple de code suivant montre un fichier image chargé par un FileReader sous forme de chaîne. La chaîne a les métadonnées « base64 », supprimées avant la création de la forme.
// 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
Une ligne est créée avec ShapeCollection.addLine. Cette méthode a besoin des marges gauche et supérieure des points de début et de fin de la ligne. Il faut également une énumération ConnectorType pour spécifier la façon dont la ligne se trie entre les points de terminaison. L’exemple de code suivant crée une ligne droite dans la feuille de calcul.
// 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();
});
Les lignes peuvent être connectées à d’autres objets Shape. Les connectBeginShape méthodes et connectEndShape attachent le début et la fin d’une ligne aux formes aux points de connexion spécifiés. L’emplacement de ces points varie selon la forme, mais peut Shape.connectionSiteCount être utilisé pour vous assurer que votre complément ne se connecte pas à un point hors limites. Une ligne est déconnectée de toutes les formes attachées à l’aide des disconnectBeginShape méthodes et disconnectEndShape .
L’exemple de code suivant connecte la ligne « MyLine » à deux formes nommées « LeftShape » et « RightShape ».
// 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();
});
Déplacer et redimensionner des formes
Les formes se trouvent au-dessus de la feuille de calcul. Leur positionnement est défini par la left propriété et top . Celles-ci agissent comme des marges des bords respectifs de la feuille de calcul, [0, 0] étant le coin supérieur gauche. Celles-ci peuvent être définies directement ou ajustées à partir de leur position actuelle avec les incrementLeft méthodes et incrementTop . La quantité de rotation d’une forme à partir de la position par défaut est également établie de cette manière, la rotation propriété étant la valeur absolue et la incrementRotation méthode d’ajustement de la rotation existante.
La profondeur d’une forme par rapport à d’autres formes est définie par la zorderPosition propriété . Cette valeur est définie à l’aide de la setZOrder méthode , qui prend un ShapeZOrder. setZOrder ajuste l’ordre de la forme actuelle par rapport aux autres formes.
Votre complément dispose de deux options pour modifier la hauteur et la largeur des formes. La définition de la height propriété ou width modifie la dimension spécifiée sans modifier l’autre dimension. scaleHeight et scaleWidth ajustent les dimensions respectives de la forme par rapport à la taille actuelle ou à la taille d’origine (en fonction de la valeur du ShapeScaleType fourni). Un paramètre ShapeScaleFrom facultatif spécifie à partir duquel la forme est mise à l’échelle (coin supérieur gauche, milieu ou coin inférieur droit). Si la propriété a la lockAspectRatio valeur true, les méthodes d’échelle conservent les proportions actuelles de la forme en ajustant également l’autre dimension.
Remarque
Les modifications directes apportées aux height propriétés et width affectent uniquement cette propriété, quelle que soit la valeur de la lockAspectRatio propriété.
L’exemple de code suivant montre une forme mise à l’échelle à 1,25 fois sa taille d’origine et une rotation de 30 degrés.
// 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();
});
Texte dans les formes
Les formes géométriques peuvent contenir du texte. Les formes ont une textFrame propriété de type TextFrame. L’objet TextFrame gère les options d’affichage du texte (telles que les marges et le dépassement de texte). TextFrame.textRange est un objet TextRange avec le contenu du texte et les paramètres de police.
L’exemple de code suivant crée une forme géométrique nommée « Wave » avec le texte « Shape Text ». Il ajuste également les couleurs de la forme et du texte, ainsi que l’alignement horizontal du texte au centre.
// 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();
});
La addTextBox méthode de ShapeCollection crée un GeometricShape de type Rectangle avec un arrière-plan blanc et du texte noir. Il s’agit de la même chose que ce qui est créé par le bouton Zone de texte d’Excel sous l’onglet Insertion . addTextBox prend un argument de chaîne pour définir le texte du TextRange.
L’exemple de code suivant montre la création d’une zone de texte avec le texte « 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();
});
Groupes de formes
Les formes peuvent être regroupées. Cela permet à un utilisateur de les traiter comme une entité unique pour le positionnement, le dimensionnement et d’autres tâches associées. Un ShapeGroup est un type de Shape, de sorte que votre complément traite le groupe comme une forme unique.
L’exemple de code suivant montre trois formes regroupées. L’exemple de code suivant montre que le groupe de formes est déplacé vers la droite de 50 pixels.
// 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();
});
Importante
Les formes individuelles du groupe sont référencées par le biais de la ShapeGroup.shapes propriété , qui est de type GroupShapeCollection. Elles ne sont plus accessibles via la collection de formes de la feuille de calcul après avoir été regroupées. Par exemple, si votre feuille de calcul comporte trois formes et qu’elles ont toutes été regroupées, la méthode de la feuille de shapes.getCount calcul renvoie un nombre de 1.
Exporter des formes sous forme d’images
N’importe quel Shape objet peut être converti en image. Shape.getAsImage retourne une chaîne encodée en base64. Le format de l’image est spécifié en tant qu’énumération PictureFormat passé à getAsImage.
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.
});
Supprimer des formes
Les formes sont supprimées de la feuille de calcul avec la méthode de l’objet Shapedelete . Aucune autre métadonnées n’est nécessaire.
L’exemple de code suivant supprime toutes les formes de MyWorksheet.
// 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();
});