Excel.Shape class

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

altTextDescription: string;

Valeur de propriété

Remarques

Jeu d’API : ExcelApi 1.9

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

altTextTitle: string;

Valeur de propriété

Remarques

Jeu 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

Jeu d’API : ExcelApi 1.9

Contexte de requête associé à l’objet. Cette opération connecte le processus du complément à celui de l’application hôte Office.

context: RequestContext;

Valeur de propriété

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

readonly displayName: string;

Valeur de propriété

Remarques

Jeu d’API : ExcelApi 1.15

Renvoie la mise en forme de remplissage de cette forme.

readonly fill: Excel.ShapeFill;

Valeur de propriété

Remarques

Jeu d’API : ExcelApi 1.9

Exemples

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

await Excel.run(async (context) => {
    // Apply a solid fill color to the shape.
    const sheet = context.workbook.worksheets.getItem("Sample");
    const badge = sheet.shapes.getItem("Badge");
    const shapeFill: Excel.ShapeFill = badge.fill;
    shapeFill.setSolidColor("#FFE08A");

    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

Jeu d’API : ExcelApi 1.9

Spécifie le type de forme géométrique de cette forme géométrique. Pour Excel.GeometricShapeType plus de détails. Retourne 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

Jeu 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

Jeu 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 InvalidArgument exception lorsqu’une valeur d’entrée est négative ou égale à zéro.

height: number;

Valeur de propriété

Remarques

Jeu d’API : ExcelApi 1.9

Spécifie l’identificateur de forme.

readonly id: string;

Valeur de propriété

Remarques

Jeu 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

Jeu 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 InvalidArgument exception lorsqu’une valeur d’entrée est négative.

left: number;

Valeur de propriété

Remarques

Jeu 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

Jeu 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

Jeu 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

Jeu d’API : ExcelApi 1.9

Exemples

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

await Excel.run(async (context) => {
    // Load and log the shape's fill and outline properties.
    const sheet = context.workbook.worksheets.getItem("Sample");
    const badge = sheet.shapes.getItem("Badge");
    badge.fill.load(["foregroundColor", "transparency", "type"]);
    badge.lineFormat.load(["color", "dashStyle", "style", "transparency", "visible", "weight"]);

    await context.sync();

    console.log("Badge fill: " + JSON.stringify(badge.fill));
    console.log("Badge line format: " + JSON.stringify(badge.lineFormat));
});

Indique si les proportions de cette forme sont verrouillées.

lockAspectRatio: boolean;

Valeur de propriété

Remarques

Jeu 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

Jeu d’API : ExcelApi 1.9

Spécifie le groupe parent de cette forme.

readonly parentGroup: Excel.Shape;

Valeur de propriété

Remarques

Jeu 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

Jeu d’API : ExcelApi 1.10

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

rotation: number;

Valeur de propriété

Remarques

Jeu 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

Jeu 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 InvalidArgument exception lorsqu’une valeur d’entrée est négative.

top: number;

Valeur de propriété

Remarques

Jeu d’API : ExcelApi 1.9

Renvoie le type de cette forme. Pour Excel.ShapeType plus de détails.

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

Valeur de propriété

Remarques

Jeu d’API : ExcelApi 1.9

Indique si la forme est visible.

visible: boolean;

Valeur de propriété

Remarques

Jeu d’API : ExcelApi 1.9

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

width: number;

Valeur de propriété

Remarques

Jeu 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

Jeu d’API : ExcelApi 1.9

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

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

Paramètres

Retours

Remarques

Jeu d’API : ExcelApi 1.10

Supprime la forme à partir de la feuille de calcul.

delete(): void;

Retours

Remarques

Jeu 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 renvoie l’image sous la forme d’une chaîne codée en Base64. La résolution est 96. Les seuls formats pris en charge sont Excel.PictureFormat.BMP, , Excel.PictureFormat.JPEGExcel.PictureFormat.PNGet .Excel.PictureFormat.GIF

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

Paramètres

Retours

Remarques

Jeu 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 renvoie l’image sous la forme d’une chaîne codée en Base64. La résolution est 96. Les seuls formats pris en charge sont Excel.PictureFormat.BMP, , Excel.PictureFormat.JPEGExcel.PictureFormat.PNGet .Excel.PictureFormat.GIF

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

Paramètres

Retours

Remarques

Jeu 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

Jeu 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 cette rotation propriété pour définir la rotation absolue de la forme.

incrementRotation(increment: number): void;

Paramètres

Retours

Remarques

Jeu 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

Jeu 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

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

Paramètres

Retours

Remarques

Jeu 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

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

Paramètres

Retours

Remarques

Jeu d’API : ExcelApi 1.9

Définit plusieurs propriétés d’un objet en même temps. Vous pouvez transmettre soit un objet ordinaire avec les propriétés appropriées, soit 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

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

Paramètres

Retours

Remarques

Jeu 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.stringify, à son tour, appelle 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 simple (typé ) Excel.Interfaces.ShapeDataqui contient des copies superficielles de toutes les propriétés enfants chargées à partir 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

Jeu 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

Jeu d’API : ExcelApi 1.9