ExcelScript.Shape interface

Reference

Package:: ExcelScript

Represents a generic shape object in the worksheet. A shape could be a geometric shape, a line, a group of shapes, etc.

Remarks

Examples

/**
 * This script creates a hexagon shape on the current worksheet.
 */
function main(workbook: ExcelScript.Workbook) {
  const currentSheet = workbook.getActiveWorksheet();
  const hexagon: ExcelScript.Shape = 
    currentSheet.addGeometricShape(ExcelScript.GeometricShapeType.hexagon);
  
  // Set the hexagon size to 40x40 pixels.
  hexagon.setHeight(40);
  hexagon.setWidth(40);

  // Position the hexagon at [100,100] pixels.
  hexagon.setLeft(100);
  hexagon.setTop(100);
}

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.
getAltTextDescription()	Specifies the alternative description text for a `Shape` object.
getAltTextTitle()	Specifies the alternative title text for a `Shape` object.
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 `ExcelScript.PictureFormat.BMP`, `ExcelScript.PictureFormat.PNG`, `ExcelScript.PictureFormat.JPEG`, and `ExcelScript.PictureFormat.GIF`.
getConnectionSiteCount()	Returns the number of connection sites on this shape.
getFill()	Returns the fill formatting of this shape.
getGeometricShape()	Returns the geometric shape associated with the shape. An error will be thrown if the shape type is not "GeometricShape".
getGeometricShapeType()	Specifies the geometric shape type of this geometric shape. See `ExcelScript.GeometricShapeType` for details. Returns `null` if the shape type is not "GeometricShape".
getGroup()	Returns the shape group associated with the shape. An error will be thrown if the shape type is not "GroupShape".
getHeight()	Specifies the height, in points, of the shape. Throws an `InvalidArgument` exception when set with a negative value or zero as an input.
getId()	Specifies the shape identifier.
getImage()	Returns the image associated with the shape. An error will be thrown if the shape type is not "Image".
getImageAsBase64(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 `ExcelScript.PictureFormat.BMP`, `ExcelScript.PictureFormat.PNG`, `ExcelScript.PictureFormat.JPEG`, and `ExcelScript.PictureFormat.GIF`.
getLeft()	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.
getLevel()	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.
getLine()	Returns the line associated with the shape. An error will be thrown if the shape type is not "Line".
getLineFormat()	Returns the line formatting of this shape.
getLockAspectRatio()	Specifies if the aspect ratio of this shape is locked.
getName()	Specifies the name of the shape.
getParentGroup()	Specifies the parent group of this shape.
getPlacement()	Represents how the object is attached to the cells below it.
getRotation()	Specifies the rotation, in degrees, of the shape.
getTextFrame()	Returns the text frame object of this shape.
getTop()	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.
getType()	Returns the type of this shape. See `ExcelScript.ShapeType` for details.
getVisible()	Specifies if the shape is visible.
getWidth()	Specifies the width, in points, of the shape. Throws an `InvalidArgument` exception when set with a negative value or zero as an input.
getZOrderPosition()	Returns the position of the specified shape in the z-order, with 0 representing the bottom of the order stack.
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.
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.
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.
setAltTextDescription(altTextDescription)	Specifies the alternative description text for a `Shape` object.
setAltTextTitle(altTextTitle)	Specifies the alternative title text for a `Shape` object.
setGeometricShapeType(geometricShapeType)	Specifies the geometric shape type of this geometric shape. See `ExcelScript.GeometricShapeType` for details. Returns `null` if the shape type is not "GeometricShape".
setHeight(height)	Specifies the height, in points, of the shape. Throws an `InvalidArgument` exception when set with a negative value or zero as an input.
setLeft(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.
setLockAspectRatio(lockAspectRatio)	Specifies if the aspect ratio of this shape is locked.
setName(name)	Specifies the name of the shape.
setPlacement(placement)	Represents how the object is attached to the cells below it.
setRotation(rotation)	Specifies the rotation, in degrees, of the shape.
setTop(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.
setVisible(visible)	Specifies if the shape is visible.
setWidth(width)	Specifies the width, in points, of the shape. Throws an `InvalidArgument` exception when set with a negative value or zero as an input.
setZOrder(position)	Moves the specified shape up or down the collection's z-order, which shifts it in front of or behind other shapes.

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): Shape;

Parameters

destinationSheet: ExcelScript.Worksheet | string

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

Returns

ExcelScript.Shape

delete()

Removes the shape from the worksheet.

delete(): void;

Returns

void

Examples

/**
 * This script deletes all the shapes on the current worksheet.
 */
function main(workbook: ExcelScript.Workbook) {
  // Get the collection of shapes on the currently selected worksheet.
  const shapes = workbook.getActiveWorksheet().getShapes();

  // Remove each shape.
  shapes.forEach(shape =>{
    shape.delete();
  });
}

getAltTextDescription()

Specifies the alternative description text for a Shape object.

getAltTextDescription(): string;

Returns

string

getAltTextTitle()

Specifies the alternative title text for a Shape object.

getAltTextTitle(): string;

Returns

string

getAsImage(format)

Warning

This API is now deprecated.

Use getImageAsBase64 instead.

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

getAsImage(format: PictureFormat): string;

Parameters

format: ExcelScript.PictureFormat

Specifies the format of the image.

Returns

string

Examples

/**
 * This script creates a star shape with the value from cell A1.
 * It then returns the image as a base64-encoded string. 
 * This string would be used as part of a Power Automate flow to add the image elsewhere.
 */
function main(workbook: ExcelScript.Workbook) {
  // Get the value of A1 from the worksheet named Sheet1.
  const sheet = workbook.getWorksheet("Sheet1");
  const value = sheet.getRange("A1").getValue();

  // Create a Shape object that looks like a 5-pointed star.
  const star = sheet.addGeometricShape(ExcelScript.GeometricShapeType.star5);

  // Set the text of star and make sure the shape fits the text.
  const textFrame = star.getTextFrame();
  textFrame.getTextRange().setText(value.toString());
  textFrame.setAutoSizeSetting(ExcelScript.ShapeAutoSize.autoSizeShapeToFitText);

  // Return the shape as a PNG image represented by a base64-encoded string.
  return star.getAsImage(ExcelScript.PictureFormat.png);
}

getConnectionSiteCount()

Returns the number of connection sites on this shape.

getConnectionSiteCount(): number;

Returns

number

getFill()

Returns the fill formatting of this shape.

getFill(): ShapeFill;

Returns

ExcelScript.ShapeFill

getGeometricShape()

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

getGeometricShape(): GeometricShape;

Returns

ExcelScript.GeometricShape

getGeometricShapeType()

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

getGeometricShapeType(): GeometricShapeType;

Returns

ExcelScript.GeometricShapeType

getGroup()

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

getGroup(): ShapeGroup;

Returns

ExcelScript.ShapeGroup

getHeight()

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

getHeight(): number;

Returns

number

getId()

Specifies the shape identifier.

getId(): string;

Returns

string

getImage()

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

getImage(): Image;

Returns

ExcelScript.Image

Examples

/**
 * This script transfers an image from one worksheet to another.
 */
function main(workbook: ExcelScript.Workbook)
{
  // Get the worksheet with the image on it.
  let firstWorksheet = workbook.getWorksheet("FirstSheet");

  // Get the first image from the worksheet.
  // If a script added the image, you could add a name to make it easier to find.
  let image: ExcelScript.Image;
  firstWorksheet.getShapes().forEach((shape, index) => {
    if (shape.getType() === ExcelScript.ShapeType.image) {
      image = shape.getImage();
      return;
    }
  });

  // Copy the image to another worksheet.
  image.getShape().copyTo("SecondSheet");
}

getImageAsBase64(format)

getImageAsBase64(format: PictureFormat): string;

Parameters

format: ExcelScript.PictureFormat

Specifies the format of the image.

Returns

string

getLeft()

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.

getLeft(): number;

Returns

number

getLevel()

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.

getLevel(): number;

Returns

number

getLine()

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

getLine(): Line;

Returns

ExcelScript.Line

Examples

/**
 * This script adds a line that goes from cell B2 to cell F4 on the current worksheet.
 */ 
function main(workbook: ExcelScript.Workbook) {
  // Get the current worksheet.
  const sheet = workbook.getActiveWorksheet();

  // Get the ranges for the two cells.
  const b2Range = sheet.getRange("B2");
  const f4Range = sheet.getRange("F4");

  // Add a straight line that connects the top-left corners of both cells.
  const newShape = sheet.addLine(
    b2Range.getLeft(),
    b2Range.getTop(),
    f4Range.getLeft(),
    f4Range.getTop(),
    ExcelScript.ConnectorType.straight);

  // Add an open arrowhead to the end of the line, such that it points at F4.
  const line = newShape.getLine();
  line.setEndArrowheadStyle(ExcelScript.ArrowheadStyle.open);
}

getLineFormat()

Returns the line formatting of this shape.

getLineFormat(): ShapeLineFormat;

Returns

ExcelScript.ShapeLineFormat

getLockAspectRatio()

Specifies if the aspect ratio of this shape is locked.

getLockAspectRatio(): boolean;

Returns

boolean

getName()

Specifies the name of the shape.

getName(): string;

Returns

string

getParentGroup()

Specifies the parent group of this shape.

getParentGroup(): Shape;

Returns

ExcelScript.Shape

getPlacement()

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

getPlacement(): Placement;

Returns

ExcelScript.Placement

getRotation()

Specifies the rotation, in degrees, of the shape.

getRotation(): number;

Returns

number

getTextFrame()

Returns the text frame object of this shape.

getTextFrame(): TextFrame;

Returns

ExcelScript.TextFrame

Examples

/**
 * This script creates a star shape with the value from cell A1.
 */
function main(workbook: ExcelScript.Workbook) {
  // Get the value of A1 from the worksheet named Sheet1.
  const sheet = workbook.getWorksheet("Sheet1");
  const value = sheet.getRange("A1").getValue();

  // Create a Shape object that looks like a 5-pointed star.
  const star = sheet.addGeometricShape(ExcelScript.GeometricShapeType.star5);

  // Set the text of star and make sure the shape fits the text.
  const textFrame = star.getTextFrame();
  textFrame.getTextRange().setText(value.toString());
  textFrame.setAutoSizeSetting(ExcelScript.ShapeAutoSize.autoSizeShapeToFitText);
}

getTop()

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.

getTop(): number;

Returns

number

getType()

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

getType(): ShapeType;

Returns

ExcelScript.ShapeType

getVisible()

Specifies if the shape is visible.

getVisible(): boolean;

Returns

boolean

getWidth()

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

getWidth(): number;

Returns

number

getZOrderPosition()

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

getZOrderPosition(): number;

Returns

number

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

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

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

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: ShapeScaleType,
            scaleFrom?: 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: ExcelScript.ShapeScaleType

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

scaleFrom: ExcelScript.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, 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: ShapeScaleType,
            scaleFrom?: 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: ExcelScript.ShapeScaleType

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

scaleFrom: ExcelScript.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

setAltTextDescription(altTextDescription)

Specifies the alternative description text for a Shape object.

setAltTextDescription(altTextDescription: string): void;

Parameters

altTextDescription: string

Returns

void

setAltTextTitle(altTextTitle)

Specifies the alternative title text for a Shape object.

setAltTextTitle(altTextTitle: string): void;

Parameters

altTextTitle: string

Returns

void

setGeometricShapeType(geometricShapeType)

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

setGeometricShapeType(geometricShapeType: GeometricShapeType): void;

Parameters

geometricShapeType: ExcelScript.GeometricShapeType

Returns

void

setHeight(height)

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

setHeight(height: number): void;

Parameters

height: number

Returns

void

setLeft(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.

setLeft(left: number): void;

Parameters

left: number

Returns

void

setLockAspectRatio(lockAspectRatio)

Specifies if the aspect ratio of this shape is locked.

setLockAspectRatio(lockAspectRatio: boolean): void;

Parameters

lockAspectRatio: boolean

Returns

void

setName(name)

Specifies the name of the shape.

setName(name: string): void;

Parameters

name: string

Returns

void

Examples

/**
 * This script creates a triangle shape on the current worksheet and names it "TRI".
 */
function main(workbook: ExcelScript.Workbook) {
  const currentSheet = workbook.getActiveWorksheet();
  const triangle: ExcelScript.Shape = 
    currentSheet.addGeometricShape(ExcelScript.GeometricShapeType.triangle);
  
  triangle.setName("TRI");
}

setPlacement(placement)

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

setPlacement(placement: Placement): void;

Parameters

placement: ExcelScript.Placement

Returns

void

Examples

/**
 * This script creates a diamond shape at cell C3.
 * The shape moves and resizes as the grid underneath it changes.
 */
function main(workbook: ExcelScript.Workbook) {
  // Get cell C3 in the current worksheet.
  const sheet = workbook.getActiveWorksheet();
  const cell = sheet.getRange("C3");

  // Create a diamond that slightly overlaps the cell C3.
  const diamond = sheet.addGeometricShape(ExcelScript.GeometricShapeType.diamond);
  // Set each dimension so that the shape extends 5 pixels beyond the cell borders.
  diamond.setLeft(cell.getLeft() - 5);
  diamond.setTop(cell.getTop() - 5);
  diamond.setHeight(cell.getHeight() + 10);
  diamond.setWidth(cell.getWidth() + 10);

  // Set the placement of the shape so that it resizes and moves with the grid.
  diamond.setPlacement(ExcelScript.Placement.twoCell);
}

setRotation(rotation)

Specifies the rotation, in degrees, of the shape.

setRotation(rotation: number): void;

Parameters

rotation: number

Returns

void

setTop(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.

setTop(top: number): void;

Parameters

top: number

Returns

void

setVisible(visible)

Specifies if the shape is visible.

setVisible(visible: boolean): void;

Parameters

visible: boolean

Returns

void

setWidth(width)

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

setWidth(width: number): void;

Parameters

width: number

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: ShapeZOrder): void;

Parameters

position: ExcelScript.ShapeZOrder

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

Returns

void