Excel.Shape class

Ссылка

Пакет:: excel

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

Extends: OfficeExtension.ClientObject

Свойства

altTextDescription	Задает замещающий текст описания объекта `Shape` .
altTextTitle	Задает замещающий текст заголовка `Shape` для объекта.
connectionSiteCount	Возвращает количество точек соединения на фигуре.
context	Контекст запроса, связанный с объектом . Это соединяет процесс надстройки с процессом ведущего приложения Office.
displayName	Возвращает отображаемое имя фигуры. Только что созданная фигура имеет созданное имя, локализованное и не соответствующее ей `name`. В этом сценарии этот API можно использовать для получения имени, отображаемого в пользовательском интерфейсе.
fill	Возвращает формат заливки фигуры.
geometricShape	Возвращает геометрическую фигуру, связанную с линией. Если тип фигуры отличается от GeometricShape, возникает ошибка.
geometricShapeType	Указывает тип геометрической фигуры этой геометрической фигуры. Дополнительные сведения см. в этой `Excel.GeometricShapeType` статье. Возвращает значение `null` , если тип фигуры не является "GeometryShape".
group	Возвращает группу фигур, связанную с фигурой. Если тип фигуры отличается от GroupShape, возникает ошибка.
height	Задает высоту фигуры (в точках). `InvalidArgument` Создает исключение, если задано отрицательное значение или ноль в качестве входных данных.
id	Указывает идентификатор фигуры.
image	Возвращает изображение, связанное с фигурой. Если тип фигуры отличается от Image, возникает ошибка.
left	Расстояние в пунктах от левого края фигуры до левого края листа. `InvalidArgument` Создает исключение, если задано отрицательное значение в качестве входных данных.
level	Задает уровень указанной фигуры. Например, уровень 0 означает, что фигура не является частью групп; уровень 1 означает, что фигура является частью группы верхнего уровня; уровень 2 означает, что фигура является частью подгруппы верхнего уровня.
line	Возвращает линию, связанную с фигурой. Если тип фигуры отличается от Line, возникает ошибка.
lineFormat	Возвращает формат линии для фигуры.
lockAspectRatio	Указывает, заблокировано ли пропорции этой фигуры.
name	Указывает имя фигуры.
parentGroup	Указывает родительскую группу этой фигуры.
placement	Представляет способ прикрепления объекта к ячейкам под ним.
rotation	Задает поворот фигуры в градусах.
textFrame	Возвращает объект рамки с текстом для фигуры.
top	Расстояние в пунктах от верхнего края фигуры до верхнего края листа. `InvalidArgument` Создает исключение, если задано отрицательное значение в качестве входных данных.
type	Возвращает тип фигуры. Дополнительные сведения см. в этой `Excel.ShapeType` статье.
visible	Указывает, видна ли фигура.
width	Задает ширину фигуры (в точках). `InvalidArgument` Создает исключение, если задано отрицательное значение или ноль в качестве входных данных.
zOrderPosition	Возвращает положение указанной фигуры по оси Z. Значение 0 представляет нижнее положение по оси.

Методы

copyTo(destinationSheet)	Копирует и вставляет `Shape` объект . Вставленная фигура копируется в то же расположение пикселей, что и эта фигура.
delete()	Удаляет фигуру с листа.
getAsImage(format)	Преобразует фигуру в изображение и возвращает изображение в виде строки в кодировке base64. Число точек на дюйм: 96. Единственными поддерживаемыми форматами являются `Excel.PictureFormat.BMP`,`Excel.PictureFormat.PNG` ,`Excel.PictureFormat.JPEG` и .`Excel.PictureFormat.GIF`
getAsImage(formatString)	Преобразует фигуру в изображение и возвращает изображение в виде строки в кодировке base64. Число точек на дюйм: 96. Единственными поддерживаемыми форматами являются `Excel.PictureFormat.BMP`,`Excel.PictureFormat.PNG` ,`Excel.PictureFormat.JPEG` и .`Excel.PictureFormat.GIF`
incrementLeft(increment)	Перемещает фигуру по горизонтали на указанное число пунктов.
incrementRotation(increment)	Поворачивает фигуру по часовой стрелке относительно оси Z на указанное число градусов. Используйте свойство , `rotation` чтобы задать абсолютный поворот фигуры.
incrementTop(increment)	Перемещает фигуру по вертикали на указанное число пунктов.
load(options)	Добавляет в очередь команду для загрузки указанных свойств объекта. Перед чтением свойств требуется вызвать метод `context.sync()`.
load(propertyNames)	Добавляет в очередь команду для загрузки указанных свойств объекта. Перед чтением свойств требуется вызвать метод `context.sync()`.
load(propertyNamesAndPaths)	Добавляет в очередь команду для загрузки указанных свойств объекта. Перед чтением свойств требуется вызвать метод `context.sync()`.
scaleHeight(scaleFactor, scaleType, scaleFrom)	Масштабирует высоту фигуры с применением указанного коэффициента. Для изображений можно указать изменение масштаба фигуры относительно исходного или текущего размера. Фигуры, не являющиеся изображениями, всегда масштабируются относительно их текущей высоты.
scaleHeight(scaleFactor, scaleTypeString, scaleFromString)	Масштабирует высоту фигуры с применением указанного коэффициента. Для изображений можно указать изменение масштаба фигуры относительно исходного или текущего размера. Фигуры, не являющиеся изображениями, всегда масштабируются относительно их текущей высоты.
scaleWidth(scaleFactor, scaleType, scaleFrom)	Масштабирует ширину фигуры с применением указанного коэффициента. Для изображений можно указать изменение масштаба фигуры относительно исходного или текущего размера. Фигуры, не являющиеся изображениями, всегда масштабируются относительно их текущей ширины.
scaleWidth(scaleFactor, scaleTypeString, scaleFromString)	Масштабирует ширину фигуры с применением указанного коэффициента. Для изображений можно указать изменение масштаба фигуры относительно исходного или текущего размера. Фигуры, не являющиеся изображениями, всегда масштабируются относительно их текущей ширины.
set(properties, options)	Задает несколько свойств объекта одновременно. Можно передать обычный объект с соответствующими свойствами или другой объект API того же типа.
set(properties)	Задает несколько свойств объекта одновременно на основе существующего загруженного объекта.
setZOrder(position)	Перемещает указанную фигуру вверх или вниз по оси Z в коллекции, что переносит ее вперед или назад относительно других фигур.
setZOrder(positionString)	Перемещает указанную фигуру вверх или вниз по оси Z в коллекции, что переносит ее вперед или назад относительно других фигур.
toJSON()	Переопределяет метод JavaScript `toJSON()` , чтобы обеспечить более полезные выходные данные при передаче объекта API в `JSON.stringify()`. (`JSON.stringify`в свою очередь вызывает `toJSON` метод переданного ему объекта.) В то время как исходный объект Excel.Shape является объектом API, `toJSON` метод возвращает обычный объект JavaScript (типизированный как `Excel.Interfaces.ShapeData`), который содержит неглубокие копии всех загруженных дочерних свойств из исходного объекта.

События

onActivated	Возникает, если фигура активирована.
onDeactivated	Возникает, если фигура деактивирована.

Сведения о свойстве

altTextDescription

Задает замещающий текст описания объекта Shape .

altTextDescription: string;

Значение свойства

string

altTextTitle

Задает замещающий текст заголовка Shape для объекта.

altTextTitle: string;

Значение свойства

string

connectionSiteCount

Возвращает количество точек соединения на фигуре.

readonly connectionSiteCount: number;

Значение свойства

number

context

Контекст запроса, связанный с объектом . Это соединяет процесс надстройки с процессом ведущего приложения Office.

context: RequestContext;

Значение свойства

Excel.RequestContext

displayName

Возвращает отображаемое имя фигуры. Только что созданная фигура имеет созданное имя, локализованное и не соответствующее ей name. В этом сценарии этот API можно использовать для получения имени, отображаемого в пользовательском интерфейсе.

readonly displayName: string;

Значение свойства

string

fill

Возвращает формат заливки фигуры.

readonly fill: Excel.ShapeFill;

Значение свойства

Excel.ShapeFill

Примеры

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/44-shape/shape-create-and-delete.yaml

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Shapes");
    const shape = sheet.shapes.addGeometricShape(Excel.GeometricShapeType.smileyFace);
    shape.left = 300;
    shape.top = 100;
    shape.height = 100;
    shape.width = 100;
    shape.fill.foregroundColor = "yellow"
    await context.sync();
});

geometricShape

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

readonly geometricShape: Excel.GeometricShape;

Значение свойства

Excel.GeometricShape

geometricShapeType

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

geometricShapeType: Excel.GeometricShapeType | "LineInverse" | "Triangle" | "RightTriangle" | "Rectangle" | "Diamond" | "Parallelogram" | "Trapezoid" | "NonIsoscelesTrapezoid" | "Pentagon" | "Hexagon" | "Heptagon" | "Octagon" | "Decagon" | "Dodecagon" | "Star4" | "Star5" | "Star6" | "Star7" | "Star8" | "Star10" | "Star12" | "Star16" | "Star24" | "Star32" | "RoundRectangle" | "Round1Rectangle" | "Round2SameRectangle" | "Round2DiagonalRectangle" | "SnipRoundRectangle" | "Snip1Rectangle" | "Snip2SameRectangle" | "Snip2DiagonalRectangle" | "Plaque" | "Ellipse" | "Teardrop" | "HomePlate" | "Chevron" | "PieWedge" | "Pie" | "BlockArc" | "Donut" | "NoSmoking" | "RightArrow" | "LeftArrow" | "UpArrow" | "DownArrow" | "StripedRightArrow" | "NotchedRightArrow" | "BentUpArrow" | "LeftRightArrow" | "UpDownArrow" | "LeftUpArrow" | "LeftRightUpArrow" | "QuadArrow" | "LeftArrowCallout" | "RightArrowCallout" | "UpArrowCallout" | "DownArrowCallout" | "LeftRightArrowCallout" | "UpDownArrowCallout" | "QuadArrowCallout" | "BentArrow" | "UturnArrow" | "CircularArrow" | "LeftCircularArrow" | "LeftRightCircularArrow" | "CurvedRightArrow" | "CurvedLeftArrow" | "CurvedUpArrow" | "CurvedDownArrow" | "SwooshArrow" | "Cube" | "Can" | "LightningBolt" | "Heart" | "Sun" | "Moon" | "SmileyFace" | "IrregularSeal1" | "IrregularSeal2" | "FoldedCorner" | "Bevel" | "Frame" | "HalfFrame" | "Corner" | "DiagonalStripe" | "Chord" | "Arc" | "LeftBracket" | "RightBracket" | "LeftBrace" | "RightBrace" | "BracketPair" | "BracePair" | "Callout1" | "Callout2" | "Callout3" | "AccentCallout1" | "AccentCallout2" | "AccentCallout3" | "BorderCallout1" | "BorderCallout2" | "BorderCallout3" | "AccentBorderCallout1" | "AccentBorderCallout2" | "AccentBorderCallout3" | "WedgeRectCallout" | "WedgeRRectCallout" | "WedgeEllipseCallout" | "CloudCallout" | "Cloud" | "Ribbon" | "Ribbon2" | "EllipseRibbon" | "EllipseRibbon2" | "LeftRightRibbon" | "VerticalScroll" | "HorizontalScroll" | "Wave" | "DoubleWave" | "Plus" | "FlowChartProcess" | "FlowChartDecision" | "FlowChartInputOutput" | "FlowChartPredefinedProcess" | "FlowChartInternalStorage" | "FlowChartDocument" | "FlowChartMultidocument" | "FlowChartTerminator" | "FlowChartPreparation" | "FlowChartManualInput" | "FlowChartManualOperation" | "FlowChartConnector" | "FlowChartPunchedCard" | "FlowChartPunchedTape" | "FlowChartSummingJunction" | "FlowChartOr" | "FlowChartCollate" | "FlowChartSort" | "FlowChartExtract" | "FlowChartMerge" | "FlowChartOfflineStorage" | "FlowChartOnlineStorage" | "FlowChartMagneticTape" | "FlowChartMagneticDisk" | "FlowChartMagneticDrum" | "FlowChartDisplay" | "FlowChartDelay" | "FlowChartAlternateProcess" | "FlowChartOffpageConnector" | "ActionButtonBlank" | "ActionButtonHome" | "ActionButtonHelp" | "ActionButtonInformation" | "ActionButtonForwardNext" | "ActionButtonBackPrevious" | "ActionButtonEnd" | "ActionButtonBeginning" | "ActionButtonReturn" | "ActionButtonDocument" | "ActionButtonSound" | "ActionButtonMovie" | "Gear6" | "Gear9" | "Funnel" | "MathPlus" | "MathMinus" | "MathMultiply" | "MathDivide" | "MathEqual" | "MathNotEqual" | "CornerTabs" | "SquareTabs" | "PlaqueTabs" | "ChartX" | "ChartStar" | "ChartPlus";

Значение свойства

group

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

readonly group: Excel.ShapeGroup;

Значение свойства

Excel.ShapeGroup

Примеры

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/44-shape/shape-groups.yaml

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Shapes");

    const shapeGroup = sheet.shapes.getItem("Group").group;
    shapeGroup.ungroup();
    console.log("Shapes ungrouped");

    await context.sync();
});

height

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

height: number;

Значение свойства

number

id

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

readonly id: string;

Значение свойства

string

image

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

readonly image: Excel.Image;

Значение свойства

Excel.Image

left

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

left: number;

Значение свойства

number

level

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

readonly level: number;

Значение свойства

number

line

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

readonly line: Excel.Line;

Значение свойства

Excel.Line

Примеры

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/44-shape/shape-lines.yaml

await Excel.run(async (context) => {
    const shapes = context.workbook.worksheets.getItem("Shapes").shapes;
    const line = shapes.getItem("StraightLine").line;
    line.beginArrowheadLength = Excel.ArrowheadLength.long;
    line.beginArrowheadWidth = Excel.ArrowheadWidth.wide;
    line.beginArrowheadStyle = Excel.ArrowheadStyle.oval;

    line.endArrowheadLength = Excel.ArrowheadLength.long;
    line.endArrowheadWidth = Excel.ArrowheadWidth.wide;
    line.endArrowheadStyle = Excel.ArrowheadStyle.triangle;

    await context.sync();
});

lineFormat

Возвращает формат линии для фигуры.

readonly lineFormat: Excel.ShapeLineFormat;

Значение свойства

Excel.ShapeLineFormat

lockAspectRatio

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

lockAspectRatio: boolean;

Значение свойства

boolean

Примеры

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/44-shape/shape-move-and-order.yaml

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Shapes");
    const shape = sheet.shapes.getItem("Octagon")
    shape.lockAspectRatio = true;
    shape.scaleHeight(1.25, Excel.ShapeScaleType.currentSize);
    await context.sync();
});

name

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

name: string;

Значение свойства

string

parentGroup

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

readonly parentGroup: Excel.Shape;

Значение свойства

Excel.Shape

placement

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

placement: Excel.Placement | "TwoCell" | "OneCell" | "Absolute";

Значение свойства

Excel.Placement | "TwoCell" | "OneCell" | "Absolute"

rotation

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

rotation: number;

Значение свойства

number

Примеры

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/44-shape/shape-create-and-delete.yaml

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Shapes");
    const shape = sheet.shapes.addGeometricShape(Excel.GeometricShapeType.triangle);
    shape.left = 100;
    shape.top = 300;
    shape.height = 150;
    shape.width = 200;
    shape.rotation = 45;
    shape.fill.clear();
    await context.sync();
});

textFrame

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

readonly textFrame: Excel.TextFrame;

Значение свойства

Excel.TextFrame

top

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

top: number;

Значение свойства

number

type

Возвращает тип фигуры. Дополнительные сведения см. в этой Excel.ShapeType статье.

readonly type: Excel.ShapeType | "Unsupported" | "Image" | "GeometricShape" | "Group" | "Line";

Значение свойства

visible

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

visible: boolean;

Значение свойства

boolean

width

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

width: number;

Значение свойства

number

zOrderPosition

Возвращает положение указанной фигуры по оси Z. Значение 0 представляет нижнее положение по оси.

readonly zOrderPosition: number;

Значение свойства

number

Сведения о методе

copyTo(destinationSheet)

Копирует и вставляет Shape объект . Вставленная фигура копируется в то же расположение пикселей, что и эта фигура.

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

Параметры

destinationSheet: Excel.Worksheet | string

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

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

Excel.Shape

delete()

Удаляет фигуру с листа.

delete(): void;

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

void

Примеры

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/44-shape/shape-create-and-delete.yaml

await Excel.run(async (context) => {
    context.workbook.worksheets.getItemOrNullObject("Shapes").delete();
    const sheet = context.workbook.worksheets.add("Shapes");

    const shapes = sheet.shapes;

    // load all the shapes in the collection without loading their properties
    shapes.load("items/$none");
    await context.sync();

    shapes.items.forEach((shape) => shape.delete());
    await context.sync();
});

getAsImage(format)

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

getAsImage(format: Excel.PictureFormat): OfficeExtension.ClientResult<string>;

Параметры

format: Excel.PictureFormat

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

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

OfficeExtension.ClientResult<string>

Примеры

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/44-shape/shape-images.yaml

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Shapes");
    const shape = sheet.shapes.getItem("Image");
    const result = shape.getAsImage(Excel.PictureFormat.png);
    await context.sync();

    const imageString = result.value;
    // Your add-in would save this string as a .png file.
    console.log("The image's Base64-encoded string: " + imageString);
});

getAsImage(formatString)

getAsImage(formatString: "UNKNOWN" | "BMP" | "JPEG" | "GIF" | "PNG" | "SVG"): OfficeExtension.ClientResult<string>;

Параметры

formatString: "UNKNOWN" | "BMP" | "JPEG" | "GIF" | "PNG" | "SVG"

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

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

OfficeExtension.ClientResult<string>

incrementLeft(increment)

Перемещает фигуру по горизонтали на указанное число пунктов.

incrementLeft(increment: number): void;

Параметры

increment: number

Приращение в точках фигура будет перемещаться по горизонтали. Положительное значение перемещает фигуру вправо, а отрицательное — влево. Если лист ориентирован справа налево, это происходит наоборот: положительные значения перемещают фигуру влево, а отрицательные — вправо.

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

void

Примеры

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/44-shape/shape-move-and-order.yaml

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Shapes");
    const shape = sheet.shapes.getItem("Square")
    shape.incrementLeft(-25);
    await context.sync();
});

incrementRotation(increment)

Поворачивает фигуру по часовой стрелке относительно оси Z на указанное число градусов. Используйте свойство , rotation чтобы задать абсолютный поворот фигуры.

incrementRotation(increment: number): void;

Параметры

increment: number

На сколько градусов будет поворачиваться фигура. Положительное значение поворачивает фигуру по часовой стрелке, а отрицательное значение — против часовой стрелки.

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

void

Примеры

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/44-shape/shape-images.yaml

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Shapes");
    const shape = sheet.shapes.getItem("Image");
    shape.incrementRotation(180);
    await context.sync();
});

incrementTop(increment)

Перемещает фигуру по вертикали на указанное число пунктов.

incrementTop(increment: number): void;

Параметры

increment: number

Приращение в точках фигура будет перемещаться по вертикали. Положительное значение перемещает фигуру вниз, а отрицательное — вверх.

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

void

Примеры

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/44-shape/shape-move-and-order.yaml

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Shapes");
    const shape = sheet.shapes.getItem("Pentagon")
    shape.incrementTop(25);
    await context.sync();
});

load(options)

Добавляет в очередь команду для загрузки указанных свойств объекта. Перед чтением свойств требуется вызвать метод context.sync().

load(options?: Excel.Interfaces.ShapeLoadOptions): Excel.Shape;

Параметры

options: Excel.Interfaces.ShapeLoadOptions

Предоставляет параметры свойств объекта для загрузки.

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

Excel.Shape

load(propertyNames)

load(propertyNames?: string | string[]): Excel.Shape;

Параметры

propertyNames: string | string[]

Строка с разделителями-запятыми или массив строк, указывающих свойства для загрузки.

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

Excel.Shape

load(propertyNamesAndPaths)

load(propertyNamesAndPaths?: {
            select?: string;
            expand?: string;
        }): Excel.Shape;

Параметры

propertyNamesAndPaths: { select?: string; expand?: string; }

propertyNamesAndPaths.select — это строка с разделителями-запятыми, указывающая загружаемые свойства, и propertyNamesAndPaths.expand строка с разделителями-запятыми, указывающая загружаемые свойства навигации.

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

Excel.Shape

scaleHeight(scaleFactor, scaleType, scaleFrom)

Масштабирует высоту фигуры с применением указанного коэффициента. Для изображений можно указать изменение масштаба фигуры относительно исходного или текущего размера. Фигуры, не являющиеся изображениями, всегда масштабируются относительно их текущей высоты.

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

Параметры

scaleFactor: number

Задает отношение между высотой фигуры после ее изменения и текущей или исходной высотой.

scaleType: Excel.ShapeScaleType

Указывает, масштабируется ли фигура относительно ее исходного или текущего размера. Исходный параметр масштабирования размера работает только для изображений.

scaleFrom: Excel.ShapeScaleFrom

Необязательный параметр. Указывает, какая часть фигуры сохраняет свое положение при масштабировании фигуры. Если этот параметр опущен, он представляет левый верхний угол фигуры, сохраняя свое положение.

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

void

Примеры

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/44-shape/shape-move-and-order.yaml

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Shapes");
    const shape = sheet.shapes.getItem("Octagon")
    shape.lockAspectRatio = true;
    shape.scaleHeight(1.25, Excel.ShapeScaleType.currentSize);
    await context.sync();
});

scaleHeight(scaleFactor, scaleTypeString, scaleFromString)

scaleHeight(scaleFactor: number, scaleTypeString: "CurrentSize" | "OriginalSize", scaleFromString?: "ScaleFromTopLeft" | "ScaleFromMiddle" | "ScaleFromBottomRight"): void;

Параметры

scaleFactor: number

Задает отношение между высотой фигуры после ее изменения и текущей или исходной высотой.

scaleTypeString: "CurrentSize" | "OriginalSize"

scaleFromString: "ScaleFromTopLeft" | "ScaleFromMiddle" | "ScaleFromBottomRight"

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

void

scaleWidth(scaleFactor, scaleType, scaleFrom)

Масштабирует ширину фигуры с применением указанного коэффициента. Для изображений можно указать изменение масштаба фигуры относительно исходного или текущего размера. Фигуры, не являющиеся изображениями, всегда масштабируются относительно их текущей ширины.

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

Параметры

scaleFactor: number

Задает отношение между шириной фигуры после ее изменения и текущей или исходной ширины.

scaleType: Excel.ShapeScaleType

scaleFrom: Excel.ShapeScaleFrom

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

void

scaleWidth(scaleFactor, scaleTypeString, scaleFromString)

scaleWidth(scaleFactor: number, scaleTypeString: "CurrentSize" | "OriginalSize", scaleFromString?: "ScaleFromTopLeft" | "ScaleFromMiddle" | "ScaleFromBottomRight"): void;

Параметры

scaleFactor: number

Задает отношение между шириной фигуры после ее изменения и текущей или исходной ширины.

scaleTypeString: "CurrentSize" | "OriginalSize"

scaleFromString: "ScaleFromTopLeft" | "ScaleFromMiddle" | "ScaleFromBottomRight"

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

void

set(properties, options)

Задает несколько свойств объекта одновременно. Можно передать обычный объект с соответствующими свойствами или другой объект API того же типа.

set(properties: Interfaces.ShapeUpdateData, options?: OfficeExtension.UpdateOptions): void;

Параметры

properties: Excel.Interfaces.ShapeUpdateData

Объект JavaScript со свойствами, структурированными изоморфно по свойствам объекта, для которого вызывается метод .

options: OfficeExtension.UpdateOptions

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

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

void

set(properties)

Задает несколько свойств объекта одновременно на основе существующего загруженного объекта.

set(properties: Excel.Shape): void;

Параметры

properties: Excel.Shape

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

void

setZOrder(position)

Перемещает указанную фигуру вверх или вниз по оси Z в коллекции, что переносит ее вперед или назад относительно других фигур.

setZOrder(position: Excel.ShapeZOrder): void;

Параметры

position: Excel.ShapeZOrder

Место перемещения фигуры в стеке z-порядка относительно других фигур. Дополнительные сведения см. в этой Excel.ShapeZOrder статье.

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

void

Примеры

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/44-shape/shape-move-and-order.yaml

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Shapes");
    const shape = sheet.shapes.getItem("Octagon")
    shape.setZOrder(Excel.ShapeZOrder.sendBackward);
    await context.sync();
});

setZOrder(positionString)

setZOrder(positionString: "BringToFront" | "BringForward" | "SendToBack" | "SendBackward"): void;

Параметры

positionString: "BringToFront" | "BringForward" | "SendToBack" | "SendBackward"

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

void

toJSON()

Переопределяет метод JavaScript toJSON() , чтобы обеспечить более полезные выходные данные при передаче объекта API в JSON.stringify(). (JSON.stringifyв свою очередь вызывает toJSON метод переданного ему объекта.) В то время как исходный объект Excel.Shape является объектом API, toJSON метод возвращает обычный объект JavaScript (типизированный как Excel.Interfaces.ShapeData), который содержит неглубокие копии всех загруженных дочерних свойств из исходного объекта.

toJSON(): Excel.Interfaces.ShapeData;

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

Excel.Interfaces.ShapeData

Сведения о событии

onActivated

Возникает, если фигура активирована.

readonly onActivated: OfficeExtension.EventHandlers<Excel.ShapeActivatedEventArgs>;

Тип события

OfficeExtension.EventHandlers<Excel.ShapeActivatedEventArgs>

onDeactivated

Возникает, если фигура деактивирована.

readonly onDeactivated: OfficeExtension.EventHandlers<Excel.ShapeDeactivatedEventArgs>;

Тип события

OfficeExtension.EventHandlers<Excel.ShapeDeactivatedEventArgs>

Excel.Shape class

Комментарии

Свойства

Методы

События

Сведения о свойстве

altTextDescription

Значение свойства

Комментарии

altTextTitle

Значение свойства

Комментарии

connectionSiteCount

Значение свойства

Комментарии

context

Значение свойства

displayName

Значение свойства

Комментарии

fill

Значение свойства

Комментарии

Примеры

geometricShape

Значение свойства

Комментарии

geometricShapeType

Значение свойства

Комментарии

group

Значение свойства

Комментарии

Примеры

height

Значение свойства

Комментарии

id

Значение свойства

Комментарии

image

Значение свойства

Комментарии

left

Значение свойства

Комментарии

level

Значение свойства

Комментарии

line

Значение свойства

Комментарии

Примеры

lineFormat

Значение свойства

Комментарии

lockAspectRatio

Значение свойства

Комментарии

Примеры

name

Значение свойства

Комментарии

parentGroup

Значение свойства

Комментарии

placement

Значение свойства

Комментарии

rotation

Значение свойства

Комментарии

Примеры

textFrame

Значение свойства

Комментарии

top

Значение свойства

Комментарии

type