ExcelScript.Shape interface
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
copy |
Copie et colle un |
delete() | Supprime la forme à partir de la feuille de calcul. |
get |
Spécifie le texte de description de remplacement d’un |
get |
Spécifie le texte de titre de remplacement d’un |
get |
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 |
get |
Renvoie le nombre de sites de connexion sur la forme spécifiée. |
get |
Renvoie la mise en forme de remplissage de cette forme. |
get |
Renvoie la Forme géométrique associée à la forme. Une erreur sera lancée si le type de forme n’est pas "GeometricShape". |
get |
Spécifie le type de forme géométrique de cette forme géométrique. Pour plus d’informations, consultez |
get |
Renvoie le groupe de la Forme associée à la forme. Une erreur sera lancée si le type de forme n’est pas "GroupShape". |
get |
Spécifie la hauteur, en points, de la forme. Lève une exception lorsqu’elle |
get |
Spécifie l’identificateur de forme. |
get |
Renvoie l’image associé à la forme. Une erreur sera lancée si le type de forme n’est pas "Image". |
get |
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 |
get |
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 |
get |
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. |
get |
Renvoie l’image associée à la forme. Une erreur sera lancée si le type de forme n’est pas "Ligne". |
get |
Renvoie la mise en forme de ligne de cette forme. |
get |
Spécifie si les proportions de cette forme sont verrouillées. |
get |
Spécifie le nom de la forme. |
get |
Spécifie le groupe parent de cette forme. |
get |
Représente la manière dont l’objet est attaché aux cellules en dessous. |
get |
Spécifie la rotation, en degrés, de la forme. |
get |
Renvoie l’objet textFrame d’une forme. |
get |
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 |
get |
Renvoie le type de cette forme. Pour plus d’informations, consultez |
get |
Spécifie si la forme est visible. |
get |
Spécifie la largeur, en points, de la forme. Lève une exception lorsqu’elle |
get |
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. |
increment |
Déplace horizontalement la forme spécifiée selon le nombre de points indiqué. |
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 |
increment |
Décale vers le haut la forme spécifiée selon le nombre de points spécifié. |
scale |
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. |
scale |
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. |
set |
Spécifie le texte de description de remplacement d’un |
set |
Spécifie le texte de titre de remplacement d’un |
set |
Spécifie le type de forme géométrique de cette forme géométrique. Pour plus d’informations, consultez |
set |
Spécifie la hauteur, en points, de la forme. Lève une exception lorsqu’elle |
set |
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 |
set |
Spécifie si les proportions de cette forme sont verrouillées. |
set |
Spécifie le nom de la forme. |
set |
Représente la manière dont l’objet est attaché aux cellules en dessous. |
set |
Spécifie la rotation, en degrés, de la forme. |
set |
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 |
set |
Spécifie si la forme est visible. |
set |
Spécifie la largeur, en points, de la forme. Lève une exception lorsqu’elle |
set |
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
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
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
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
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
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
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)
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
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
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
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()
getPlacement()
Représente la manière dont l’objet est attaché aux cellules en dessous.
getPlacement(): Placement;
Retours
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
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
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
Optional. 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
Optional. 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
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)
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 ».
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)
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.
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)
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.
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