Partager via


PowerPoint.Shape class

Représente une forme unique dans la diapositive.

S' étend

Remarques

[ Ensemble d’API : PowerPointApi 1.3 ]

Exemples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/powerpoint/shapes/get-shapes-by-type.yaml

// Changes the transparency of every geometric shape in the slide.
await PowerPoint.run(async (context) => {
  // Get the type of shape for every shape in the collection.
  const shapes: PowerPoint.ShapeCollection = context.presentation.slides.getItemAt(0).shapes;
  shapes.load("type");
  await context.sync();

  // Change the shape transparency to be halfway transparent.
  shapes.items.forEach((shape) => {
    if (shape.type === PowerPoint.ShapeType.geometricShape) {
      shape.fill.transparency = 0.5;
    }
  });
  await context.sync();
});

Propriétés

adjustments

Retourne un Adjustments objet qui contient des valeurs d’ajustement pour tous les ajustements de cette forme.

altTextDescription

Description du texte de remplacement de la forme.

Le texte de remplacement fournit des représentations textuelles alternatives des informations contenues dans la forme. Cette information est utile pour les personnes malvoyantes ou cognitives qui peuvent ne pas être en mesure de voir ou de comprendre la forme.

altTextTitle

Titre du texte de remplacement de la forme.

Le texte de remplacement fournit des représentations textuelles alternatives des informations contenues dans la forme. Cette information est utile pour les personnes malvoyantes ou cognitives qui peuvent ne pas être en mesure de voir ou de comprendre la forme. Un titre peut être lu à une personne handicapée et est utilisé pour déterminer si elle souhaite entendre la description du contenu.

context

Contexte de requête associé à l’objet . Cela connecte le processus du complément au processus de l’application hôte Office.

creationId

Obtient l’ID de création de la forme. Retourne null si la forme n’a pas d’ID de création.

customXmlParts

Retourne une collection de parties XML personnalisées dans la forme.

fill

Renvoie la mise en forme de remplissage de cette forme.

group

Retourne le ShapeGroup associé à la forme. Si le type de forme n’est pas group, cette méthode retourne l’erreur GeneralException .

height

Spécifie la hauteur, en points, de la forme. Lève une exception lorsqu’elle InvalidArgument est définie avec une valeur négative.

id

Obtient l’ID unique de la forme.

isDecorative

Représente si la forme est décorative ou non.

Les objets décoratifs ajoutent un intérêt visuel, mais ne sont pas informatifs (par exemple, bordures stylistiques). Personnes utilisant des lecteurs d’écran entendront qu’ils sont décoratifs afin qu’ils sachent qu’ils ne manquent aucune information importante.

left

Distance, en points, entre le côté gauche de la forme et le côté gauche de la diapositive.

level

Retourne le niveau de la forme spécifiée.

  • Un niveau de 0 signifie que la forme ne fait pas partie d’un groupe.

  • Un niveau de 1 signifie que la forme fait partie d’un groupe de niveau supérieur.

  • Un niveau supérieur à 1 indique que la forme est un groupe imbriqué.

lineFormat

Renvoie la mise en forme de ligne de cette forme.

name

Spécifie le nom de cette forme.

parentGroup

Renvoie le groupe parent de cette forme. Si la forme ne fait pas partie d’un groupe, cette méthode retourne l’erreur GeneralException .

placeholderFormat

Retourne les propriétés qui s’appliquent spécifiquement à cet espace réservé. Si le type de forme n’est pas placeholder, cette méthode retourne l’erreur GeneralException .

rotation

Spécifie la rotation, en degrés, de la forme autour de l’axe z. Une valeur positive indique une rotation dans le sens des aiguilles d’une montre, et une valeur négative indique une rotation dans le sens inverse des aiguilles d’une montre.

tags

Retourne une collection de balises dans la forme.

textFrame

Renvoie l’objet PowerPoint.TextFrame de ce Shape. Lève une InvalidArgument exception si la forme ne prend pas en charge un TextFrame.

top

Distance, en points, entre le bord supérieur de la forme et le bord supérieur de la diapositive.

type

Renvoie le type de cette forme. Pour plus d’informations , voir PowerPoint.ShapeType .

visible

Spécifie si la forme est visible.

width

Spécifie la largeur, en points, de la forme. Lève une exception lorsqu’elle InvalidArgument est définie avec une valeur négative.

zOrderPosition

Retourne la position de l’ordre de plan de la forme, avec 0 représentant le bas de la pile de commandes. Chaque forme d’une diapositive a un ordre de plan unique, mais chaque diapositive a également une pile d’ordre de plan unique, de sorte que deux formes sur des diapositives distinctes peuvent avoir le même numéro d’ordre de plan.

Méthode

delete()

Supprime la forme de la collection de formes. Ne fait rien si la forme n’existe pas.

getImageAsBase64(options)

Restitue une image de la forme.

getParentSlide()

Retourne l’objet PowerPoint.Slide parent qui contient ce Shape. Lève une exception si cette forme n’appartient pas à un Slide.

getParentSlideLayout()

Renvoie l’objet Parent PowerPoint.SlideLayout qui contient ce Shape. Lève une exception si cette forme n’appartient pas à un SlideLayout.

getParentSlideLayoutOrNullObject()

Renvoie l’objet Parent PowerPoint.SlideLayout qui contient ce Shape. Si cette forme n’appartient pas à , SlideLayoutun objet avec une isNullObject propriété définie sur true est retourné. Pour plus d’informations, consultez *Méthodes et propriétés OrNullObject.

getParentSlideMaster()

Renvoie l’objet PowerPoint.SlideMaster parent qui contient ce Shape. Lève une exception si cette forme n’appartient pas à un SlideMaster.

getParentSlideMasterOrNullObject()

Renvoie l’objet PowerPoint.SlideMaster parent qui contient ce Shape. Si cette forme n’appartient pas à , SlideMasterun objet avec une isNullObject propriété définie sur true est retourné. Pour plus d’informations, consultez *Méthodes et propriétés OrNullObject.

getParentSlideOrNullObject()

Retourne l’objet PowerPoint.Slide parent qui contient ce Shape. Si cette forme n’appartient pas à , Slideun objet avec une isNullObject propriété définie sur true est retourné. Pour plus d’informations, consultez *Méthodes et propriétés OrNullObject.

getTable()

Renvoie l’objet Table si cette forme est un tableau.

getTextFrameOrNullObject()

Renvoie l’objet PowerPoint.TextFrame de ce Shape. Si la forme ne prend pas en charge un TextFrame, un objet avec une isNullObject propriété définie sur true est retourné. Pour plus d’informations, consultez *Méthodes et propriétés OrNullObject.

load(options)

Files d’attente de la commande pour charger les propriétés de l’objet spécifié. Vous devez contacter context.sync() avant de lire les propriétés.

load(propertyNames)

Files d’attente de la commande pour charger les propriétés de l’objet spécifié. Vous devez contacter context.sync() avant de lire les propriétés.

load(propertyNamesAndPaths)

Files d’attente de la commande pour charger les propriétés de l’objet spécifié. Vous devez contacter context.sync() avant de lire les propriétés.

setHyperlink(options)

Définit un lien hypertexte sur ce Shape avec les options spécifiées. Cela supprime tout lien hypertexte existant sur ce Shape.

setZOrder(position)

Déplace la forme spécifiée vers le haut ou vers le bas z de commande de la collection qui décale devant ou derrière les autres formes.

setZOrder(position)

Déplace la forme spécifiée vers le haut ou vers le bas z de commande de la collection qui décale devant ou derrière les autres formes.

toJSON()

Remplace la méthode JavaScript toJSON() afin de fournir une sortie plus utile lorsqu’un objet API est passé à JSON.stringify(). (JSON.stringify, à son tour, appelle la toJSON méthode de l’objet qui lui est passé.) Alors que l’objet d’origine PowerPoint.Shape est un objet API, la toJSON méthode renvoie un objet JavaScript brut (typé en tant PowerPoint.Interfaces.ShapeDataque ) qui contient des copies superficielles de toutes les propriétés enfants chargées de l’objet d’origine.

Détails de la propriété

adjustments

Retourne un Adjustments objet qui contient des valeurs d’ajustement pour tous les ajustements de cette forme.

readonly adjustments: PowerPoint.Adjustments;

Valeur de la propriété

Remarques

[ Ensemble d’API : PowerPointApi 1.10 ]

altTextDescription

Description du texte de remplacement de la forme.

Le texte de remplacement fournit des représentations textuelles alternatives des informations contenues dans la forme. Cette information est utile pour les personnes malvoyantes ou cognitives qui peuvent ne pas être en mesure de voir ou de comprendre la forme.

altTextDescription: string;

Valeur de la propriété

string

Remarques

[ Ensemble d’API : PowerPointApi 1.10 ]

altTextTitle

Titre du texte de remplacement de la forme.

Le texte de remplacement fournit des représentations textuelles alternatives des informations contenues dans la forme. Cette information est utile pour les personnes malvoyantes ou cognitives qui peuvent ne pas être en mesure de voir ou de comprendre la forme. Un titre peut être lu à une personne handicapée et est utilisé pour déterminer si elle souhaite entendre la description du contenu.

altTextTitle: string;

Valeur de la propriété

string

Remarques

[ Ensemble d’API : PowerPointApi 1.10 ]

context

Contexte de requête associé à l’objet . Cela connecte le processus du complément au processus de l’application hôte Office.

context: RequestContext;

Valeur de la propriété

creationId

Obtient l’ID de création de la forme. Retourne null si la forme n’a pas d’ID de création.

readonly creationId: string | null;

Valeur de la propriété

string | null

Remarques

[ Ensemble d’API : PowerPointApi 1.10 ]

customXmlParts

Retourne une collection de parties XML personnalisées dans la forme.

readonly customXmlParts: PowerPoint.CustomXmlPartCollection;

Valeur de la propriété

Remarques

[ Ensemble d’API : PowerPointApi 1.7 ]

fill

Renvoie la mise en forme de remplissage de cette forme.

readonly fill: PowerPoint.ShapeFill;

Valeur de la propriété

Remarques

[ Ensemble d’API : PowerPointApi 1.4 ]

Exemples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/powerpoint/shapes/get-set-shapes.yaml

// Changes the selected shapes fill color to red.
await PowerPoint.run(async (context) => {
  const shapes: PowerPoint.ShapeScopedCollection = context.presentation.getSelectedShapes();
  const shapeCount = shapes.getCount();
  shapes.load("items/fill/type");
  await context.sync();
  shapes.items.map((shape) => {
    const shapeFillType = shape.fill.type as PowerPoint.ShapeFillType;
    console.log(`Shape ID ${shape.id} original fill type: ${shapeFillType}`);
    shape.fill.setSolidColor("red");
  });
  await context.sync();
});

group

Retourne le ShapeGroup associé à la forme. Si le type de forme n’est pas group, cette méthode retourne l’erreur GeneralException .

readonly group: PowerPoint.ShapeGroup;

Valeur de la propriété

Remarques

[ Ensemble d’API : PowerPointApi 1.8 ]

Exemples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/powerpoint/shapes/group-ungroup-shapes.yaml

await PowerPoint.run(async (context) => {
  // Ungroups the first shape group on the current slide.

  // Get the shapes on the current slide.
  context.presentation.load("slides");
  const slide: PowerPoint.Slide = context.presentation.getSelectedSlides().getItemAt(0);
  slide.load("shapes/items/type,shapes/items/id");
  await context.sync();

  const shapes: PowerPoint.ShapeCollection = 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}`);
});

height

Spécifie la hauteur, en points, de la forme. Lève une exception lorsqu’elle InvalidArgument est définie avec une valeur négative.

height: number;

Valeur de la propriété

number

Remarques

[ Ensemble d’API : PowerPointApi 1.4 ]

Exemples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/powerpoint/shapes/get-set-shapes.yaml

// Arranges the selected shapes in a line from left to right.
await PowerPoint.run(async (context) => {
  const shapes: PowerPoint.ShapeScopedCollection = context.presentation.getSelectedShapes();
  const shapeCount = shapes.getCount();
  shapes.load("items");
  await context.sync();
  let maxHeight = 0;
  shapes.items.map((shape) => {
    shape.load("width,height");
  });
  await context.sync();
  shapes.items.map((shape) => {
    shape.left = currentLeft;
    shape.top = currentTop;
    currentLeft += shape.width;
    if (shape.height > maxHeight) maxHeight = shape.height;
  });
  await context.sync();
  currentLeft = 0;
  if (currentTop > slideHeight - 200) currentTop = 0;
});

id

Obtient l’ID unique de la forme.

readonly id: string;

Valeur de la propriété

string

Remarques

[ Ensemble d’API : PowerPointApi 1.3 ]

isDecorative

Représente si la forme est décorative ou non.

Les objets décoratifs ajoutent un intérêt visuel, mais ne sont pas informatifs (par exemple, bordures stylistiques). Personnes utilisant des lecteurs d’écran entendront qu’ils sont décoratifs afin qu’ils sachent qu’ils ne manquent aucune information importante.

isDecorative: boolean;

Valeur de la propriété

boolean

Remarques

[ Ensemble d’API : PowerPointApi 1.10 ]

left

Distance, en points, entre le côté gauche de la forme et le côté gauche de la diapositive.

left: number;

Valeur de la propriété

number

Remarques

[ Ensemble d’API : PowerPointApi 1.4 ]

Exemples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/powerpoint/shapes/get-set-shapes.yaml

// Arranges the selected shapes in a line from left to right.
await PowerPoint.run(async (context) => {
  const shapes: PowerPoint.ShapeScopedCollection = context.presentation.getSelectedShapes();
  const shapeCount = shapes.getCount();
  shapes.load("items");
  await context.sync();
  let maxHeight = 0;
  shapes.items.map((shape) => {
    shape.load("width,height");
  });
  await context.sync();
  shapes.items.map((shape) => {
    shape.left = currentLeft;
    shape.top = currentTop;
    currentLeft += shape.width;
    if (shape.height > maxHeight) maxHeight = shape.height;
  });
  await context.sync();
  currentLeft = 0;
  if (currentTop > slideHeight - 200) currentTop = 0;
});

level

Retourne le niveau de la forme spécifiée.

  • Un niveau de 0 signifie que la forme ne fait pas partie d’un groupe.

  • Un niveau de 1 signifie que la forme fait partie d’un groupe de niveau supérieur.

  • Un niveau supérieur à 1 indique que la forme est un groupe imbriqué.

readonly level: number;

Valeur de la propriété

number

Remarques

[ Ensemble d’API : PowerPointApi 1.8 ]

lineFormat

Renvoie la mise en forme de ligne de cette forme.

readonly lineFormat: PowerPoint.ShapeLineFormat;

Valeur de la propriété

Remarques

[ Ensemble d’API : PowerPointApi 1.4 ]

name

Spécifie le nom de cette forme.

name: string;

Valeur de la propriété

string

Remarques

[ Ensemble d’API : PowerPointApi 1.4 ]

parentGroup

Renvoie le groupe parent de cette forme. Si la forme ne fait pas partie d’un groupe, cette méthode retourne l’erreur GeneralException .

readonly parentGroup: PowerPoint.Shape;

Valeur de la propriété

Remarques

[ Ensemble d’API : PowerPointApi 1.8 ]

placeholderFormat

Retourne les propriétés qui s’appliquent spécifiquement à cet espace réservé. Si le type de forme n’est pas placeholder, cette méthode retourne l’erreur GeneralException .

readonly placeholderFormat: PowerPoint.PlaceholderFormat;

Valeur de la propriété

Remarques

[ Ensemble d’API : PowerPointApi 1.8 ]

Exemples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/powerpoint/shapes/get-shapes-by-type.yaml

// Gets the placeholder shapes in the slide.
await PowerPoint.run(async (context) => {
  // Get properties for every shape in the collection.
  const shapes: PowerPoint.ShapeCollection = context.presentation.slides.getItemAt(0).shapes;
  shapes.load("type,name");
  await context.sync();

  const placeholderShapes = [];
  console.log(`Number of shapes found: ${shapes.items.length}`);
  shapes.items.forEach((shape) => {
    if (shape.type === PowerPoint.ShapeType.placeholder) {
      // Load placeholderFormat property.
      // PowerPoint throws an exception if you try to load this property on a shape that isn't a placeholder type.
      shape.load("placeholderFormat");
      placeholderShapes.push(shape);
    }
  });
  await context.sync();

  console.log(`Number of placeholder shapes found: ${placeholderShapes.length}`);
  for (let i = 0; i < placeholderShapes.length; i++) {
    let currentPlaceholder: PowerPoint.PlaceholderFormat = placeholderShapes[i].placeholderFormat;
    let placeholderType = currentPlaceholder.type as PowerPoint.PlaceholderType;
    let placeholderContainedType = currentPlaceholder.containedType as PowerPoint.ShapeType;
    console.log(`Shape "${placeholderShapes[i].name}" placeholder properties:`);
    console.log(`\ttype: ${placeholderType}`);
    console.log(`\tcontainedType: ${placeholderContainedType}`);
  }
});

rotation

Spécifie la rotation, en degrés, de la forme autour de l’axe z. Une valeur positive indique une rotation dans le sens des aiguilles d’une montre, et une valeur négative indique une rotation dans le sens inverse des aiguilles d’une montre.

rotation: number;

Valeur de la propriété

number

Remarques

[ Ensemble d’API : PowerPointApi 1.10 ]

tags

Retourne une collection de balises dans la forme.

readonly tags: PowerPoint.TagCollection;

Valeur de la propriété

Remarques

[ Ensemble d’API : PowerPointApi 1.3 ]

textFrame

Renvoie l’objet PowerPoint.TextFrame de ce Shape. Lève une InvalidArgument exception si la forme ne prend pas en charge un TextFrame.

readonly textFrame: PowerPoint.TextFrame;

Valeur de la propriété

Remarques

[ Ensemble d’API : PowerPointApi 1.4 ]

top

Distance, en points, entre le bord supérieur de la forme et le bord supérieur de la diapositive.

top: number;

Valeur de la propriété

number

Remarques

[ Ensemble d’API : PowerPointApi 1.4 ]

Exemples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/powerpoint/shapes/get-set-shapes.yaml

// Arranges the selected shapes in a line from left to right.
await PowerPoint.run(async (context) => {
  const shapes: PowerPoint.ShapeScopedCollection = context.presentation.getSelectedShapes();
  const shapeCount = shapes.getCount();
  shapes.load("items");
  await context.sync();
  let maxHeight = 0;
  shapes.items.map((shape) => {
    shape.load("width,height");
  });
  await context.sync();
  shapes.items.map((shape) => {
    shape.left = currentLeft;
    shape.top = currentTop;
    currentLeft += shape.width;
    if (shape.height > maxHeight) maxHeight = shape.height;
  });
  await context.sync();
  currentLeft = 0;
  if (currentTop > slideHeight - 200) currentTop = 0;
});

type

Renvoie le type de cette forme. Pour plus d’informations , voir PowerPoint.ShapeType .

readonly type: PowerPoint.ShapeType | "Unsupported" | "Image" | "GeometricShape" | "Group" | "Line" | "Table" | "Callout" | "Chart" | "ContentApp" | "Diagram" | "Freeform" | "Graphic" | "Ink" | "Media" | "Model3D" | "Ole" | "Placeholder" | "SmartArt" | "TextBox";

Valeur de la propriété

PowerPoint.ShapeType | "Unsupported" | "Image" | "GeometricShape" | "Group" | "Line" | "Table" | "Callout" | "Chart" | "ContentApp" | "Diagram" | "Freeform" | "Graphic" | "Ink" | "Media" | "Model3D" | "Ole" | "Placeholder" | "SmartArt" | "TextBox"

Remarques

[ Ensemble d’API : PowerPointApi 1.4 ]

Exemples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/powerpoint/shapes/get-shapes-by-type.yaml

// Changes the transparency of every geometric shape in the slide.
await PowerPoint.run(async (context) => {
  // Get the type of shape for every shape in the collection.
  const shapes: PowerPoint.ShapeCollection = context.presentation.slides.getItemAt(0).shapes;
  shapes.load("type");
  await context.sync();

  // Change the shape transparency to be halfway transparent.
  shapes.items.forEach((shape) => {
    if (shape.type === PowerPoint.ShapeType.geometricShape) {
      shape.fill.transparency = 0.5;
    }
  });
  await context.sync();
});

visible

Spécifie si la forme est visible.

visible: boolean;

Valeur de la propriété

boolean

Remarques

[ Ensemble d’API : PowerPointApi 1.10 ]

width

Spécifie la largeur, en points, de la forme. Lève une exception lorsqu’elle InvalidArgument est définie avec une valeur négative.

width: number;

Valeur de la propriété

number

Remarques

[ Ensemble d’API : PowerPointApi 1.4 ]

Exemples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/powerpoint/shapes/get-set-shapes.yaml

// Arranges the selected shapes in a line from left to right.
await PowerPoint.run(async (context) => {
  const shapes: PowerPoint.ShapeScopedCollection = context.presentation.getSelectedShapes();
  const shapeCount = shapes.getCount();
  shapes.load("items");
  await context.sync();
  let maxHeight = 0;
  shapes.items.map((shape) => {
    shape.load("width,height");
  });
  await context.sync();
  shapes.items.map((shape) => {
    shape.left = currentLeft;
    shape.top = currentTop;
    currentLeft += shape.width;
    if (shape.height > maxHeight) maxHeight = shape.height;
  });
  await context.sync();
  currentLeft = 0;
  if (currentTop > slideHeight - 200) currentTop = 0;
});

zOrderPosition

Retourne la position de l’ordre de plan de la forme, avec 0 représentant le bas de la pile de commandes. Chaque forme d’une diapositive a un ordre de plan unique, mais chaque diapositive a également une pile d’ordre de plan unique, de sorte que deux formes sur des diapositives distinctes peuvent avoir le même numéro d’ordre de plan.

readonly zOrderPosition: number;

Valeur de la propriété

number

Remarques

[ Ensemble d’API : PowerPointApi 1.8 ]

Exemples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/powerpoint/shapes/binding-to-shapes.yaml

async function changeZOrder(operation: PowerPoint.ShapeZOrder) {
  // Changes the z-order position of the selected shapes.
  return PowerPoint.run(async (context) => {
    const selectedShapes = context.presentation.getSelectedShapes();
    selectedShapes.load();
    await context.sync();

    if (selectedShapes.items.length === 0) {
      console.log("No shapes are selected.");
    } else {
      let direction = 1; // Start with bottom-most (lowest number).

      // Start with top-most when sending to back or bringing forward.

      switch (operation) {
        case PowerPoint.ShapeZOrder.bringForward:

        case PowerPoint.ShapeZOrder.sendToBack:
          direction = -1; // Reverse direction.

          break;
      }

      // Change the z-order position for each of the selected shapes,

      // starting with the bottom-most when bringing to front or sending backward,

      // or top-most when sending to back or bringing forward,

      // so the selected shapes retain their relative z-order positions after they're changed.

      selectedShapes.items
        .sort((a, b) => (a.zOrderPosition - b.zOrderPosition) * direction)
        .forEach((shape) => {
          try {
            const originalZOrderPosition = shape.zOrderPosition;
            shape.setZOrder(operation);

            console.log(`Changed z-order of shape ${shape.id}.`);
          } catch (err) {
            console.log(`Unable to change z-order of shape ${shape.id}. ${err.message}`);
          }
        });

      await context.sync();
    }
  });
}

Détails de la méthode

delete()

Supprime la forme de la collection de formes. Ne fait rien si la forme n’existe pas.

delete(): void;

Retourne

void

Remarques

[ Ensemble d’API : PowerPointApi 1.3 ]

Exemples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/powerpoint/shapes/shapes.yaml

// This function gets the collection of shapes on the first slide,
// and then iterates through them, deleting each one.
await PowerPoint.run(async (context) => {
  const slide: PowerPoint.Slide = context.presentation.slides.getItemAt(0);
  const shapes: PowerPoint.ShapeCollection = slide.shapes;

  // Load all the shapes in the collection without loading their properties.
  shapes.load("items/$none");

  await context.sync();

  shapes.items.forEach((shape) => shape.delete());

  await context.sync();
});

getImageAsBase64(options)

Restitue une image de la forme.

getImageAsBase64(options?: PowerPoint.ShapeGetImageOptions): OfficeExtension.ClientResult<string>;

Paramètres

options
PowerPoint.ShapeGetImageOptions

Facultatif. Options permettant de spécifier les propriétés d’image de sortie souhaitées.

Retourne

Chaîne encodée en Base64 de l’image de forme dans le format spécifié.

Remarques

[ Ensemble d’API : PowerPointApi 1.10 ]

getParentSlide()

Retourne l’objet PowerPoint.Slide parent qui contient ce Shape. Lève une exception si cette forme n’appartient pas à un Slide.

getParentSlide(): PowerPoint.Slide;

Retourne

Remarques

[ Ensemble d’API : PowerPointApi 1.5 ]

getParentSlideLayout()

Renvoie l’objet Parent PowerPoint.SlideLayout qui contient ce Shape. Lève une exception si cette forme n’appartient pas à un SlideLayout.

getParentSlideLayout(): PowerPoint.SlideLayout;

Retourne

Remarques

[ Ensemble d’API : PowerPointApi 1.5 ]

getParentSlideLayoutOrNullObject()

Renvoie l’objet Parent PowerPoint.SlideLayout qui contient ce Shape. Si cette forme n’appartient pas à , SlideLayoutun objet avec une isNullObject propriété définie sur true est retourné. Pour plus d’informations, consultez *Méthodes et propriétés OrNullObject.

getParentSlideLayoutOrNullObject(): PowerPoint.SlideLayout;

Retourne

Remarques

[ Ensemble d’API : PowerPointApi 1.5 ]

getParentSlideMaster()

Renvoie l’objet PowerPoint.SlideMaster parent qui contient ce Shape. Lève une exception si cette forme n’appartient pas à un SlideMaster.

getParentSlideMaster(): PowerPoint.SlideMaster;

Retourne

Remarques

[ Ensemble d’API : PowerPointApi 1.5 ]

getParentSlideMasterOrNullObject()

Renvoie l’objet PowerPoint.SlideMaster parent qui contient ce Shape. Si cette forme n’appartient pas à , SlideMasterun objet avec une isNullObject propriété définie sur true est retourné. Pour plus d’informations, consultez *Méthodes et propriétés OrNullObject.

getParentSlideMasterOrNullObject(): PowerPoint.SlideMaster;

Retourne

Remarques

[ Ensemble d’API : PowerPointApi 1.5 ]

getParentSlideOrNullObject()

Retourne l’objet PowerPoint.Slide parent qui contient ce Shape. Si cette forme n’appartient pas à , Slideun objet avec une isNullObject propriété définie sur true est retourné. Pour plus d’informations, consultez *Méthodes et propriétés OrNullObject.

getParentSlideOrNullObject(): PowerPoint.Slide;

Retourne

Remarques

[ Ensemble d’API : PowerPointApi 1.5 ]

getTable()

Renvoie l’objet Table si cette forme est un tableau.

getTable(): PowerPoint.Table;

Retourne

Remarques

[ Ensemble d’API : PowerPointApi 1.8 ]

Exemples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/powerpoint/shapes/add-modify-tables.yaml

// Gets the table from a shape.
await PowerPoint.run(async (context) => {
  const shapes = context.presentation.getSelectedShapes();
  const shapeCount = shapes.getCount();
  shapes.load("items");
  await context.sync();

  if (shapeCount.value > 0) {
    const shape = shapes.getItemAt(0);
    shape.load("type");
    await context.sync();

    // The shape type can indicate whether the shape is a table.
    const isTable = shape.type === PowerPoint.ShapeType.table;

    if (isTable) {
      // Get the Table object for the Shape which is a table.
      const table = shape.getTable();
      table.load();
      await context.sync();

      // Get the Table row and column count.
      console.log("Table RowCount: " + table.rowCount + " and columnCount: " + table.columnCount);
    } else console.log("Selected shape isn't table.");
  } else console.log("No shape selected.");
});

getTextFrameOrNullObject()

Renvoie l’objet PowerPoint.TextFrame de ce Shape. Si la forme ne prend pas en charge un TextFrame, un objet avec une isNullObject propriété définie sur true est retourné. Pour plus d’informations, consultez *Méthodes et propriétés OrNullObject.

getTextFrameOrNullObject(): PowerPoint.TextFrame;

Retourne

Remarques

[ Ensemble d’API : PowerPointApi 1.10 ]

load(options)

Files d’attente de la commande pour charger les propriétés de l’objet spécifié. Vous devez contacter context.sync() avant de lire les propriétés.

load(options?: PowerPoint.Interfaces.ShapeLoadOptions): PowerPoint.Shape;

Paramètres

options
PowerPoint.Interfaces.ShapeLoadOptions

Fournit des options pour les propriétés de l’objet à charger.

Retourne

load(propertyNames)

Files d’attente de la commande pour charger les propriétés de l’objet spécifié. Vous devez contacter context.sync() avant de lire les propriétés.

load(propertyNames?: string | string[]): PowerPoint.Shape;

Paramètres

propertyNames

string | string[]

Chaîne délimitée par des virgules ou tableau de chaînes qui spécifient les propriétés à charger.

Retourne

load(propertyNamesAndPaths)

Files d’attente de la commande pour charger les propriétés de l’objet spécifié. Vous devez contacter context.sync() avant de lire les propriétés.

load(propertyNamesAndPaths?: {
            select?: string;
            expand?: string;
        }): PowerPoint.Shape;

Paramètres

propertyNamesAndPaths

{ select?: string; expand?: string; }

propertyNamesAndPaths.select est une chaîne délimitée par des virgules qui spécifie les propriétés à charger, et propertyNamesAndPaths.expand est une chaîne délimitée par des virgules qui spécifie les propriétés de navigation à charger.

Retourne

Définit un lien hypertexte sur ce Shape avec les options spécifiées. Cela supprime tout lien hypertexte existant sur ce Shape.

setHyperlink(options?: PowerPoint.HyperlinkAddOptions): PowerPoint.Hyperlink;

Paramètres

options
PowerPoint.HyperlinkAddOptions

Facultatif. Options du lien hypertexte.

Retourne

Objet PowerPoint.Hyperlink nouvellement créé.

Remarques

[ Ensemble d’API : PowerPointApi 1.10 ]

setZOrder(position)

Déplace la forme spécifiée vers le haut ou vers le bas z de commande de la collection qui décale devant ou derrière les autres formes.

setZOrder(position: PowerPoint.ShapeZOrder): void;

Paramètres

position
PowerPoint.ShapeZOrder

Spécifie comment déplacer la forme dans la pile d’ordre de plan. Utilise l’enum ShapeZOrder .

Retourne

void

Remarques

[ Ensemble d’API : PowerPointApi 1.8 ]

Exemples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/powerpoint/shapes/binding-to-shapes.yaml

async function changeZOrder(operation: PowerPoint.ShapeZOrder) {
  // Changes the z-order position of the selected shapes.
  return PowerPoint.run(async (context) => {
    const selectedShapes = context.presentation.getSelectedShapes();
    selectedShapes.load();
    await context.sync();

    if (selectedShapes.items.length === 0) {
      console.log("No shapes are selected.");
    } else {
      let direction = 1; // Start with bottom-most (lowest number).

      // Start with top-most when sending to back or bringing forward.

      switch (operation) {
        case PowerPoint.ShapeZOrder.bringForward:

        case PowerPoint.ShapeZOrder.sendToBack:
          direction = -1; // Reverse direction.

          break;
      }

      // Change the z-order position for each of the selected shapes,

      // starting with the bottom-most when bringing to front or sending backward,

      // or top-most when sending to back or bringing forward,

      // so the selected shapes retain their relative z-order positions after they're changed.

      selectedShapes.items
        .sort((a, b) => (a.zOrderPosition - b.zOrderPosition) * direction)
        .forEach((shape) => {
          try {
            const originalZOrderPosition = shape.zOrderPosition;
            shape.setZOrder(operation);

            console.log(`Changed z-order of shape ${shape.id}.`);
          } catch (err) {
            console.log(`Unable to change z-order of shape ${shape.id}. ${err.message}`);
          }
        });

      await context.sync();
    }
  });
}

setZOrder(position)

Déplace la forme spécifiée vers le haut ou vers le bas z de commande de la collection qui décale devant ou derrière les autres formes.

setZOrder(position: "BringForward" | "BringToFront" | "SendBackward" | "SendToBack"): void;

Paramètres

position

"BringForward" | "BringToFront" | "SendBackward" | "SendToBack"

Spécifie comment déplacer la forme dans la pile d’ordre de plan. Utilise l’enum ShapeZOrder .

Retourne

void

Remarques

[ Ensemble d’API : PowerPointApi 1.8 ]

toJSON()

Remplace la méthode JavaScript toJSON() afin de fournir une sortie plus utile lorsqu’un objet API est passé à JSON.stringify(). (JSON.stringify, à son tour, appelle la toJSON méthode de l’objet qui lui est passé.) Alors que l’objet d’origine PowerPoint.Shape est un objet API, la toJSON méthode renvoie un objet JavaScript brut (typé en tant PowerPoint.Interfaces.ShapeDataque ) qui contient des copies superficielles de toutes les propriétés enfants chargées de l’objet d’origine.

toJSON(): PowerPoint.Interfaces.ShapeData;

Retourne