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. Число точек на дюйм: 96. Единственными поддерживаемыми форматами являются `ExcelScript.PictureFormat.BMP`,`ExcelScript.PictureFormat.PNG` ,`ExcelScript.PictureFormat.JPEG` и .`ExcelScript.PictureFormat.GIF`
getConnectionSiteCount()	Возвращает количество точек соединения на фигуре.
getFill()	Возвращает формат заливки фигуры.
getGeometricShape()	Возвращает геометрическую фигуру, связанную с линией. Если тип фигуры отличается от GeometricShape, возникает ошибка.
getGeometricShapeType()	Указывает тип геометрической фигуры этой геометрической фигуры. Дополнительные сведения см. в этой `ExcelScript.GeometricShapeType` статье. Возвращает значение `null` , если тип фигуры не является "GeometryShape".
getGroup()	Возвращает группу фигур, связанную с фигурой. Если тип фигуры отличается от GroupShape, возникает ошибка.
getHeight()	Задает высоту фигуры (в точках). `InvalidArgument` Создает исключение, если задано отрицательное значение или ноль в качестве входных данных.
getId()	Указывает идентификатор фигуры.
getImage()	Возвращает изображение, связанное с фигурой. Если тип фигуры отличается от Image, возникает ошибка.
getImageAsBase64(format)	Преобразует фигуру в изображение и возвращает изображение в виде строки в кодировке base64. Число точек на дюйм: 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` , если тип фигуры не является "GeometryShape".
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. Число точек на дюйм: 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 , если тип фигуры не является "GeometryShape".

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)

setGeometricShapeType(geometricShapeType: GeometricShapeType): void;

Параметры

geometricShapeType: ExcelScript.GeometricShapeType

Возвращаемое значение

void

setHeight(height)

setHeight(height: number): void;

Параметры

height: number

Возвращаемое значение

void

setLeft(left)

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)

setTop(top: number): void;

Параметры

top: number

Возвращаемое значение

void

setVisible(visible)

Указывает, видна ли фигура.

setVisible(visible: boolean): void;

Параметры

visible: boolean

Возвращаемое значение

void

setWidth(width)

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)

Параметры

Возвращаемое значение