ExcelScript.Shape interface

Référence

Paquet:: ExcelScript

Représente un objet de forme générique dans la feuille de calcul. Une forme peut être une forme géométrique, une ligne, un groupe de formes, etc.

Remarques

Exemples

/**
 * This script creates a hexagon shape on the current worksheet.
 */
function main(workbook: ExcelScript.Workbook) {
  const currentSheet = workbook.getActiveWorksheet();
  const hexagon: ExcelScript.Shape = 
    currentSheet.addGeometricShape(ExcelScript.GeometricShapeType.hexagon);
  
  // Set the hexagon size to 40x40 pixels.
  hexagon.setHeight(40);
  hexagon.setWidth(40);

  // Position the hexagon at [100,100] pixels.
  hexagon.setLeft(100);
  hexagon.setTop(100);
}

Méthodes

copyTo(destinationSheet)	Copie et colle un `Shape` objet. La forme collée est copiée au même emplacement en pixels que cette forme.
delete()	Supprime la forme à partir de la feuille de calcul.
getAltTextDescription()	Spécifie le texte de description de remplacement d’un `Shape` objet.
getAltTextTitle()	Spécifie le texte de titre de remplacement d’un `Shape` objet.
getAsImage(format)	Convertit la forme à une image et renvoie l’image comme une chaîne codée en base 64. La résolution est 96. Les seuls formats pris en charge sont `ExcelScript.PictureFormat.BMP`,`ExcelScript.PictureFormat.PNG` ,`ExcelScript.PictureFormat.JPEG` et .`ExcelScript.PictureFormat.GIF`
getConnectionSiteCount()	Renvoie le nombre de sites de connexion sur la forme spécifiée.
getFill()	Renvoie la mise en forme de remplissage de cette forme.
getGeometricShape()	Renvoie la Forme géométrique associée à la forme. Une erreur sera lancée si le type de forme n’est pas "GeometricShape".
getGeometricShapeType()	Spécifie le type de forme géométrique de cette forme géométrique. Pour plus d’informations, consultez `ExcelScript.GeometricShapeType` . Renvoie `null` si le type de forme n’est pas « GeometricShape ».
getGroup()	Renvoie le groupe de la Forme associée à la forme. Une erreur sera lancée si le type de forme n’est pas "GroupShape".
getHeight()	Spécifie la hauteur, en points, de la forme. Lève une exception lorsqu’elle `InvalidArgument` est définie avec une valeur négative ou zéro comme entrée.
getId()	Spécifie l’identificateur de forme.
getImage()	Renvoie l’image associé à la forme. Une erreur sera lancée si le type de forme n’est pas "Image".
getImageAsBase64(format)	Convertit la forme à une image et renvoie l’image comme une chaîne codée en base 64. La résolution est 96. Les seuls formats pris en charge sont `ExcelScript.PictureFormat.BMP`,`ExcelScript.PictureFormat.PNG` ,`ExcelScript.PictureFormat.JPEG` et .`ExcelScript.PictureFormat.GIF`
getLeft()	La distance, en points, entre le côté gauche du graphique et l’origine de la feuille de calcul. Lève une exception lorsqu’elle `InvalidArgument` est définie avec une valeur négative en tant qu’entrée.
getLevel()	Spécifie le niveau de la forme spécifiée. Par exemple, un niveau de 0 signifie que la forme ne fait pas partie d’un groupe, un niveau de la forme 1 signifie fait partie d’un groupe de niveau supérieur et un niveau de 2, la forme fait partie d’un groupe sous-blocs de niveau supérieur.
getLine()	Renvoie l’image associée à la forme. Une erreur sera lancée si le type de forme n’est pas "Ligne".
getLineFormat()	Renvoie la mise en forme de ligne de cette forme.
getLockAspectRatio()	Spécifie si les proportions de cette forme sont verrouillées.
getName()	Spécifie le nom de la forme.
getParentGroup()	Spécifie le groupe parent de cette forme.
getPlacement()	Représente la manière dont l’objet est attaché aux cellules en dessous.
getRotation()	Spécifie la rotation, en degrés, de la forme.
getTextFrame()	Renvoie l’objet textFrame d’une forme.
getTop()	La distance, en points, du bord supérieur de l’objet au bord supérieur de la feuille de calcul. Lève une exception lorsqu’elle `InvalidArgument` est définie avec une valeur négative en tant qu’entrée.
getType()	Renvoie le type de cette forme. Pour plus d’informations, consultez `ExcelScript.ShapeType` .
getVisible()	Spécifie si la forme est visible.
getWidth()	Spécifie la largeur, en points, de la forme. Lève une exception lorsqu’elle `InvalidArgument` est définie avec une valeur négative ou zéro comme entrée.
getZOrderPosition()	Renvoie la position de la forme spécifiée dans l’ordre z, valeur z de commande de la forme tout en bas est égal à 0.
incrementLeft(increment)	Déplace horizontalement la forme spécifiée selon le nombre de points indiqué.
incrementRotation(increment)	Fait pivoter la forme spécifiée dans le sens des aiguilles d’une montre, selon le nombre de degrés spécifié, autour de l'axe z. Utilisez la `rotation` propriété pour définir la rotation absolue de la forme.
incrementTop(increment)	Décale vers le haut la forme spécifiée selon le nombre de points spécifié.
scaleHeight(scaleFactor, scaleType, scaleFrom)	Met la hauteur de la forme à l’échelle en utilisant un facteur spécifié. Pour des images, vous pouvez indiquer si vous souhaitez mettre la forme à l’échelle par rapport à la taille d’origine ou la taille actuelle. Les formes autres que des images sont toujours mis à l’échelle par rapport à leur hauteur actuelle.
scaleWidth(scaleFactor, scaleType, scaleFrom)	Met la largeur de la forme à l’échelle en utilisant un facteur spécifié. Pour des images, vous pouvez indiquer si vous souhaitez mettre la forme à l’échelle par rapport à la taille d’origine ou la taille actuelle. Les formes autres que des images sont toujours mis à l’échelle par rapport à leur largeur actuelle.
setAltTextDescription(altTextDescription)	Spécifie le texte de description de remplacement d’un `Shape` objet.
setAltTextTitle(altTextTitle)	Spécifie le texte de titre de remplacement d’un `Shape` objet.
setGeometricShapeType(geometricShapeType)	Spécifie le type de forme géométrique de cette forme géométrique. Pour plus d’informations, consultez `ExcelScript.GeometricShapeType` . Renvoie `null` si le type de forme n’est pas « GeometricShape ».
setHeight(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 ou zéro comme entrée.
setLeft(left)	La distance, en points, entre le côté gauche du graphique et l’origine de la feuille de calcul. Lève une exception lorsqu’elle `InvalidArgument` est définie avec une valeur négative en tant qu’entrée.
setLockAspectRatio(lockAspectRatio)	Spécifie si les proportions de cette forme sont verrouillées.
setName(name)	Spécifie le nom de la forme.
setPlacement(placement)	Représente la manière dont l’objet est attaché aux cellules en dessous.
setRotation(rotation)	Spécifie la rotation, en degrés, de la forme.
setTop(top)	La distance, en points, du bord supérieur de l’objet au bord supérieur de la feuille de calcul. Lève une exception lorsqu’elle `InvalidArgument` est définie avec une valeur négative en tant qu’entrée.
setVisible(visible)	Spécifie si la forme est visible.
setWidth(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 ou zéro comme entrée.
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.

Détails de la méthode

copyTo(destinationSheet)

Copie et colle un Shape objet. La forme collée est copiée au même emplacement en pixels que cette forme.

copyTo(destinationSheet?: Worksheet | string): Shape;

Paramètres

destinationSheet: ExcelScript.Worksheet | string

Feuille dans laquelle l’objet de forme sera collé. La valeur par défaut est la feuille de calcul de la forme copiée.

Retours

ExcelScript.Shape

delete()

Supprime la forme à partir de la feuille de calcul.

delete(): void;

Retours

void

Exemples

/**
 * This script deletes all the shapes on the current worksheet.
 */
function main(workbook: ExcelScript.Workbook) {
  // Get the collection of shapes on the currently selected worksheet.
  const shapes = workbook.getActiveWorksheet().getShapes();

  // Remove each shape.
  shapes.forEach(shape =>{
    shape.delete();
  });
}

getAltTextDescription()

Spécifie le texte de description de remplacement d’un Shape objet.

getAltTextDescription(): string;

Retours

string

getAltTextTitle()

Spécifie le texte de titre de remplacement d’un Shape objet.

getAltTextTitle(): string;

Retours

string

getAsImage(format)

Avertissement

Cette API est à présent déconseillée.

Use getImageAsBase64 instead.

Convertit la forme à une image et renvoie l’image comme une chaîne codée en base 64. La résolution est 96. Les seuls formats pris en charge sont ExcelScript.PictureFormat.BMP,ExcelScript.PictureFormat.PNG ,ExcelScript.PictureFormat.JPEG et .ExcelScript.PictureFormat.GIF

getAsImage(format: PictureFormat): string;

Paramètres

format: ExcelScript.PictureFormat

Spécifie le format de l’image.

Retours

string

Exemples

/**
 * This script creates a star shape with the value from cell A1.
 * It then returns the image as a base64-encoded string. 
 * This string would be used as part of a Power Automate flow to add the image elsewhere.
 */
function main(workbook: ExcelScript.Workbook) {
  // Get the value of A1 from the worksheet named Sheet1.
  const sheet = workbook.getWorksheet("Sheet1");
  const value = sheet.getRange("A1").getValue();

  // Create a Shape object that looks like a 5-pointed star.
  const star = sheet.addGeometricShape(ExcelScript.GeometricShapeType.star5);

  // Set the text of star and make sure the shape fits the text.
  const textFrame = star.getTextFrame();
  textFrame.getTextRange().setText(value.toString());
  textFrame.setAutoSizeSetting(ExcelScript.ShapeAutoSize.autoSizeShapeToFitText);

  // Return the shape as a PNG image represented by a base64-encoded string.
  return star.getAsImage(ExcelScript.PictureFormat.png);
}

getConnectionSiteCount()

Renvoie le nombre de sites de connexion sur la forme spécifiée.

getConnectionSiteCount(): number;

Retours

number

getFill()

Renvoie la mise en forme de remplissage de cette forme.

getFill(): ShapeFill;

Retours

ExcelScript.ShapeFill

getGeometricShape()

Renvoie la Forme géométrique associée à la forme. Une erreur sera lancée si le type de forme n’est pas "GeometricShape".

getGeometricShape(): GeometricShape;

Retours

ExcelScript.GeometricShape

getGeometricShapeType()

Spécifie le type de forme géométrique de cette forme géométrique. Pour plus d’informations, consultez ExcelScript.GeometricShapeType . Renvoie null si le type de forme n’est pas « GeometricShape ».

getGeometricShapeType(): GeometricShapeType;

Retours

ExcelScript.GeometricShapeType

getGroup()

Renvoie le groupe de la Forme associée à la forme. Une erreur sera lancée si le type de forme n’est pas "GroupShape".

getGroup(): ShapeGroup;

Retours

ExcelScript.ShapeGroup

getHeight()

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

getHeight(): number;

Retours

number

getId()

Spécifie l’identificateur de forme.

getId(): string;

Retours

string

getImage()

Renvoie l’image associé à la forme. Une erreur sera lancée si le type de forme n’est pas "Image".

getImage(): Image;

Retours

ExcelScript.Image

Exemples

/**
 * This script transfers an image from one worksheet to another.
 */
function main(workbook: ExcelScript.Workbook)
{
  // Get the worksheet with the image on it.
  let firstWorksheet = workbook.getWorksheet("FirstSheet");

  // Get the first image from the worksheet.
  // If a script added the image, you could add a name to make it easier to find.
  let image: ExcelScript.Image;
  firstWorksheet.getShapes().forEach((shape, index) => {
    if (shape.getType() === ExcelScript.ShapeType.image) {
      image = shape.getImage();
      return;
    }
  });

  // Copy the image to another worksheet.
  image.getShape().copyTo("SecondSheet");
}

getImageAsBase64(format)

getImageAsBase64(format: PictureFormat): string;

Paramètres

format: ExcelScript.PictureFormat

Spécifie le format de l’image.

Retours

string

getLeft()

La distance, en points, entre le côté gauche du graphique et l’origine de la feuille de calcul. Lève une exception lorsqu’elle InvalidArgument est définie avec une valeur négative en tant qu’entrée.

getLeft(): number;

Retours

number

getLevel()

Spécifie le niveau de la forme spécifiée. Par exemple, un niveau de 0 signifie que la forme ne fait pas partie d’un groupe, un niveau de la forme 1 signifie fait partie d’un groupe de niveau supérieur et un niveau de 2, la forme fait partie d’un groupe sous-blocs de niveau supérieur.

getLevel(): number;

Retours

number

getLine()

Renvoie l’image associée à la forme. Une erreur sera lancée si le type de forme n’est pas "Ligne".

getLine(): Line;

Retours

ExcelScript.Line

Exemples

/**
 * This script adds a line that goes from cell B2 to cell F4 on the current worksheet.
 */ 
function main(workbook: ExcelScript.Workbook) {
  // Get the current worksheet.
  const sheet = workbook.getActiveWorksheet();

  // Get the ranges for the two cells.
  const b2Range = sheet.getRange("B2");
  const f4Range = sheet.getRange("F4");

  // Add a straight line that connects the top-left corners of both cells.
  const newShape = sheet.addLine(
    b2Range.getLeft(),
    b2Range.getTop(),
    f4Range.getLeft(),
    f4Range.getTop(),
    ExcelScript.ConnectorType.straight);

  // Add an open arrowhead to the end of the line, such that it points at F4.
  const line = newShape.getLine();
  line.setEndArrowheadStyle(ExcelScript.ArrowheadStyle.open);
}

getLineFormat()

Renvoie la mise en forme de ligne de cette forme.

getLineFormat(): ShapeLineFormat;

Retours

ExcelScript.ShapeLineFormat

getLockAspectRatio()

Spécifie si les proportions de cette forme sont verrouillées.

getLockAspectRatio(): boolean;

Retours

boolean

getName()

Spécifie le nom de la forme.

getName(): string;

Retours

string

getParentGroup()

Spécifie le groupe parent de cette forme.

getParentGroup(): Shape;

Retours

ExcelScript.Shape

getPlacement()

Représente la manière dont l’objet est attaché aux cellules en dessous.

getPlacement(): Placement;

Retours

ExcelScript.Placement

getRotation()

Spécifie la rotation, en degrés, de la forme.

getRotation(): number;

Retours

number

getTextFrame()

Renvoie l’objet textFrame d’une forme.

getTextFrame(): TextFrame;

Retours

ExcelScript.TextFrame

Exemples

/**
 * This script creates a star shape with the value from cell A1.
 */
function main(workbook: ExcelScript.Workbook) {
  // Get the value of A1 from the worksheet named Sheet1.
  const sheet = workbook.getWorksheet("Sheet1");
  const value = sheet.getRange("A1").getValue();

  // Create a Shape object that looks like a 5-pointed star.
  const star = sheet.addGeometricShape(ExcelScript.GeometricShapeType.star5);

  // Set the text of star and make sure the shape fits the text.
  const textFrame = star.getTextFrame();
  textFrame.getTextRange().setText(value.toString());
  textFrame.setAutoSizeSetting(ExcelScript.ShapeAutoSize.autoSizeShapeToFitText);
}

getTop()

La distance, en points, du bord supérieur de l’objet au bord supérieur de la feuille de calcul. Lève une exception lorsqu’elle InvalidArgument est définie avec une valeur négative en tant qu’entrée.

getTop(): number;

Retours

number

getType()

Renvoie le type de cette forme. Pour plus d’informations, consultez ExcelScript.ShapeType .

getType(): ShapeType;

Retours

ExcelScript.ShapeType

getVisible()

Spécifie si la forme est visible.

getVisible(): boolean;

Retours

boolean

getWidth()

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

getWidth(): number;

Retours

number

getZOrderPosition()

Renvoie la position de la forme spécifiée dans l’ordre z, valeur z de commande de la forme tout en bas est égal à 0.

getZOrderPosition(): number;

Retours

number

incrementLeft(increment)

Déplace horizontalement la forme spécifiée selon le nombre de points indiqué.

incrementLeft(increment: number): void;

Paramètres

increment: number

L’incrément, en points, la forme est déplacée horizontalement. Une valeur positive déplace la forme vers la droite et une valeur négative la déplace vers la gauche. Si la feuille est orientée de droite à gauche, cela est inversé : les valeurs positives déplacent la forme vers la gauche et les valeurs négatives la déplacent vers la droite.

Retours

void

incrementRotation(increment)

Fait pivoter la forme spécifiée dans le sens des aiguilles d’une montre, selon le nombre de degrés spécifié, autour de l'axe z. Utilisez la rotation propriété pour définir la rotation absolue de la forme.

incrementRotation(increment: number): void;

Paramètres

increment: number

Nombre de degrés de rotation de la forme. Une valeur positive fait pivoter la forme dans le sens des aiguilles d’une montre et une valeur négative la fait pivoter dans le sens inverse des aiguilles d’une montre.

Retours

void

incrementTop(increment)

Décale vers le haut la forme spécifiée selon le nombre de points spécifié.

incrementTop(increment: number): void;

Paramètres

increment: number

L’incrément, en points, la forme est déplacée verticalement. Une valeur positive déplace la forme vers le bas et une valeur négative la déplace vers le haut.

Retours

void

scaleHeight(scaleFactor, scaleType, scaleFrom)

Met la hauteur de la forme à l’échelle en utilisant un facteur spécifié. Pour des images, vous pouvez indiquer si vous souhaitez mettre la forme à l’échelle par rapport à la taille d’origine ou la taille actuelle. Les formes autres que des images sont toujours mis à l’échelle par rapport à leur hauteur actuelle.

scaleHeight(
            scaleFactor: number,
            scaleType: ShapeScaleType,
            scaleFrom?: ShapeScaleFrom
        ): void;

Paramètres

scaleFactor: number

Indique le rapport entre la hauteur de la forme redimensionnée et sa hauteur actuelle ou originale.

scaleType: ExcelScript.ShapeScaleType

Spécifie si la forme est mise à l’échelle par rapport à sa taille d’origine ou actuelle. L’option de mise à l’échelle de taille d’origine fonctionne uniquement pour les images.

scaleFrom: ExcelScript.ShapeScaleFrom

Facultatif. Spécifie la partie de la forme qui conserve sa position lorsque le forme est mise à l'échelle. S’il est omis, il représente le coin supérieur gauche de la forme conserve sa position.

Retours

void

scaleWidth(scaleFactor, scaleType, scaleFrom)

Met la largeur de la forme à l’échelle en utilisant un facteur spécifié. Pour des images, vous pouvez indiquer si vous souhaitez mettre la forme à l’échelle par rapport à la taille d’origine ou la taille actuelle. Les formes autres que des images sont toujours mis à l’échelle par rapport à leur largeur actuelle.

scaleWidth(
            scaleFactor: number,
            scaleType: ShapeScaleType,
            scaleFrom?: ShapeScaleFrom
        ): void;

Paramètres

scaleFactor: number

Indique le rapport de la largeur de la forme redimensionnée sur sa largeur actuelle ou originale.

scaleType: ExcelScript.ShapeScaleType

Spécifie si la forme est mise à l’échelle par rapport à sa taille d’origine ou actuelle. L’option de mise à l’échelle de taille d’origine fonctionne uniquement pour les images.

scaleFrom: ExcelScript.ShapeScaleFrom

Retours

void

setAltTextDescription(altTextDescription)

Spécifie le texte de description de remplacement d’un Shape objet.

setAltTextDescription(altTextDescription: string): void;

Paramètres

altTextDescription: string

Retours

void

setAltTextTitle(altTextTitle)

Spécifie le texte de titre de remplacement d’un Shape objet.

setAltTextTitle(altTextTitle: string): void;

Paramètres

altTextTitle: string

Retours

void

setGeometricShapeType(geometricShapeType)

setGeometricShapeType(geometricShapeType: GeometricShapeType): void;

Paramètres

geometricShapeType: ExcelScript.GeometricShapeType

Retours

void

setHeight(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 ou zéro comme entrée.

setHeight(height: number): void;

Paramètres

height: number

Retours

void

setLeft(left)

setLeft(left: number): void;

Paramètres

left: number

Retours

void

setLockAspectRatio(lockAspectRatio)

Spécifie si les proportions de cette forme sont verrouillées.

setLockAspectRatio(lockAspectRatio: boolean): void;

Paramètres

lockAspectRatio: boolean

Retours

void

setName(name)

Spécifie le nom de la forme.

setName(name: string): void;

Paramètres

name: string

Retours

void

Exemples

/**
 * This script creates a triangle shape on the current worksheet and names it "TRI".
 */
function main(workbook: ExcelScript.Workbook) {
  const currentSheet = workbook.getActiveWorksheet();
  const triangle: ExcelScript.Shape = 
    currentSheet.addGeometricShape(ExcelScript.GeometricShapeType.triangle);
  
  triangle.setName("TRI");
}

setPlacement(placement)

Représente la manière dont l’objet est attaché aux cellules en dessous.

setPlacement(placement: Placement): void;

Paramètres

placement: ExcelScript.Placement

Retours

void

Exemples

/**
 * This script creates a diamond shape at cell C3.
 * The shape moves and resizes as the grid underneath it changes.
 */
function main(workbook: ExcelScript.Workbook) {
  // Get cell C3 in the current worksheet.
  const sheet = workbook.getActiveWorksheet();
  const cell = sheet.getRange("C3");

  // Create a diamond that slightly overlaps the cell C3.
  const diamond = sheet.addGeometricShape(ExcelScript.GeometricShapeType.diamond);
  // Set each dimension so that the shape extends 5 pixels beyond the cell borders.
  diamond.setLeft(cell.getLeft() - 5);
  diamond.setTop(cell.getTop() - 5);
  diamond.setHeight(cell.getHeight() + 10);
  diamond.setWidth(cell.getWidth() + 10);

  // Set the placement of the shape so that it resizes and moves with the grid.
  diamond.setPlacement(ExcelScript.Placement.twoCell);
}

setRotation(rotation)

Spécifie la rotation, en degrés, de la forme.

setRotation(rotation: number): void;

Paramètres

rotation: number

Retours

void

setTop(top)

setTop(top: number): void;

Paramètres

top: number

Retours

void

setVisible(visible)

Spécifie si la forme est visible.

setVisible(visible: boolean): void;

Paramètres

visible: boolean

Retours

void

setWidth(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 ou zéro comme entrée.

setWidth(width: number): void;

Paramètres

width: number

Retours

void

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: ShapeZOrder): void;

Paramètres

position: ExcelScript.ShapeZOrder

Où déplacer la forme dans la pile de l’ordre de plan par rapport aux autres formes. Pour plus d’informations, consultez ExcelScript.ShapeZOrder .

Retours

void