Excel.Shape class

Reference

Package:: excel

Represents a generic shape object in the worksheet. A shape could be a geometric shape, a line, a group of shapes, etc. To learn more about the shape object model, read Work with shapes using the Excel JavaScript API.

Extends: OfficeExtension.ClientObject

Remarks

[ API set: ExcelApi 1.9 ]

Properties

altTextDescription	Specifies the alternative description text for a `Shape` object.
altTextTitle	Specifies the alternative title text for a `Shape` object.
connectionSiteCount	Returns the number of connection sites on this shape.
context	The request context associated with the object. This connects the add-in's process to the Office host application's process.
fill	Returns the fill formatting of this shape.
geometricShape	Returns the geometric shape associated with the shape. An error will be thrown if the shape type is not "GeometricShape".
geometricShapeType	Specifies the geometric shape type of this geometric shape. See `Excel.GeometricShapeType` for details. Returns `null` if the shape type is not "GeometricShape".
group	Returns the shape group associated with the shape. An error will be thrown if the shape type is not "GroupShape".
height	Specifies the height, in points, of the shape. Throws an `InvalidArgument` exception when set with a negative value or zero as an input.
id	Specifies the shape identifier.
image	Returns the image associated with the shape. An error will be thrown if the shape type is not "Image".
left	The distance, in points, from the left side of the shape to the left side of the worksheet. Throws an `InvalidArgument` exception when set with a negative value as an input.
level	Specifies the level of the specified shape. For example, a level of 0 means that the shape is not part of any groups, a level of 1 means the shape is part of a top-level group, and a level of 2 means the shape is part of a sub-group of the top level.
line	Returns the line associated with the shape. An error will be thrown if the shape type is not "Line".
lineFormat	Returns the line formatting of this shape.
lockAspectRatio	Specifies if the aspect ratio of this shape is locked.
name	Specifies the name of the shape.
parentGroup	Specifies the parent group of this shape.
rotation	Specifies the rotation, in degrees, of the shape.
textFrame	Returns the text frame object of this shape.
top	The distance, in points, from the top edge of the shape to the top edge of the worksheet. Throws an `InvalidArgument` exception when set with a negative value as an input.
type	Returns the type of this shape. See `Excel.ShapeType` for details.
visible	Specifies if the shape is visible.
width	Specifies the width, in points, of the shape. Throws an `InvalidArgument` exception when set with a negative value or zero as an input.
zOrderPosition	Returns the position of the specified shape in the z-order, with 0 representing the bottom of the order stack.

Methods

delete()	Removes the shape from the worksheet.
getAsImage(format)	Converts the shape to an image and returns the image as a base64-encoded string. The DPI is 96. The only supported formats are `Excel.PictureFormat.BMP`, `Excel.PictureFormat.PNG`, `Excel.PictureFormat.JPEG`, and `Excel.PictureFormat.GIF`.
getAsImage(formatString)	Converts the shape to an image and returns the image as a base64-encoded string. The DPI is 96. The only supported formats are `Excel.PictureFormat.BMP`, `Excel.PictureFormat.PNG`, `Excel.PictureFormat.JPEG`, and `Excel.PictureFormat.GIF`.
incrementLeft(increment)	Moves the shape horizontally by the specified number of points.
incrementRotation(increment)	Rotates the shape clockwise around the z-axis by the specified number of degrees. Use the `rotation` property to set the absolute rotation of the shape.
incrementTop(increment)	Moves the shape vertically by the specified number of points.
load(options)	Queues up a command to load the specified properties of the object. You must call `context.sync()` before reading the properties.
load(propertyNames)	Queues up a command to load the specified properties of the object. You must call `context.sync()` before reading the properties.
load(propertyNamesAndPaths)	Queues up a command to load the specified properties of the object. You must call `context.sync()` before reading the properties.
scaleHeight(scaleFactor, scaleType, scaleFrom)	Scales the height of the shape by a specified factor. For images, you can indicate whether you want to scale the shape relative to the original or the current size. Shapes other than pictures are always scaled relative to their current height.
scaleHeight(scaleFactor, scaleTypeString, scaleFromString)	Scales the height of the shape by a specified factor. For images, you can indicate whether you want to scale the shape relative to the original or the current size. Shapes other than pictures are always scaled relative to their current height.
scaleWidth(scaleFactor, scaleType, scaleFrom)	Scales the width of the shape by a specified factor. For images, you can indicate whether you want to scale the shape relative to the original or the current size. Shapes other than pictures are always scaled relative to their current width.
scaleWidth(scaleFactor, scaleTypeString, scaleFromString)	Scales the width of the shape by a specified factor. For images, you can indicate whether you want to scale the shape relative to the original or the current size. Shapes other than pictures are always scaled relative to their current width.
set(properties, options)	Sets multiple properties of an object at the same time. You can pass either a plain object with the appropriate properties, or another API object of the same type.
set(properties)	Sets multiple properties on the object at the same time, based on an existing loaded object.
setZOrder(position)	Moves the specified shape up or down the collection's z-order, which shifts it in front of or behind other shapes.
setZOrder(positionString)	Moves the specified shape up or down the collection's z-order, which shifts it in front of or behind other shapes.
toJSON()	Overrides the JavaScript `toJSON()` method in order to provide more useful output when an API object is passed to `JSON.stringify()`. (`JSON.stringify`, in turn, calls the `toJSON` method of the object that is passed to it.) Whereas the original Excel.Shape object is an API object, the `toJSON` method returns a plain JavaScript object (typed as `Excel.Interfaces.ShapeData`) that contains shallow copies of any loaded child properties from the original object.

Events

onActivated	Occurs when the shape is activated.
onDeactivated	Occurs when the shape is deactivated.

Property Details

altTextDescription

Specifies the alternative description text for a Shape object.

altTextDescription: string;

Property Value

string

Remarks

[ API set: ExcelApi 1.9 ]

altTextTitle

Specifies the alternative title text for a Shape object.

altTextTitle: string;

Property Value

string

Remarks

[ API set: ExcelApi 1.9 ]

connectionSiteCount

Returns the number of connection sites on this shape.

readonly connectionSiteCount: number;

Property Value

number

Remarks

[ API set: ExcelApi 1.9 ]

context

The request context associated with the object. This connects the add-in's process to the Office host application's process.

context: RequestContext;

Property Value

Excel.RequestContext

fill

Returns the fill formatting of this shape.

readonly fill: Excel.ShapeFill;

Property Value

Excel.ShapeFill

Remarks

[ API set: ExcelApi 1.9 ]

Examples

// 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

Returns the geometric shape associated with the shape. An error will be thrown if the shape type is not "GeometricShape".

readonly geometricShape: Excel.GeometricShape;

Property Value

Excel.GeometricShape

Remarks

[ API set: ExcelApi 1.9 ]

geometricShapeType

Specifies the geometric shape type of this geometric shape. See Excel.GeometricShapeType for details. Returns null if the shape type is not "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";

Property Value

Remarks

[ API set: ExcelApi 1.9 ]

group

Returns the shape group associated with the shape. An error will be thrown if the shape type is not "GroupShape".

readonly group: Excel.ShapeGroup;

Property Value

Excel.ShapeGroup

Remarks

[ API set: ExcelApi 1.9 ]

Examples

// 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

Specifies the height, in points, of the shape. Throws an InvalidArgument exception when set with a negative value or zero as an input.

height: number;

Property Value

number

Remarks

[ API set: ExcelApi 1.9 ]

id

Specifies the shape identifier.

readonly id: string;

Property Value

string

Remarks

[ API set: ExcelApi 1.9 ]

image

Returns the image associated with the shape. An error will be thrown if the shape type is not "Image".

readonly image: Excel.Image;

Property Value

Excel.Image

Remarks

[ API set: ExcelApi 1.9 ]

left

The distance, in points, from the left side of the shape to the left side of the worksheet. Throws an InvalidArgument exception when set with a negative value as an input.

left: number;

Property Value

number

Remarks

[ API set: ExcelApi 1.9 ]

level

Specifies the level of the specified shape. For example, a level of 0 means that the shape is not part of any groups, a level of 1 means the shape is part of a top-level group, and a level of 2 means the shape is part of a sub-group of the top level.

readonly level: number;

Property Value

number

Remarks

[ API set: ExcelApi 1.9 ]

line

Returns the line associated with the shape. An error will be thrown if the shape type is not "Line".

readonly line: Excel.Line;

Property Value

Excel.Line

Remarks

[ API set: ExcelApi 1.9 ]

Examples

// 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

Returns the line formatting of this shape.

readonly lineFormat: Excel.ShapeLineFormat;

Property Value

Excel.ShapeLineFormat

Remarks

[ API set: ExcelApi 1.9 ]

lockAspectRatio

Specifies if the aspect ratio of this shape is locked.

lockAspectRatio: boolean;

Property Value

boolean

Remarks

[ API set: ExcelApi 1.9 ]

Examples

// 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

Specifies the name of the shape.

name: string;

Property Value

string

Remarks

[ API set: ExcelApi 1.9 ]

parentGroup

Specifies the parent group of this shape.

readonly parentGroup: Excel.Shape;

Property Value

Excel.Shape

Remarks

[ API set: ExcelApi 1.9 ]

rotation

Specifies the rotation, in degrees, of the shape.

rotation: number;

Property Value

number

Remarks

[ API set: ExcelApi 1.9 ]

Examples

// 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

Returns the text frame object of this shape.

readonly textFrame: Excel.TextFrame;

Property Value

Excel.TextFrame

Remarks

[ API set: ExcelApi 1.9 ]

top

The distance, in points, from the top edge of the shape to the top edge of the worksheet. Throws an InvalidArgument exception when set with a negative value as an input.

top: number;

Property Value

number

Remarks

[ API set: ExcelApi 1.9 ]

type

Returns the type of this shape. See Excel.ShapeType for details.

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

Property Value

Remarks

[ API set: ExcelApi 1.9 ]

visible

Specifies if the shape is visible.

visible: boolean;

Property Value

boolean

Remarks

[ API set: ExcelApi 1.9 ]

width

Specifies the width, in points, of the shape. Throws an InvalidArgument exception when set with a negative value or zero as an input.

width: number;

Property Value

number

Remarks

[ API set: ExcelApi 1.9 ]

zOrderPosition

Returns the position of the specified shape in the z-order, with 0 representing the bottom of the order stack.

readonly zOrderPosition: number;

Property Value

number

Remarks

[ API set: ExcelApi 1.9 ]

Method Details

delete()

Removes the shape from the worksheet.

delete(): void;

Returns

void

Remarks

[ API set: ExcelApi 1.9 ]

Examples

// 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)

Converts the shape to an image and returns the image as a base64-encoded string. The DPI is 96. The only supported formats are Excel.PictureFormat.BMP, Excel.PictureFormat.PNG, Excel.PictureFormat.JPEG, and Excel.PictureFormat.GIF.

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

Parameters

format: Excel.PictureFormat

Specifies the format of the image.

Returns

OfficeExtension.ClientResult<string>

Remarks

[ API set: ExcelApi 1.9 ]

Examples

// 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)

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

Parameters

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

Specifies the format of the image.

Returns

OfficeExtension.ClientResult<string>

Remarks

[ API set: ExcelApi 1.9 ]

incrementLeft(increment)

Moves the shape horizontally by the specified number of points.

incrementLeft(increment: number): void;

Parameters

increment: number

The increment, in points, the shape will be horizontally moved. A positive value moves the shape to the right and a negative value moves it to the left. If the sheet is right-to-left oriented, this is reversed: positive values will move the shape to the left and negative values will move it to the right.

Returns

void

Remarks

[ API set: ExcelApi 1.9 ]

Examples

// 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)

Rotates the shape clockwise around the z-axis by the specified number of degrees. Use the rotation property to set the absolute rotation of the shape.

incrementRotation(increment: number): void;

Parameters

increment: number

How many degrees the shape will be rotated. A positive value rotates the shape clockwise and a negative value rotates it counterclockwise.

Returns

void

Remarks

[ API set: ExcelApi 1.9 ]

Examples

// 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)

Moves the shape vertically by the specified number of points.

incrementTop(increment: number): void;

Parameters

increment: number

The increment, in points, the shape will be vertically moved. A positive value moves the shape down and a negative value moves it up.

Returns

void

Remarks

[ API set: ExcelApi 1.9 ]

Examples

// 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)

Queues up a command to load the specified properties of the object. You must call context.sync() before reading the properties.

load(options?: Excel.Interfaces.ShapeLoadOptions): Excel.Shape;

Parameters

options: Excel.Interfaces.ShapeLoadOptions

Provides options for which properties of the object to load.

Returns

Excel.Shape

load(propertyNames)

Queues up a command to load the specified properties of the object. You must call context.sync() before reading the properties.

load(propertyNames?: string | string[]): Excel.Shape;

Parameters

propertyNames: string | string[]

A comma-delimited string or an array of strings that specify the properties to load.

Returns

Excel.Shape

load(propertyNamesAndPaths)

Queues up a command to load the specified properties of the object. You must call context.sync() before reading the properties.

load(propertyNamesAndPaths?: {
            select?: string;
            expand?: string;
        }): Excel.Shape;

Parameters

propertyNamesAndPaths: { select?: string; expand?: string; }

propertyNamesAndPaths.select is a comma-delimited string that specifies the properties to load, and propertyNamesAndPaths.expand is a comma-delimited string that specifies the navigation properties to load.

Returns

Excel.Shape

scaleHeight(scaleFactor, scaleType, scaleFrom)

Scales the height of the shape by a specified factor. For images, you can indicate whether you want to scale the shape relative to the original or the current size. Shapes other than pictures are always scaled relative to their current height.

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

Parameters

scaleFactor: number

Specifies the ratio between the height of the shape after you resize it and the current or original height.

scaleType: Excel.ShapeScaleType

Specifies whether the shape is scaled relative to its original or current size. The original size scaling option only works for images.

scaleFrom: Excel.ShapeScaleFrom

Optional. Specifies which part of the shape retains its position when the shape is scaled. If omitted, it represents the shape's upper left corner retains its position.

Returns

void

Remarks

[ API set: ExcelApi 1.9 ]

Examples

// 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)

scaleHeight(scaleFactor: number, scaleTypeString: "CurrentSize" | "OriginalSize", scaleFromString?: "ScaleFromTopLeft" | "ScaleFromMiddle" | "ScaleFromBottomRight"): void;

Parameters

scaleFactor: number

Specifies the ratio between the height of the shape after you resize it and the current or original height.

scaleTypeString: "CurrentSize" | "OriginalSize"

Specifies whether the shape is scaled relative to its original or current size. The original size scaling option only works for images.

scaleFromString: "ScaleFromTopLeft" | "ScaleFromMiddle" | "ScaleFromBottomRight"

Optional. Specifies which part of the shape retains its position when the shape is scaled. If omitted, it represents the shape's upper left corner retains its position.

Returns

void

Remarks

[ API set: ExcelApi 1.9 ]

scaleWidth(scaleFactor, scaleType, scaleFrom)

Scales the width of the shape by a specified factor. For images, you can indicate whether you want to scale the shape relative to the original or the current size. Shapes other than pictures are always scaled relative to their current width.

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

Parameters

scaleFactor: number

Specifies the ratio between the width of the shape after you resize it and the current or original width.

scaleType: Excel.ShapeScaleType

Specifies whether the shape is scaled relative to its original or current size. The original size scaling option only works for images.

scaleFrom: Excel.ShapeScaleFrom

Optional. Specifies which part of the shape retains its position when the shape is scaled. If omitted, it represents the shape's upper left corner retains its position.

Returns

void

Remarks

[ API set: ExcelApi 1.9 ]

scaleWidth(scaleFactor, scaleTypeString, scaleFromString)

scaleWidth(scaleFactor: number, scaleTypeString: "CurrentSize" | "OriginalSize", scaleFromString?: "ScaleFromTopLeft" | "ScaleFromMiddle" | "ScaleFromBottomRight"): void;

Parameters

scaleFactor: number

Specifies the ratio between the width of the shape after you resize it and the current or original width.

scaleTypeString: "CurrentSize" | "OriginalSize"

Specifies whether the shape is scaled relative to its original or current size. The original size scaling option only works for images.

scaleFromString: "ScaleFromTopLeft" | "ScaleFromMiddle" | "ScaleFromBottomRight"

Optional. Specifies which part of the shape retains its position when the shape is scaled. If omitted, it represents the shape's upper left corner retains its position.

Returns

void

Remarks

[ API set: ExcelApi 1.9 ]

set(properties, options)

Sets multiple properties of an object at the same time. You can pass either a plain object with the appropriate properties, or another API object of the same type.

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

Parameters

properties: Excel.Interfaces.ShapeUpdateData

A JavaScript object with properties that are structured isomorphically to the properties of the object on which the method is called.

options: OfficeExtension.UpdateOptions

Provides an option to suppress errors if the properties object tries to set any read-only properties.

Returns

void

set(properties)

Sets multiple properties on the object at the same time, based on an existing loaded object.

set(properties: Excel.Shape): void;

Parameters

properties: Excel.Shape

Returns

void

setZOrder(position)

Moves the specified shape up or down the collection's z-order, which shifts it in front of or behind other shapes.

setZOrder(position: Excel.ShapeZOrder): void;

Parameters

position: Excel.ShapeZOrder

Where to move the shape in the z-order stack relative to the other shapes. See Excel.ShapeZOrder for details.

Returns

void

Remarks

[ API set: ExcelApi 1.9 ]

Examples

// 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)

Moves the specified shape up or down the collection's z-order, which shifts it in front of or behind other shapes.

setZOrder(positionString: "BringToFront" | "BringForward" | "SendToBack" | "SendBackward"): void;

Parameters

positionString: "BringToFront" | "BringForward" | "SendToBack" | "SendBackward"

Where to move the shape in the z-order stack relative to the other shapes. See Excel.ShapeZOrder for details.

Returns

void

Remarks

[ API set: ExcelApi 1.9 ]

toJSON()

Overrides the JavaScript toJSON() method in order to provide more useful output when an API object is passed to JSON.stringify(). (JSON.stringify, in turn, calls the toJSON method of the object that is passed to it.) Whereas the original Excel.Shape object is an API object, the toJSON method returns a plain JavaScript object (typed as Excel.Interfaces.ShapeData) that contains shallow copies of any loaded child properties from the original object.

toJSON(): Excel.Interfaces.ShapeData;

Returns

Excel.Interfaces.ShapeData

Event Details

onActivated

Occurs when the shape is activated.

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

Event Type

OfficeExtension.EventHandlers<Excel.ShapeActivatedEventArgs>

Remarks

[ API set: ExcelApi 1.9 ]

onDeactivated

Occurs when the shape is deactivated.

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

Event Type

OfficeExtension.EventHandlers<Excel.ShapeDeactivatedEventArgs>

Remarks

[ API set: ExcelApi 1.9 ]