Excel.Shape class

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

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.

placement

Represents how the object is attached to the cells below it.

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

copyTo(destinationSheet)

Copies and pastes a Shape object. The pasted shape is copied to the same pixel location as this shape.

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

fill

Returns the fill formatting of this shape.

readonly fill: Excel.ShapeFill;

Property Value

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

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

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"

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

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

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

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

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

Remarks

[ API set: ExcelApi 1.9 ]

placement

Represents how the object is attached to the cells below it.

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

Property Value

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

Remarks

[ API set: ExcelApi 1.10 ]

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

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

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

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

copyTo(destinationSheet)

Copies and pastes a Shape object. The pasted shape is copied to the same pixel location as this shape.

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

Parameters

destinationSheet

Excel.Worksheet | string

The sheet to which the shape object will be pasted. The default value is the copied shape's worksheet.

Returns

Remarks

[ API set: ExcelApi 1.10 ]

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

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)

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: "UNKNOWN" | "BMP" | "JPEG" | "GIF" | "PNG" | "SVG"): OfficeExtension.ClientResult<string>;

Parameters

formatString

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

Specifies the format of the image.

Returns

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

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

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

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)

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

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

Event Details

onActivated

Occurs when the shape is activated.

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

Event Type

Remarks

[ API set: ExcelApi 1.9 ]

onDeactivated

Occurs when the shape is deactivated.

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

Event Type

Remarks

[ API set: ExcelApi 1.9 ]