ExcelScript.Shape interface

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

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

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

delete()

Removes the shape from the worksheet.

delete(): void;

Returns

void

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

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

getGeometricShape()

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

getGeometricShape(): GeometricShape;

Returns

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

getGroup()

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

getGroup(): ShapeGroup;

Returns

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

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)

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.

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

getLineFormat()

Returns the line formatting of this shape.

getLineFormat(): ShapeLineFormat;

Returns

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

getPlacement()

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

getPlacement(): Placement;

Returns

getRotation()

Specifies the rotation, in degrees, of the shape.

getRotation(): number;

Returns

number

getTextFrame()

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

getTextFrame(): TextFrame;

Returns

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

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

setPlacement(placement)

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

setPlacement(placement: Placement): void;

Parameters

Returns

void

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