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 .

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

Regrouper et dissocier des formes

Dans PowerPoint, vous pouvez regrouper plusieurs formes et les traiter comme une seule forme. Vous pouvez ensuite dissocier les formes groupées. Pour en savoir plus sur le regroupement d’objets dans l’interface utilisateur De PowerPoint, voir Regrouper ou dissocier des formes, des images ou d’autres objets.

Regrouper des formes

Pour regrouper des formes avec l’API JavaScript, utilisez ShapeCollection.addGroup.

L’exemple de code suivant montre comment regrouper des formes existantes de type GeometricShape trouvées sur la diapositive active.

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

Dissocier les formes

Pour dissocier des formes avec l’API JavaScript, obtenez la propriété group à partir de l’objet du Shape groupe, puis appelez ShapeGroup.ungroup.

L’exemple de code suivant montre comment dissocier le premier groupe de formes trouvé sur la diapositive active.

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

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

Voir aussi

• Utiliser des tables à l’aide de l’API JavaScript PowerPoint
• Lier des formes dans une présentation PowerPoint
• Regrouper ou dissocier des formes, des images ou d’autres objets