Поделиться через


ExcelScript.Shape interface

Представляет универсальный объект фигуры на листе. Фигура может быть геометрической фигурой, линией, группой фигур и т. д.

Комментарии

Примеры

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

Лист, на который будет вставлен объект фигуры. Значением по умолчанию является лист скопированной фигуры.

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

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;

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

getGeometricShape()

Возвращает геометрическую фигуру, связанную с линией. Если тип фигуры отличается от GeometricShape, возникает ошибка.

getGeometricShape(): GeometricShape;

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

getGeometricShapeType()

Указывает тип геометрической фигуры этой геометрической фигуры. Дополнительные сведения см. в этой ExcelScript.GeometricShapeType статье. Возвращает значение null , если тип фигуры не является "GeometryShape".

getGeometricShapeType(): GeometricShapeType;

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

getGroup()

Возвращает группу фигур, связанную с фигурой. Если тип фигуры отличается от GroupShape, возникает ошибка.

getGroup(): ShapeGroup;

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

getHeight()

Задает высоту фигуры (в точках). InvalidArgument Создает исключение, если задано отрицательное значение или ноль в качестве входных данных.

getHeight(): number;

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

number

getId()

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

getId(): string;

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

string

getImage()

Возвращает изображение, связанное с фигурой. Если тип фигуры отличается от Image, возникает ошибка.

getImage(): 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)

Преобразует фигуру в изображение и возвращает изображение в виде строки в кодировке base64. Число точек на дюйм: 96. Единственными поддерживаемыми форматами являются ExcelScript.PictureFormat.BMP,ExcelScript.PictureFormat.PNG ,ExcelScript.PictureFormat.JPEG и .ExcelScript.PictureFormat.GIF

getImageAsBase64(format: PictureFormat): string;

Параметры

format
ExcelScript.PictureFormat

Задает формат изображения.

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

string

getLeft()

Расстояние в пунктах от левого края фигуры до левого края листа. InvalidArgument Создает исключение, если задано отрицательное значение в качестве входных данных.

getLeft(): number;

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

number

getLevel()

Задает уровень указанной фигуры. Например, уровень 0 означает, что фигура не является частью групп; уровень 1 означает, что фигура является частью группы верхнего уровня; уровень 2 означает, что фигура является частью подгруппы верхнего уровня.

getLevel(): number;

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

number

getLine()

Возвращает линию, связанную с фигурой. Если тип фигуры отличается от Line, возникает ошибка.

getLine(): 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;

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

getLockAspectRatio()

Указывает, заблокировано ли пропорции этой фигуры.

getLockAspectRatio(): boolean;

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

boolean

getName()

Указывает имя фигуры.

getName(): string;

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

string

getParentGroup()

Указывает родительскую группу этой фигуры.

getParentGroup(): Shape;

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

getPlacement()

Представляет способ прикрепления объекта к ячейкам под ним.

getPlacement(): Placement;

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

getRotation()

Задает поворот фигуры в градусах.

getRotation(): number;

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

number

getTextFrame()

Возвращает объект рамки с текстом для фигуры.

getTextFrame(): 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;

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

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 , если тип фигуры не является "GeometryShape".

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;

Параметры

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

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