ExcelScript.Shape interface

参考

包:: ExcelScript

表示工作表中的泛型形状对象。形状可以是几何形状、线条、一组形状等。

注解

示例

/**
 * 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);
}

方法

copyTo(destinationSheet)	复制并粘贴 `Shape` 对象。粘贴的形状将复制到此形状所在的同一像素位置。
delete()	从工作表删除形状。
getAltTextDescription()	指定对象的可选说明文本 `Shape` 。
getAltTextTitle()	指定对象的可选标题文本 `Shape` 。
getAsImage(format)	将形状转换为图像并将图像返回为 base64 编码字符串。 DPI 为 96。唯一支持的格式是 `ExcelScript.PictureFormat.BMP`、`ExcelScript.PictureFormat.PNG`、`ExcelScript.PictureFormat.JPEG` 和。`ExcelScript.PictureFormat.GIF`
getConnectionSiteCount()	返回此形状上的连接站点数。
getFill()	返回此形状的填充格式。
getGeometricShape()	返回与形状关联的几何形状。如果形状类型不是“GeometricShape”，则会引发错误。
getGeometricShapeType()	指定此几何形状的几何形状类型。有关详细信息，请参阅 `ExcelScript.GeometricShapeType`。 `null`如果形状类型不是“GeometricShape”，则返回。
getGroup()	返回与形状关联的形状组。如果形状类型不是“GroupShape”，则会引发错误。
getHeight()	指定形状的高度（以磅为单位）。 `InvalidArgument`使用负值或零作为输入进行设置时引发异常。
getId()	指定形状标识符。
getImage()	返回与形状关联的图像。如果形状类型不是“Image”，则会引发错误。
getImageAsBase64(format)	将形状转换为图像并将图像返回为 base64 编码字符串。 DPI 为 96。唯一支持的格式是 `ExcelScript.PictureFormat.BMP`、`ExcelScript.PictureFormat.PNG`、`ExcelScript.PictureFormat.JPEG` 和。`ExcelScript.PictureFormat.GIF`
getLeft()	从形状左侧到工作表左侧的距离（以磅为单位）。 `InvalidArgument`将负值设置为输入时引发异常。
getLevel()	指定指定形状的级别。例如，级别 0 表示形状不是任何组的一部分，级别 1 表示形状是顶级组的一部分，级别 2 表示形状是顶级子组的一部分。
getLine()	返回与形状关联的线条。如果形状类型不是“Line”，则会引发错误。
getLineFormat()	返回此形状的线条格式。
getLockAspectRatio()	指定是否锁定此形状的纵横比。
getName()	指定形状的名称。
getParentGroup()	指定此形状的父组。
getPlacement()	表示对象如何附加到其下方的单元格。
getRotation()	指定形状的旋转（以度为单位）。
getTextFrame()	返回此形状的文本框对象。
getTop()	从形状上边缘到工作表上边缘之间的距离（以磅为单位）。 `InvalidArgument`将负值设置为输入时引发异常。
getType()	返回此形状的类型。有关详细信息，请参阅 `ExcelScript.ShapeType`。
getVisible()	指定形状是否可见。
getWidth()	指定形状的宽度（以磅为单位）。 `InvalidArgument`使用负值或零作为输入进行设置时引发异常。
getZOrderPosition()	返回指定形状在 z 顺序中的位置，0 表示顺序堆栈的底部。
incrementLeft(increment)	以指定磅数水平移动形状。
incrementRotation(increment)	将形状围绕 z 轴旋转特定度数。 `rotation`使用属性设置形状的绝对旋转。
incrementTop(increment)	以指定磅数垂直移动形状。
scaleHeight(scaleFactor, scaleType, scaleFrom)	按指定因子缩放形状的高度。对于图像，你可以说明是相对于原始尺寸还是当前尺寸缩放形状。对于除图片以外的其他形状来说，缩放总是相对于其当前高度而言。
scaleWidth(scaleFactor, scaleType, scaleFrom)	按指定因子缩放形状的宽度。对于图像，你可以说明是相对于原始尺寸还是当前尺寸缩放形状。对于除图片以外的其他形状来说，缩放总是相对于其当前宽度而言。
setAltTextDescription(altTextDescription)	指定对象的可选说明文本 `Shape` 。
setAltTextTitle(altTextTitle)	指定对象的可选标题文本 `Shape` 。
setGeometricShapeType(geometricShapeType)	指定此几何形状的几何形状类型。有关详细信息，请参阅 `ExcelScript.GeometricShapeType`。 `null`如果形状类型不是“GeometricShape”，则返回。
setHeight(height)	指定形状的高度（以磅为单位）。 `InvalidArgument`使用负值或零作为输入进行设置时引发异常。
setLeft(left)	从形状左侧到工作表左侧的距离（以磅为单位）。 `InvalidArgument`将负值设置为输入时引发异常。
setLockAspectRatio(lockAspectRatio)	指定是否锁定此形状的纵横比。
setName(name)	指定形状的名称。
setPlacement(placement)	表示对象如何附加到其下方的单元格。
setRotation(rotation)	指定形状的旋转（以度为单位）。
setTop(top)	从形状上边缘到工作表上边缘之间的距离（以磅为单位）。 `InvalidArgument`将负值设置为输入时引发异常。
setVisible(visible)	指定形状是否可见。
setWidth(width)	指定形状的宽度（以磅为单位）。 `InvalidArgument`使用负值或零作为输入进行设置时引发异常。
setZOrder(position)	将指定形状沿集合的 z 顺序向上或向下移动，将其移动到其他形状的前面或后面。

方法详细信息

copyTo(destinationSheet)

复制并粘贴 Shape 对象。粘贴的形状将复制到此形状所在的同一像素位置。

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

参数

destinationSheet: ExcelScript.Worksheet | string

形状对象将粘贴到的工作表。默认值为复制形状的工作表。

ExcelScript.Shape

delete()

从工作表删除形状。

delete(): void;

void

示例

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

指定对象的可选说明文本 Shape 。

getAltTextDescription(): string;

string

getAltTextTitle()

指定对象的可选标题文本 Shape 。

getAltTextTitle(): string;

string

getAsImage(format)

警告

现已弃用此 API。

Use getImageAsBase64 instead.

将形状转换为图像并将图像返回为 base64 编码字符串。 DPI 为 96。唯一支持的格式是 ExcelScript.PictureFormat.BMP、ExcelScript.PictureFormat.PNG、ExcelScript.PictureFormat.JPEG 和。ExcelScript.PictureFormat.GIF

getAsImage(format: PictureFormat): string;

参数

format: ExcelScript.PictureFormat

指定图像的格式。

string

示例

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

返回此形状上的连接站点数。

getConnectionSiteCount(): number;

number

getFill()

返回此形状的填充格式。

getFill(): ShapeFill;

ExcelScript.ShapeFill

getGeometricShape()

返回与形状关联的几何形状。如果形状类型不是“GeometricShape”，则会引发错误。

getGeometricShape(): GeometricShape;

ExcelScript.GeometricShape

getGeometricShapeType()

指定此几何形状的几何形状类型。有关详细信息，请参阅 ExcelScript.GeometricShapeType。 null如果形状类型不是“GeometricShape”，则返回。

getGeometricShapeType(): GeometricShapeType;

ExcelScript.GeometricShapeType

getGroup()

返回与形状关联的形状组。如果形状类型不是“GroupShape”，则会引发错误。

getGroup(): ShapeGroup;

ExcelScript.ShapeGroup

getHeight()

指定形状的高度（以磅为单位）。 InvalidArgument使用负值或零作为输入进行设置时引发异常。

getHeight(): number;

number

getId()

指定形状标识符。

getId(): string;

string

getImage()

返回与形状关联的图像。如果形状类型不是“Image”，则会引发错误。

getImage(): Image;

ExcelScript.Image

示例

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

参数

format: ExcelScript.PictureFormat

指定图像的格式。

string

getLeft()

从形状左侧到工作表左侧的距离（以磅为单位）。 InvalidArgument将负值设置为输入时引发异常。

getLeft(): number;

number

getLevel()

指定指定形状的级别。例如，级别 0 表示形状不是任何组的一部分，级别 1 表示形状是顶级组的一部分，级别 2 表示形状是顶级子组的一部分。

getLevel(): number;

number

getLine()

返回与形状关联的线条。如果形状类型不是“Line”，则会引发错误。

getLine(): Line;

ExcelScript.Line

示例

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

返回此形状的线条格式。

getLineFormat(): ShapeLineFormat;

ExcelScript.ShapeLineFormat

getLockAspectRatio()

指定是否锁定此形状的纵横比。

getLockAspectRatio(): boolean;

boolean

getName()

指定形状的名称。

getName(): string;

string

getParentGroup()

指定此形状的父组。

getParentGroup(): Shape;

ExcelScript.Shape

getPlacement()

表示对象如何附加到其下方的单元格。

getPlacement(): Placement;

ExcelScript.Placement

getRotation()

指定形状的旋转（以度为单位）。

getRotation(): number;

number

getTextFrame()

返回此形状的文本框对象。

getTextFrame(): TextFrame;

ExcelScript.TextFrame

示例

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

从形状上边缘到工作表上边缘之间的距离（以磅为单位）。 InvalidArgument将负值设置为输入时引发异常。

getTop(): number;

number

getType()

返回此形状的类型。有关详细信息，请参阅 ExcelScript.ShapeType。

getType(): ShapeType;

ExcelScript.ShapeType

getVisible()

指定形状是否可见。

getVisible(): boolean;

boolean

getWidth()

指定形状的宽度（以磅为单位）。 InvalidArgument使用负值或零作为输入进行设置时引发异常。

getWidth(): number;

number

getZOrderPosition()

返回指定形状在 z 顺序中的位置，0 表示顺序堆栈的底部。

getZOrderPosition(): number;

number

incrementLeft(increment)

以指定磅数水平移动形状。

incrementLeft(increment: number): void;

参数

increment: number

该增量（以磅为单位）将水平移动形状。正值将形状向右移动，负值将形状向左移动。如果工作表是从右向左方向的，则相反：正值会将形状向左移动，负值会将形状向右移动。

void

incrementRotation(increment)

将形状围绕 z 轴旋转特定度数。 rotation使用属性设置形状的绝对旋转。

incrementRotation(increment: number): void;

参数

increment: number

形状将旋转多少度。正值顺时针旋转形状，负值逆时针旋转形状。

void

incrementTop(increment)

以指定磅数垂直移动形状。

incrementTop(increment: number): void;

参数

increment: number

增量（以磅为单位）将垂直移动形状。正值将形状向下移动，负值将形状向上移动。

void

scaleHeight(scaleFactor, scaleType, scaleFrom)

按指定因子缩放形状的高度。对于图像，你可以说明是相对于原始尺寸还是当前尺寸缩放形状。对于除图片以外的其他形状来说，缩放总是相对于其当前高度而言。

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

参数

scaleFactor: number

指定形状调整后的高度与当前或原始高度的比例。

scaleType: ExcelScript.ShapeScaleType

指定是相对于其原始大小还是当前大小缩放形状。原始大小缩放选项仅适用于图像。

scaleFrom: ExcelScript.ShapeScaleFrom

可选。指定在缩放形状时，该形状的哪一部分将保持在原有的位置。如果省略，则表示形状的左上角保留其位置。

void

scaleWidth(scaleFactor, scaleType, scaleFrom)

按指定因子缩放形状的宽度。对于图像，你可以说明是相对于原始尺寸还是当前尺寸缩放形状。对于除图片以外的其他形状来说，缩放总是相对于其当前宽度而言。

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

参数

scaleFactor: number

指定形状调整后的宽度与当前或原始宽度的比例。

scaleType: ExcelScript.ShapeScaleType

指定是相对于其原始大小还是当前大小缩放形状。原始大小缩放选项仅适用于图像。

scaleFrom: ExcelScript.ShapeScaleFrom

可选。指定在缩放形状时，该形状的哪一部分将保持在原有的位置。如果省略，则表示形状的左上角保留其位置。

void

setAltTextDescription(altTextDescription)

指定对象的可选说明文本 Shape 。

setAltTextDescription(altTextDescription: string): void;

参数

altTextDescription: string

void

setAltTextTitle(altTextTitle)

指定对象的可选标题文本 Shape 。

setAltTextTitle(altTextTitle: string): void;

参数

altTextTitle: string

void

setGeometricShapeType(geometricShapeType)

指定此几何形状的几何形状类型。有关详细信息，请参阅 ExcelScript.GeometricShapeType。 null如果形状类型不是“GeometricShape”，则返回。

setGeometricShapeType(geometricShapeType: GeometricShapeType): void;

参数

geometricShapeType: ExcelScript.GeometricShapeType

void

setHeight(height)

指定形状的高度（以磅为单位）。 InvalidArgument使用负值或零作为输入进行设置时引发异常。

setHeight(height: number): void;

参数

height: number

void

setLeft(left)

从形状左侧到工作表左侧的距离（以磅为单位）。 InvalidArgument将负值设置为输入时引发异常。

setLeft(left: number): void;

参数

left: number

void

setLockAspectRatio(lockAspectRatio)

指定是否锁定此形状的纵横比。

setLockAspectRatio(lockAspectRatio: boolean): void;

参数

lockAspectRatio: boolean

void

setName(name)

指定形状的名称。

setName(name: string): void;

参数

name: string

void

示例

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

表示对象如何附加到其下方的单元格。

setPlacement(placement: Placement): void;

参数

placement: ExcelScript.Placement

void

示例

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

指定形状的旋转（以度为单位）。

setRotation(rotation: number): void;

参数

rotation: number

void

setTop(top)

从形状上边缘到工作表上边缘之间的距离（以磅为单位）。 InvalidArgument将负值设置为输入时引发异常。

setTop(top: number): void;

参数

top: number

void

setVisible(visible)

指定形状是否可见。

setVisible(visible: boolean): void;

参数

visible: boolean

void

setWidth(width)

指定形状的宽度（以磅为单位）。 InvalidArgument使用负值或零作为输入进行设置时引发异常。

setWidth(width: number): void;

参数

width: number

void

setZOrder(position)

将指定形状沿集合的 z 顺序向上或向下移动，将其移动到其他形状的前面或后面。

setZOrder(position: ShapeZOrder): void;

参数

position: ExcelScript.ShapeZOrder

相对于其他形状移动 z 顺序堆栈中的形状的位置。有关详细信息，请参阅 ExcelScript.ShapeZOrder。

void

通过

ExcelScript.Shape interface

注解

示例

方法

方法详细信息

copyTo(destinationSheet)

参数

返回

delete()

返回

示例

getAltTextDescription()

返回

getAltTextTitle()

返回

getAsImage(format)

参数

返回

示例

getConnectionSiteCount()

返回

getFill()

返回

getGeometricShape()

返回

getGeometricShapeType()

返回

getGroup()

返回

getHeight()

返回

getId()

返回

getImage()

返回

示例

getImageAsBase64(format)

参数

返回

getLeft()

返回

getLevel()

返回

getLine()

返回

示例

getLineFormat()

返回

getLockAspectRatio()

返回

getName()

返回

getParentGroup()

返回

getPlacement()

返回

getRotation()

返回

getTextFrame()

返回

示例

getTop()

返回

getType()

返回

getVisible()

返回

getWidth()

返回

getZOrderPosition()

返回

incrementLeft(increment)

参数

返回

incrementRotation(increment)

参数

返回

incrementTop(increment)

参数