Excel.Shape class

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

altTextDescription: string;

Valeur de propriété

Remarques

[ Ensemble d’API : ExcelApi 1.9 ]

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

altTextTitle: string;

Valeur de propriété

Remarques

[ Ensemble d’API : ExcelApi 1.9 ]

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

readonly connectionSiteCount: number;

Valeur de propriété

Remarques

[ Ensemble d’API : ExcelApi 1.9 ]

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é

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é

Remarques

[ Ensemble d’API : ExcelApi 1.15 ]

Renvoie la mise en forme de remplissage de cette forme.

readonly fill: Excel.ShapeFill;

Valeur de propriété

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

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é

Remarques

[ Ensemble d’API : ExcelApi 1.9 ]

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é

Remarques

[ Ensemble d’API : ExcelApi 1.9 ]

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é

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

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é

Remarques

[ Ensemble d’API : ExcelApi 1.9 ]

Spécifie l’identificateur de forme.

readonly id: string;

Valeur de propriété

Remarques

[ Ensemble d’API : ExcelApi 1.9 ]

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é

Remarques

[ Ensemble d’API : ExcelApi 1.9 ]

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é

Remarques

[ Ensemble d’API : ExcelApi 1.9 ]

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é

Remarques

[ Ensemble d’API : ExcelApi 1.9 ]

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é

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

Renvoie la mise en forme de ligne de cette forme.

readonly lineFormat: Excel.ShapeLineFormat;

Valeur de propriété

Remarques

[ Ensemble d’API : ExcelApi 1.9 ]

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

lockAspectRatio: boolean;

Valeur de propriété

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

Spécifie le nom de la forme.

name: string;

Valeur de propriété

Remarques

[ Ensemble d’API : ExcelApi 1.9 ]

Spécifie le groupe parent de cette forme.

readonly parentGroup: Excel.Shape;

Valeur de propriété

Remarques

[ Ensemble d’API : ExcelApi 1.9 ]

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

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

Valeur de propriété

Remarques

[ Ensemble d’API : ExcelApi 1.10 ]

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

rotation: number;

Valeur de propriété

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

Renvoie l’objet textFrame d’une forme.

readonly textFrame: Excel.TextFrame;

Valeur de propriété

Remarques

[ Ensemble d’API : ExcelApi 1.9 ]

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é

Remarques

[ Ensemble d’API : ExcelApi 1.9 ]

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é

Remarques

[ Ensemble d’API : ExcelApi 1.9 ]

Spécifie si la forme est visible.

visible: boolean;

Valeur de propriété

Remarques

[ Ensemble d’API : ExcelApi 1.9 ]

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é

Remarques

[ Ensemble d’API : ExcelApi 1.9 ]

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é

Remarques

[ Ensemble d’API : ExcelApi 1.9 ]

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

Retours

Remarques

[ Ensemble d’API : ExcelApi 1.10 ]

Supprime la forme à partir de la feuille de calcul.

delete(): void;

Retours

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

Convertit la forme en image et retourne l’image sous la forme d’une chaîne encodée en Base64. 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

Retours

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

Convertit la forme en image et retourne l’image sous la forme d’une chaîne encodée en Base64. 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

Retours

Remarques

[ Ensemble d’API : ExcelApi 1.9 ]

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

incrementLeft(increment: number): void;

Paramètres

Retours

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

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

Retours

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

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

incrementTop(increment: number): void;

Paramètres

Retours

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

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

Retours

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

Retours

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

Retours

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

Retours

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

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

Retours

Remarques

[ Ensemble d’API : ExcelApi 1.9 ]

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

Retours

Remarques

[ Ensemble d’API : ExcelApi 1.9 ]

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

Retours

Remarques

[ Ensemble d’API : ExcelApi 1.9 ]

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

Retours

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

Retours

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

Retours

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

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

Retours

Remarques

[ Ensemble d’API : ExcelApi 1.9 ]

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 d’origine Excel.Shape 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

Se produit lorsque la forme est activée.

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

Type d'événement

Remarques

[ Ensemble d’API : ExcelApi 1.9 ]

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

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

Type d'événement

Remarques

[ Ensemble d’API : ExcelApi 1.9 ]