Excel.Shape class

Paquet:

excel

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. Pour en savoir plus sur le modèle objet de forme, consultez Utiliser des formes à l’aide de l’API JavaScript Excel.

Extends

OfficeExtension.ClientObject

Remarques

[ Ensemble d’API : ExcelApi 1.9 ]

Propriétés

altTextDescription	Spécifie le texte de description de remplacement d’un Shape objet.
altTextTitle	Spécifie le texte de titre de remplacement d’un Shape objet.
connectionSiteCount	Renvoie le nombre de sites de connexion sur la forme spécifiée.
context	Contexte de requête associé à l’objet . Cela connecte le processus du complément au processus de l’application hôte Office.
displayName	Obtient le nom complet de la forme. Une forme nouvellement créée a un nom généré qui est localisé et peut ne pas correspondre à son name. Dans ce scénario, vous pouvez utiliser cette API pour obtenir le nom affiché dans l’interface utilisateur.
fill	Renvoie la mise en forme de remplissage de cette forme.
geometricShape	Renvoie la Forme géométrique associée à la forme. Une erreur sera lancée si le type de forme n’est pas "GeometricShape".
geometricShapeType	Spécifie le type de forme géométrique de cette forme géométrique. Pour plus d’informations, consultez Excel.GeometricShapeType . Renvoie null si le type de forme n’est pas « GeometricShape ».
group	Renvoie le groupe de la Forme associée à la forme. Une erreur sera lancée si le type de forme n’est pas "GroupShape".
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.
id	Spécifie l’identificateur de forme.
image	Renvoie l’image associé à la forme. Une erreur sera lancée si le type de forme n’est pas "Image".
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.
level	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.
line	Renvoie l’image associée à la forme. Une erreur sera lancée si le type de forme n’est pas "Ligne".
lineFormat	Renvoie la mise en forme de ligne de cette forme.
lockAspectRatio	Spécifie si les proportions de cette forme sont verrouillées.
name	Spécifie le nom de la forme.
parentGroup	Spécifie le groupe parent de cette forme.
placement	Représente la manière dont l’objet est attaché aux cellules en dessous.
rotation	Spécifie la rotation, en degrés, de la forme.
textFrame	Renvoie l’objet textFrame d’une forme.
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.
type	Renvoie le type de cette forme. Pour plus d’informations, consultez Excel.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 ou zéro comme entrée.
zOrderPosition	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.

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.
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 Excel.PictureFormat.BMP,Excel.PictureFormat.PNG ,Excel.PictureFormat.JPEG et .Excel.PictureFormat.GIF
getAsImage(formatString)	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 Excel.PictureFormat.BMP,Excel.PictureFormat.PNG ,Excel.PictureFormat.JPEG et .Excel.PictureFormat.GIF
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é.
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.
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, scaleTypeString, scaleFromString)	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.
scaleWidth(scaleFactor, scaleTypeString, scaleFromString)	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(properties, options)	Définit plusieurs propriétés d’un objet en même temps. Vous pouvez passer un objet brut avec les propriétés appropriées ou un autre objet API du même type.
set(properties)	Définit plusieurs propriétés sur l’objet en même temps, en fonction d’un objet chargé existant.
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(positionString)	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.stringifyappelle à son tour la toJSON méthode de l’objet qui lui est passé.) Alors que l’objet Excel.Shape d’origine est un objet API, la toJSON méthode renvoie un objet JavaScript brut (typé en tant Excel.Interfaces.ShapeDataque ) qui contient des copies superficielles de toutes les propriétés enfants chargées de l’objet d’origine.

Événements

onActivated	Se produit lorsque la forme est activée.
onDeactivated	Se produit lorsque la forme est désactivée.

Détails de la propriété

altTextDescription

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

altTextDescription: string;

Valeur de propriété

string

Remarques

[ Ensemble d’API : ExcelApi 1.9 ]

altTextTitle

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

altTextTitle: string;

Valeur de propriété

string

Remarques

[ Ensemble d’API : ExcelApi 1.9 ]

connectionSiteCount

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

readonly connectionSiteCount: number;

Valeur de propriété

number

Remarques

[ Ensemble d’API : ExcelApi 1.9 ]

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 propriété

Excel.RequestContext

displayName

Obtient le nom complet de la forme. Une forme nouvellement créée a un nom généré qui est localisé et peut ne pas correspondre à son name. Dans ce scénario, vous pouvez utiliser cette API pour obtenir le nom affiché dans l’interface utilisateur.

readonly displayName: string;

Valeur de propriété

string

Remarques

[ Ensemble d’API : ExcelApi 1.15 ]

fill

Renvoie la mise en forme de remplissage de cette forme.

readonly fill: Excel.ShapeFill;

Valeur de propriété

Excel.ShapeFill

Remarques

[ Ensemble d’API : ExcelApi 1.9 ]

Exemples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/44-shape/shape-create-and-delete.yaml

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Shapes");
    const shape = sheet.shapes.addGeometricShape(Excel.GeometricShapeType.smileyFace);
    shape.left = 300;
    shape.top = 100;
    shape.height = 100;
    shape.width = 100;
    shape.fill.foregroundColor = "yellow"
    await context.sync();
});

geometricShape

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

readonly geometricShape: Excel.GeometricShape;

Valeur de propriété

Excel.GeometricShape

Remarques

[ Ensemble d’API : ExcelApi 1.9 ]

geometricShapeType

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

geometricShapeType: Excel.GeometricShapeType | "LineInverse" | "Triangle" | "RightTriangle" | "Rectangle" | "Diamond" | "Parallelogram" | "Trapezoid" | "NonIsoscelesTrapezoid" | "Pentagon" | "Hexagon" | "Heptagon" | "Octagon" | "Decagon" | "Dodecagon" | "Star4" | "Star5" | "Star6" | "Star7" | "Star8" | "Star10" | "Star12" | "Star16" | "Star24" | "Star32" | "RoundRectangle" | "Round1Rectangle" | "Round2SameRectangle" | "Round2DiagonalRectangle" | "SnipRoundRectangle" | "Snip1Rectangle" | "Snip2SameRectangle" | "Snip2DiagonalRectangle" | "Plaque" | "Ellipse" | "Teardrop" | "HomePlate" | "Chevron" | "PieWedge" | "Pie" | "BlockArc" | "Donut" | "NoSmoking" | "RightArrow" | "LeftArrow" | "UpArrow" | "DownArrow" | "StripedRightArrow" | "NotchedRightArrow" | "BentUpArrow" | "LeftRightArrow" | "UpDownArrow" | "LeftUpArrow" | "LeftRightUpArrow" | "QuadArrow" | "LeftArrowCallout" | "RightArrowCallout" | "UpArrowCallout" | "DownArrowCallout" | "LeftRightArrowCallout" | "UpDownArrowCallout" | "QuadArrowCallout" | "BentArrow" | "UturnArrow" | "CircularArrow" | "LeftCircularArrow" | "LeftRightCircularArrow" | "CurvedRightArrow" | "CurvedLeftArrow" | "CurvedUpArrow" | "CurvedDownArrow" | "SwooshArrow" | "Cube" | "Can" | "LightningBolt" | "Heart" | "Sun" | "Moon" | "SmileyFace" | "IrregularSeal1" | "IrregularSeal2" | "FoldedCorner" | "Bevel" | "Frame" | "HalfFrame" | "Corner" | "DiagonalStripe" | "Chord" | "Arc" | "LeftBracket" | "RightBracket" | "LeftBrace" | "RightBrace" | "BracketPair" | "BracePair" | "Callout1" | "Callout2" | "Callout3" | "AccentCallout1" | "AccentCallout2" | "AccentCallout3" | "BorderCallout1" | "BorderCallout2" | "BorderCallout3" | "AccentBorderCallout1" | "AccentBorderCallout2" | "AccentBorderCallout3" | "WedgeRectCallout" | "WedgeRRectCallout" | "WedgeEllipseCallout" | "CloudCallout" | "Cloud" | "Ribbon" | "Ribbon2" | "EllipseRibbon" | "EllipseRibbon2" | "LeftRightRibbon" | "VerticalScroll" | "HorizontalScroll" | "Wave" | "DoubleWave" | "Plus" | "FlowChartProcess" | "FlowChartDecision" | "FlowChartInputOutput" | "FlowChartPredefinedProcess" | "FlowChartInternalStorage" | "FlowChartDocument" | "FlowChartMultidocument" | "FlowChartTerminator" | "FlowChartPreparation" | "FlowChartManualInput" | "FlowChartManualOperation" | "FlowChartConnector" | "FlowChartPunchedCard" | "FlowChartPunchedTape" | "FlowChartSummingJunction" | "FlowChartOr" | "FlowChartCollate" | "FlowChartSort" | "FlowChartExtract" | "FlowChartMerge" | "FlowChartOfflineStorage" | "FlowChartOnlineStorage" | "FlowChartMagneticTape" | "FlowChartMagneticDisk" | "FlowChartMagneticDrum" | "FlowChartDisplay" | "FlowChartDelay" | "FlowChartAlternateProcess" | "FlowChartOffpageConnector" | "ActionButtonBlank" | "ActionButtonHome" | "ActionButtonHelp" | "ActionButtonInformation" | "ActionButtonForwardNext" | "ActionButtonBackPrevious" | "ActionButtonEnd" | "ActionButtonBeginning" | "ActionButtonReturn" | "ActionButtonDocument" | "ActionButtonSound" | "ActionButtonMovie" | "Gear6" | "Gear9" | "Funnel" | "MathPlus" | "MathMinus" | "MathMultiply" | "MathDivide" | "MathEqual" | "MathNotEqual" | "CornerTabs" | "SquareTabs" | "PlaqueTabs" | "ChartX" | "ChartStar" | "ChartPlus";

Valeur de propriété

Excel.GeometricShapeType | "LineInverse" | "Triangle" | "RightTriangle" | "Rectangle" | "Diamond" | "Parallelogram" | "Trapezoid" | "NonIsoscelesTrapezoid" | "Pentagon" | "Hexagon" | "Heptagon" | "Octagon" | "Decagon" | "Dodecagon" | "Star4" | "Star5" | "Star6" | "Star7" | "Star8" | "Star10" | "Star12" | "Star16" | "Star24" | "Star32" | "RoundRectangle" | "Round1Rectangle" | "Round2SameRectangle" | "Round2DiagonalRectangle" | "SnipRoundRectangle" | "Snip1Rectangle" | "Snip2SameRectangle" | "Snip2DiagonalRectangle" | "Plaque" | "Ellipse" | "Teardrop" | "HomePlate" | "Chevron" | "PieWedge" | "Pie" | "BlockArc" | "Donut" | "NoSmoking" | "RightArrow" | "LeftArrow" | "UpArrow" | "DownArrow" | "StripedRightArrow" | "NotchedRightArrow" | "BentUpArrow" | "LeftRightArrow" | "UpDownArrow" | "LeftUpArrow" | "LeftRightUpArrow" | "QuadArrow" | "LeftArrowCallout" | "RightArrowCallout" | "UpArrowCallout" | "DownArrowCallout" | "LeftRightArrowCallout" | "UpDownArrowCallout" | "QuadArrowCallout" | "BentArrow" | "UturnArrow" | "CircularArrow" | "LeftCircularArrow" | "LeftRightCircularArrow" | "CurvedRightArrow" | "CurvedLeftArrow" | "CurvedUpArrow" | "CurvedDownArrow" | "SwooshArrow" | "Cube" | "Can" | "LightningBolt" | "Heart" | "Sun" | "Moon" | "SmileyFace" | "IrregularSeal1" | "IrregularSeal2" | "FoldedCorner" | "Bevel" | "Frame" | "HalfFrame" | "Corner" | "DiagonalStripe" | "Chord" | "Arc" | "LeftBracket" | "RightBracket" | "LeftBrace" | "RightBrace" | "BracketPair" | "BracePair" | "Callout1" | "Callout2" | "Callout3" | "AccentCallout1" | "AccentCallout2" | "AccentCallout3" | "BorderCallout1" | "BorderCallout2" | "BorderCallout3" | "AccentBorderCallout1" | "AccentBorderCallout2" | "AccentBorderCallout3" | "WedgeRectCallout" | "WedgeRRectCallout" | "WedgeEllipseCallout" | "CloudCallout" | "Cloud" | "Ribbon" | "Ribbon2" | "EllipseRibbon" | "EllipseRibbon2" | "LeftRightRibbon" | "VerticalScroll" | "HorizontalScroll" | "Wave" | "DoubleWave" | "Plus" | "FlowChartProcess" | "FlowChartDecision" | "FlowChartInputOutput" | "FlowChartPredefinedProcess" | "FlowChartInternalStorage" | "FlowChartDocument" | "FlowChartMultidocument" | "FlowChartTerminator" | "FlowChartPreparation" | "FlowChartManualInput" | "FlowChartManualOperation" | "FlowChartConnector" | "FlowChartPunchedCard" | "FlowChartPunchedTape" | "FlowChartSummingJunction" | "FlowChartOr" | "FlowChartCollate" | "FlowChartSort" | "FlowChartExtract" | "FlowChartMerge" | "FlowChartOfflineStorage" | "FlowChartOnlineStorage" | "FlowChartMagneticTape" | "FlowChartMagneticDisk" | "FlowChartMagneticDrum" | "FlowChartDisplay" | "FlowChartDelay" | "FlowChartAlternateProcess" | "FlowChartOffpageConnector" | "ActionButtonBlank" | "ActionButtonHome" | "ActionButtonHelp" | "ActionButtonInformation" | "ActionButtonForwardNext" | "ActionButtonBackPrevious" | "ActionButtonEnd" | "ActionButtonBeginning" | "ActionButtonReturn" | "ActionButtonDocument" | "ActionButtonSound" | "ActionButtonMovie" | "Gear6" | "Gear9" | "Funnel" | "MathPlus" | "MathMinus" | "MathMultiply" | "MathDivide" | "MathEqual" | "MathNotEqual" | "CornerTabs" | "SquareTabs" | "PlaqueTabs" | "ChartX" | "ChartStar" | "ChartPlus"

Remarques

[ Ensemble d’API : ExcelApi 1.9 ]

group

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

readonly group: Excel.ShapeGroup;

Valeur de propriété

Excel.ShapeGroup

Remarques

[ Ensemble d’API : ExcelApi 1.9 ]

Exemples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/44-shape/shape-groups.yaml

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Shapes");

    const shapeGroup = sheet.shapes.getItem("Group").group;
    shapeGroup.ungroup();
    console.log("Shapes ungrouped");

    await context.sync();
});

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.

height: number;

Valeur de propriété

number

Remarques

[ Ensemble d’API : ExcelApi 1.9 ]

id

Spécifie l’identificateur de forme.

readonly id: string;

Valeur de propriété

string

Remarques

[ Ensemble d’API : ExcelApi 1.9 ]

image

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

readonly image: Excel.Image;

Valeur de propriété

Excel.Image

Remarques

[ Ensemble d’API : ExcelApi 1.9 ]

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.

left: number;

Valeur de propriété

number

Remarques

[ Ensemble d’API : ExcelApi 1.9 ]

level

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.

readonly level: number;

Valeur de propriété

number

Remarques

[ Ensemble d’API : ExcelApi 1.9 ]

line

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

readonly line: Excel.Line;

Valeur de propriété

Excel.Line

Remarques

[ Ensemble d’API : ExcelApi 1.9 ]

Exemples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/44-shape/shape-lines.yaml

await Excel.run(async (context) => {
    const shapes = context.workbook.worksheets.getItem("Shapes").shapes;
    const line = shapes.getItem("StraightLine").line;
    line.beginArrowheadLength = Excel.ArrowheadLength.long;
    line.beginArrowheadWidth = Excel.ArrowheadWidth.wide;
    line.beginArrowheadStyle = Excel.ArrowheadStyle.oval;

    line.endArrowheadLength = Excel.ArrowheadLength.long;
    line.endArrowheadWidth = Excel.ArrowheadWidth.wide;
    line.endArrowheadStyle = Excel.ArrowheadStyle.triangle;

    await context.sync();
});

lineFormat

Renvoie la mise en forme de ligne de cette forme.

readonly lineFormat: Excel.ShapeLineFormat;

Valeur de propriété

Excel.ShapeLineFormat

Remarques

[ Ensemble d’API : ExcelApi 1.9 ]

lockAspectRatio

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

lockAspectRatio: boolean;

Valeur de propriété

boolean

Remarques

[ Ensemble d’API : ExcelApi 1.9 ]

Exemples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/44-shape/shape-move-and-order.yaml

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Shapes");
    const shape = sheet.shapes.getItem("Octagon")
    shape.lockAspectRatio = true;
    shape.scaleHeight(1.25, Excel.ShapeScaleType.currentSize);
    await context.sync();
});

name

Spécifie le nom de la forme.

name: string;

Valeur de propriété

string

Remarques

[ Ensemble d’API : ExcelApi 1.9 ]

parentGroup

Spécifie le groupe parent de cette forme.

readonly parentGroup: Excel.Shape;

Valeur de propriété

Excel.Shape

Remarques

[ Ensemble d’API : ExcelApi 1.9 ]

placement

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

placement: Excel.Placement | "TwoCell" | "OneCell" | "Absolute";

Valeur de propriété

Excel.Placement | "TwoCell" | "OneCell" | "Absolute"

Remarques

[ Ensemble d’API : ExcelApi 1.10 ]

rotation

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

rotation: number;

Valeur de propriété

number

Remarques

[ Ensemble d’API : ExcelApi 1.9 ]

Exemples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/44-shape/shape-create-and-delete.yaml

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Shapes");
    const shape = sheet.shapes.addGeometricShape(Excel.GeometricShapeType.triangle);
    shape.left = 100;
    shape.top = 300;
    shape.height = 150;
    shape.width = 200;
    shape.rotation = 45;
    shape.fill.clear();
    await context.sync();
});

textFrame

Renvoie l’objet textFrame d’une forme.

readonly textFrame: Excel.TextFrame;

Valeur de propriété

Excel.TextFrame

Remarques

[ Ensemble d’API : ExcelApi 1.9 ]

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.

top: number;

Valeur de propriété

number

Remarques

[ Ensemble d’API : ExcelApi 1.9 ]

type

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

readonly type: Excel.ShapeType | "Unsupported" | "Image" | "GeometricShape" | "Group" | "Line";

Valeur de propriété

Excel.ShapeType | "Unsupported" | "Image" | "GeometricShape" | "Group" | "Line"

Remarques

[ Ensemble d’API : ExcelApi 1.9 ]

visible

Spécifie si la forme est visible.

visible: boolean;

Valeur de propriété

boolean

Remarques

[ Ensemble d’API : ExcelApi 1.9 ]

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.

width: number;

Valeur de propriété

number

Remarques

[ Ensemble d’API : ExcelApi 1.9 ]

zOrderPosition

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.

readonly zOrderPosition: number;

Valeur de propriété

number

Remarques

[ Ensemble d’API : ExcelApi 1.9 ]

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): Excel.Shape;

Paramètres

destinationSheet

Excel.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

Excel.Shape

Remarques

[ Ensemble d’API : ExcelApi 1.10 ]

delete()

Supprime la forme à partir de la feuille de calcul.

delete(): void;

Retours

void

Remarques

[ Ensemble d’API : ExcelApi 1.9 ]

Exemples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/44-shape/shape-create-and-delete.yaml

await Excel.run(async (context) => {
    context.workbook.worksheets.getItemOrNullObject("Shapes").delete();
    const sheet = context.workbook.worksheets.add("Shapes");

    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((shape) => shape.delete());
    await context.sync();
});

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 Excel.PictureFormat.BMP,Excel.PictureFormat.PNG ,Excel.PictureFormat.JPEG et .Excel.PictureFormat.GIF

getAsImage(format: Excel.PictureFormat): OfficeExtension.ClientResult<string>;

Paramètres

format

Excel.PictureFormat

Spécifie le format de l’image.

Retours

OfficeExtension.ClientResult<string>

Remarques

[ Ensemble d’API : ExcelApi 1.9 ]

Exemples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/44-shape/shape-images.yaml

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Shapes");
    const shape = sheet.shapes.getItem("Image");
    const result = shape.getAsImage(Excel.PictureFormat.png);
    await context.sync();

    const imageString = result.value;
    // Your add-in would save this string as a .png file.
    console.log("The image's Base64-encoded string: " + imageString);
});

getAsImage(formatString)

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 Excel.PictureFormat.BMP,Excel.PictureFormat.PNG ,Excel.PictureFormat.JPEG et .Excel.PictureFormat.GIF

getAsImage(formatString: "UNKNOWN" | "BMP" | "JPEG" | "GIF" | "PNG" | "SVG"): OfficeExtension.ClientResult<string>;

Paramètres

formatString

"UNKNOWN" | "BMP" | "JPEG" | "GIF" | "PNG" | "SVG"

Spécifie le format de l’image.

Retours

OfficeExtension.ClientResult<string>

Remarques

[ Ensemble d’API : ExcelApi 1.9 ]

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

Remarques

[ Ensemble d’API : ExcelApi 1.9 ]

Exemples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/44-shape/shape-move-and-order.yaml

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Shapes");
    const shape = sheet.shapes.getItem("Square")
    shape.incrementLeft(-25);
    await context.sync();
});

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

Remarques

[ Ensemble d’API : ExcelApi 1.9 ]

Exemples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/44-shape/shape-images.yaml

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Shapes");
    const shape = sheet.shapes.getItem("Image");
    shape.incrementRotation(180);
    await context.sync();
});

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

Remarques

[ Ensemble d’API : ExcelApi 1.9 ]

Exemples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/44-shape/shape-move-and-order.yaml

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Shapes");
    const shape = sheet.shapes.getItem("Pentagon")
    shape.incrementTop(25);
    await context.sync();
});

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?: Excel.Interfaces.ShapeLoadOptions): Excel.Shape;

Paramètres

options

Excel.Interfaces.ShapeLoadOptions

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

Retours

Excel.Shape

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[]): Excel.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.

Retours

Excel.Shape

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;
        }): Excel.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.

Retours

Excel.Shape

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: Excel.ShapeScaleType, scaleFrom?: Excel.ShapeScaleFrom): void;

Paramètres

scaleFactor

number

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

scaleType

Excel.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

Excel.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

Remarques

[ Ensemble d’API : ExcelApi 1.9 ]

Exemples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/44-shape/shape-move-and-order.yaml

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Shapes");
    const shape = sheet.shapes.getItem("Octagon")
    shape.lockAspectRatio = true;
    shape.scaleHeight(1.25, Excel.ShapeScaleType.currentSize);
    await context.sync();
});

scaleHeight(scaleFactor, scaleTypeString, scaleFromString)

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, scaleTypeString: "CurrentSize" | "OriginalSize", scaleFromString?: "ScaleFromTopLeft" | "ScaleFromMiddle" | "ScaleFromBottomRight"): void;

Paramètres

scaleFactor

number

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

scaleTypeString

"CurrentSize" | "OriginalSize"

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.

scaleFromString

"ScaleFromTopLeft" | "ScaleFromMiddle" | "ScaleFromBottomRight"

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

Remarques

[ Ensemble d’API : ExcelApi 1.9 ]

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: Excel.ShapeScaleType, scaleFrom?: Excel.ShapeScaleFrom): void;

Paramètres

scaleFactor

number

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

scaleType

Excel.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

Excel.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

Remarques

[ Ensemble d’API : ExcelApi 1.9 ]

scaleWidth(scaleFactor, scaleTypeString, scaleFromString)

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, scaleTypeString: "CurrentSize" | "OriginalSize", scaleFromString?: "ScaleFromTopLeft" | "ScaleFromMiddle" | "ScaleFromBottomRight"): void;

Paramètres

scaleFactor

number

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

scaleTypeString

"CurrentSize" | "OriginalSize"

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.

scaleFromString

"ScaleFromTopLeft" | "ScaleFromMiddle" | "ScaleFromBottomRight"

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

Remarques

[ Ensemble d’API : ExcelApi 1.9 ]

set(properties, options)

Définit plusieurs propriétés d’un objet en même temps. Vous pouvez passer un objet brut avec les propriétés appropriées ou un autre objet API du même type.

set(properties: Interfaces.ShapeUpdateData, options?: OfficeExtension.UpdateOptions): void;

Paramètres

properties

Excel.Interfaces.ShapeUpdateData

Objet JavaScript avec des propriétés qui sont structurées isomorphes en fonction des propriétés de l’objet sur lequel la méthode est appelée.

options

OfficeExtension.UpdateOptions

Fournit une option permettant de supprimer les erreurs si l’objet properties tente de définir des propriétés en lecture seule.

Retours

void

set(properties)

Définit plusieurs propriétés sur l’objet en même temps, en fonction d’un objet chargé existant.

set(properties: Excel.Shape): void;

Paramètres

properties

Excel.Shape

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

Paramètres

position

Excel.ShapeZOrder

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

Retours

void

Remarques

[ Ensemble d’API : ExcelApi 1.9 ]

Exemples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/44-shape/shape-move-and-order.yaml

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Shapes");
    const shape = sheet.shapes.getItem("Octagon")
    shape.setZOrder(Excel.ShapeZOrder.sendBackward);
    await context.sync();
});

setZOrder(positionString)

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(positionString: "BringToFront" | "BringForward" | "SendToBack" | "SendBackward"): void;

Paramètres

positionString

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

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

Retours

void

Remarques

[ Ensemble d’API : ExcelApi 1.9 ]

toJSON()

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

toJSON(): Excel.Interfaces.ShapeData;

Retours

Excel.Interfaces.ShapeData

Détails de l'événement

onActivated

Se produit lorsque la forme est activée.

readonly onActivated: OfficeExtension.EventHandlers<Excel.ShapeActivatedEventArgs>;

Type d'événement

OfficeExtension.EventHandlers<Excel.ShapeActivatedEventArgs>

Remarques

[ Ensemble d’API : ExcelApi 1.9 ]

onDeactivated

Se produit lorsque la forme est désactivée.

readonly onDeactivated: OfficeExtension.EventHandlers<Excel.ShapeDeactivatedEventArgs>;

Type d'événement

OfficeExtension.EventHandlers<Excel.ShapeDeactivatedEventArgs>

Remarques

[ Ensemble d’API : ExcelApi 1.9 ]