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.

[ API set: ExcelApi 1.9 ]

Extends
OfficeExtension.ClientObject

Properties

altTextDescription

Returns or sets the alternative description text for a Shape object.

[ API set: ExcelApi 1.9 ]

altTextTitle

Returns or sets the alternative title text for a Shape object.

[ API set: ExcelApi 1.9 ]

connectionSiteCount

Returns the number of connection sites on this shape. Read-only.

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

fill

Returns the fill formatting of this shape. Read-only.

[ API set: ExcelApi 1.9 ]

geometricShape

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

[ API set: ExcelApi 1.9 ]

geometricShapeType

Represents the geometric shape type of this geometric shape. See Excel.GeometricShapeType for details. Returns null if the shape type is not "GeometricShape".

[ 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".

[ API set: ExcelApi 1.9 ]

height

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

[ API set: ExcelApi 1.9 ]

id

Represents the shape identifier. Read-only.

[ 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".

[ 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 invalid argument exception when set with a negative value as input.

[ API set: ExcelApi 1.9 ]

level

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

[ 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".

[ API set: ExcelApi 1.9 ]

lineFormat

Returns the line formatting of this shape. Read-only.

[ API set: ExcelApi 1.9 ]

lockAspectRatio

Specifies whether or not the aspect ratio of this shape is locked.

[ API set: ExcelApi 1.9 ]

name

Represents the name of the shape.

[ API set: ExcelApi 1.9 ]

parentGroup

Represents the parent group of this shape.

[ API set: ExcelApi 1.9 ]

placement

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

[ API set: ExcelApi BETA (PREVIEW ONLY) ]

rotation

Represents the rotation, in degrees, of the shape.

[ API set: ExcelApi 1.9 ]

textFrame

Returns the text frame object of this shape. Read only.

[ 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 invalid argument exception when set with a negative value as input.

[ API set: ExcelApi 1.9 ]

type

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

[ API set: ExcelApi 1.9 ]

visible

Represents the visibility of this shape.

[ API set: ExcelApi 1.9 ]

width

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

[ 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. Read-only.

[ API set: ExcelApi 1.9 ]

Methods

copyTo(destinationSheet)

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

[ API set: ExcelApi BETA (PREVIEW ONLY) ]

delete()

Removes the shape from the worksheet.

[ API set: ExcelApi 1.9 ]

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.

[ API set: ExcelApi 1.9 ]

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.

[ API set: ExcelApi 1.9 ]

incrementLeft(increment)

Moves the shape horizontally by the specified number of points.

[ API set: ExcelApi 1.9 ]

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.

[ API set: ExcelApi 1.9 ]

incrementTop(increment)

Moves the shape vertically by the specified number of points.

[ API set: ExcelApi 1.9 ]

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.

[ API set: ExcelApi 1.9 ]

scaleHeight(scaleFactor, scaleTypeString, 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.

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

[ API set: ExcelApi 1.9 ]

scaleWidth(scaleFactor, scaleTypeString, 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.

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

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.

[ API set: ExcelApi 1.9 ]

setZOrder(positionString)

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

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

Events

onActivated

Occurs when the shape is activated.

[ API set: ExcelApi 1.9 ]

onDeactivated

Occurs when the shape is deactivated.

[ API set: ExcelApi 1.9 ]

Property Details

altTextDescription

Returns or sets the alternative description text for a Shape object.

[ API set: ExcelApi 1.9 ]

altTextDescription: string;

Property Value

string

altTextTitle

Returns or sets the alternative title text for a Shape object.

[ API set: ExcelApi 1.9 ]

altTextTitle: string;

Property Value

string

connectionSiteCount

Returns the number of connection sites on this shape. Read-only.

[ API set: ExcelApi 1.9 ]

readonly connectionSiteCount: number;

Property Value

number

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. Read-only.

[ API set: ExcelApi 1.9 ]

readonly fill: Excel.ShapeFill;

Property Value

Examples

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

[ API set: ExcelApi 1.9 ]

readonly geometricShape: Excel.GeometricShape;

Property Value

geometricShapeType

Represents the geometric shape type of this geometric shape. See Excel.GeometricShapeType for details. Returns null if the shape type is not "GeometricShape".

[ API set: ExcelApi 1.9 ]

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"

group

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

[ API set: ExcelApi 1.9 ]

readonly group: Excel.ShapeGroup;

Property Value

Examples

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

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

[ API set: ExcelApi 1.9 ]

height: number;

Property Value

number

id

Represents the shape identifier. Read-only.

[ API set: ExcelApi 1.9 ]

readonly id: string;

Property Value

string

image

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

[ API set: ExcelApi 1.9 ]

readonly image: Excel.Image;

Property Value

left

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

[ API set: ExcelApi 1.9 ]

left: number;

Property Value

number

level

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

[ API set: ExcelApi 1.9 ]

readonly level: number;

Property Value

number

line

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

[ API set: ExcelApi 1.9 ]

readonly line: Excel.Line;

Property Value

Examples

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. Read-only.

[ API set: ExcelApi 1.9 ]

readonly lineFormat: Excel.ShapeLineFormat;

Property Value

lockAspectRatio

Specifies whether or not the aspect ratio of this shape is locked.

[ API set: ExcelApi 1.9 ]

lockAspectRatio: boolean;

Property Value

boolean

Examples

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

Represents the name of the shape.

[ API set: ExcelApi 1.9 ]

name: string;

Property Value

string

parentGroup

Represents the parent group of this shape.

[ API set: ExcelApi 1.9 ]

readonly parentGroup: Excel.Shape;

Property Value

placement

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

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

[ API set: ExcelApi BETA (PREVIEW ONLY) ]

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

Property Value

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

rotation

Represents the rotation, in degrees, of the shape.

[ API set: ExcelApi 1.9 ]

rotation: number;

Property Value

number

Examples

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. Read only.

[ API set: ExcelApi 1.9 ]

readonly textFrame: Excel.TextFrame;

Property Value

top

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

[ API set: ExcelApi 1.9 ]

top: number;

Property Value

number

type

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

[ API set: ExcelApi 1.9 ]

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

Property Value

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

visible

Represents the visibility of this shape.

[ API set: ExcelApi 1.9 ]

visible: boolean;

Property Value

boolean

width

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

[ API set: ExcelApi 1.9 ]

width: number;

Property Value

number

zOrderPosition

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

[ API set: ExcelApi 1.9 ]

readonly zOrderPosition: number;

Property Value

number

Method Details

copyTo(destinationSheet)

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

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

[ API set: ExcelApi BETA (PREVIEW ONLY) ]

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

Parameters

destinationSheet
Worksheet | string

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

Returns

delete()

Removes the shape from the worksheet.

[ API set: ExcelApi 1.9 ]

delete(): void;

Returns

void

Examples

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.

[ API set: ExcelApi 1.9 ]

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

Parameters

format
Excel.PictureFormat

Specifies the format of the image.

Returns

OfficeExtension.ClientResult<string>

Examples

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.

[ API set: ExcelApi 1.9 ]

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>

incrementLeft(increment)

Moves the shape horizontally by the specified number of points.

[ API set: ExcelApi 1.9 ]

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

Examples

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.

[ API set: ExcelApi 1.9 ]

incrementRotation(increment: number): void;

Parameters

increment
number

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

Returns

void

Examples

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.

[ API set: ExcelApi 1.9 ]

incrementTop(increment: number): void;

Parameters

increment
number

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

Returns

void

Examples

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.

[ API set: ExcelApi 1.9 ]

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

Examples

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

[ API set: ExcelApi 1.9 ]

scaleHeight(scaleFactor: number, scaleTypeString: "CurrentSize" | "OriginalSize", scaleFrom?: "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.

scaleFrom
"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

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.

[ API set: ExcelApi 1.9 ]

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

scaleWidth(scaleFactor, scaleTypeString, 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.

[ API set: ExcelApi 1.9 ]

scaleWidth(scaleFactor: number, scaleTypeString: "CurrentSize" | "OriginalSize", scaleFrom?: "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.

scaleFrom
"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

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

Remarks

This method has the following additional signature:

set(properties: Excel.Shape): 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.

[ API set: ExcelApi 1.9 ]

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

Examples

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.

[ API set: ExcelApi 1.9 ]

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

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.

[ API set: ExcelApi 1.9 ]

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

Returns

OfficeExtension.EventHandlers<Excel.ShapeActivatedEventArgs>

onDeactivated

Occurs when the shape is deactivated.

[ API set: ExcelApi 1.9 ]

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

Returns

OfficeExtension.EventHandlers<Excel.ShapeDeactivatedEventArgs>