Utiliser des formes à l’aide de l’API JavaScript PowerPoint

Cet article explique comment utiliser des formes géométriques, des lignes et des zones de texte conjointement avec les API Shape et ShapeCollection .

Créer des formes

Les formes sont créées et stockées dans la collection de formes d’une diapositive (slide.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.

Formes géométriques

Une forme géométrique est créée avec l’une des surcharges de ShapeCollection.addGeometricShape. Le premier paramètre est une énumération GeometryShapeType ou la chaîne équivalente à l’une des valeurs de l’énumération. Il existe un deuxième paramètre facultatif de type ShapeAddOptions qui peut spécifier la taille initiale de la forme et sa position par rapport aux côtés supérieur et gauche de la diapositive, mesurée en points. Ces propriétés peuvent également être définies après la création de la forme.

L’exemple de code suivant crée un rectangle nommé « Square » placé à 100 points des côtés supérieur et gauche de la diapositive. La méthode retourne un Shape objet .

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

Une ligne est créée avec l’une des surcharges de ShapeCollection.addLine. Le premier paramètre est une énumération ConnectorType ou la chaîne équivalente à l’une des valeurs de l’énumération pour spécifier la façon dont la ligne se trie entre les points de terminaison. Il existe un deuxième paramètre facultatif de type ShapeAddOptions qui peut spécifier les points de début et de fin de la ligne. Ces propriétés peuvent également être définies après la création de la forme. La méthode retourne un Shape objet .

Remarque

Lorsque la forme est une ligne, les top propriétés et left des Shape objets et ShapeAddOptions spécifient le point de départ de la ligne par rapport aux bords supérieur et gauche de la diapositive. Les height propriétés et width spécifient le point de terminaison de la ligne par rapport au point de départ. Par conséquent, le point de terminaison relatif aux bords supérieur et gauche de la diapositive est (top + height) par ().left + width L’unité de mesure de toutes les propriétés est des points et les valeurs négatives sont autorisées.

L’exemple de code suivant crée une ligne droite sur la diapositive.

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

Zones de texte

Une zone de texte est créée avec la méthode addTextBox . Le premier paramètre est le texte qui doit apparaître dans la zone initialement. Il existe un deuxième paramètre facultatif de type ShapeAddOptions qui peut spécifier la taille initiale de la zone de texte et sa position par rapport aux côtés supérieur et gauche de la diapositive. Ces propriétés peuvent également être définies après la création de la forme.

L’exemple de code suivant montre comment créer une zone de texte sur la première diapositive.

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

Déplacer et redimensionner des formes

Les formes se trouvent au-dessus de la diapositive. Leur positionnement est défini par les left propriétés et top . Celles-ci agissent comme des marges des bords respectifs de la diapositive, mesurées en points, avec left: 0 et top: 0 étant le coin supérieur gauche. La taille de la forme est spécifiée par les height propriétés et width . Votre code peut déplacer ou redimensionner la forme en réinitialisant ces propriétés. (Ces propriétés ont une signification légèrement différente lorsque la forme est une ligne. Voir Lignes.)

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 « Accolades » avec le texte « Texte de forme ». Il ajuste également la forme et les couleurs du texte, ainsi que l’alignement vertical du texte au centre.

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

Supprimer des formes

Les formes sont supprimées de la diapositive avec la méthode de l’objet Shapedelete .

L’exemple de code suivant montre comment supprimer des formes.

await PowerPoint.run(async (context) => {
    // Delete all shapes from the first slide.
    const sheet = context.presentation.slides.getItemAt(0);
    const shapes = sheet.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();
});