Excel.Shape class

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

[Набор API: ExcelApi 1,9]

Extends

Свойства

altTextDescription

Задает текст альтернативного описания для объекта Shape.

[Набор API: ExcelApi 1,9]

altTextTitle

Указывает альтернативный текст заголовка для объекта Shape.

[Набор API: ExcelApi 1,9]

connectionSiteCount

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

[Набор API: ExcelApi 1,9]

context

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

fill

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

[Набор API: ExcelApi 1,9]

geometricShape

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

[Набор API: ExcelApi 1,9]

geometricShapeType

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

[Набор API: ExcelApi 1,9]

group

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

[Набор API: ExcelApi 1,9]

height

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

[Набор API: ExcelApi 1,9]

id

Задает идентификатор фигуры.

[Набор API: ExcelApi 1,9]

image

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

[Набор API: ExcelApi 1,9]

left

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

[Набор API: ExcelApi 1,9]

level

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

[Набор API: ExcelApi 1,9]

line

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

[Набор API: ExcelApi 1,9]

lineFormat

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

[Набор API: ExcelApi 1,9]

lockAspectRatio

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

[Набор API: ExcelApi 1,9]

name

Задает имя фигуры.

[Набор API: ExcelApi 1,9]

parentGroup

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

[Набор API: ExcelApi 1,9]

placement

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

[Набор API: ExcelApi 1,10]

rotation

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

[Набор API: ExcelApi 1,9]

textFrame

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

[Набор API: ExcelApi 1,9]

top

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

[Набор API: ExcelApi 1,9]

type

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

[Набор API: ExcelApi 1,9]

visible

Указывает, отображается ли фигура.

[Набор API: ExcelApi 1,9]

width

Задает ширину фигуры в пунктах. При задании с отрицательным значением или нулем в качестве входных данных создается исключение недопустимого аргумента.

[Набор API: ExcelApi 1,9]

zOrderPosition

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

[Набор API: ExcelApi 1,9]

Методы

copyTo(destinationSheet)

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

[Набор API: ExcelApi 1,10]

delete()

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

[Набор API: ExcelApi 1,9]

getAsImage(format)

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

[Набор API: ExcelApi 1,9]

getAsImage(formatString)

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

[Набор API: ExcelApi 1,9]

incrementLeft(increment)

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

[Набор API: ExcelApi 1,9]

incrementRotation(increment)

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

[Набор API: ExcelApi 1,9]

incrementTop(increment)

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

[Набор API: ExcelApi 1,9]

load(options)

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

load(propertyNames)

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

load(propertyNamesAndPaths)

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

scaleHeight(scaleFactor, scaleType, scaleFrom)

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

[Набор API: ExcelApi 1,9]

scaleHeight(scaleFactor, scaleTypeString, scaleFrom)

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

[Набор API: ExcelApi 1,9]

scaleWidth(scaleFactor, scaleType, scaleFrom)

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

[Набор API: ExcelApi 1,9]

scaleWidth(scaleFactor, scaleTypeString, scaleFrom)

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

[Набор API: ExcelApi 1,9]

set(properties, options)

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

set(properties)

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

setZOrder(position)

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

[Набор API: ExcelApi 1,9]

setZOrder(positionString)

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

[Набор API: ExcelApi 1,9]

toJSON()

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

События

onActivated

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

[Набор API: ExcelApi 1,9]

onDeactivated

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

[Набор API: ExcelApi 1,9]

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

altTextDescription

Задает текст альтернативного описания для объекта Shape.

[Набор API: ExcelApi 1,9]

altTextDescription: string;

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

string

altTextTitle

Указывает альтернативный текст заголовка для объекта Shape.

[Набор API: ExcelApi 1,9]

altTextTitle: string;

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

string

connectionSiteCount

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

[Набор API: ExcelApi 1,9]

readonly connectionSiteCount: number;

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

number

context

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

context: RequestContext;

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

fill

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

[Набор API: ExcelApi 1,9]

readonly fill: Excel.ShapeFill;

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

Примеры

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/master/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, возникает ошибка.

[Набор API: ExcelApi 1,9]

readonly geometricShape: Excel.GeometricShape;

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

geometricShapeType

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

[Набор API: ExcelApi 1,9]

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";

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

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, возникает ошибка.

[Набор API: ExcelApi 1,9]

readonly group: Excel.ShapeGroup;

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

Примеры

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/master/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

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

[Набор API: ExcelApi 1,9]

height: number;

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

number

id

Задает идентификатор фигуры.

[Набор API: ExcelApi 1,9]

readonly id: string;

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

string

image

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

[Набор API: ExcelApi 1,9]

readonly image: Excel.Image;

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

left

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

[Набор API: ExcelApi 1,9]

left: number;

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

number

level

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

[Набор API: ExcelApi 1,9]

readonly level: number;

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

number

line

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

[Набор API: ExcelApi 1,9]

readonly line: Excel.Line;

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

Примеры

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/master/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

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

[Набор API: ExcelApi 1,9]

readonly lineFormat: Excel.ShapeLineFormat;

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

lockAspectRatio

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

[Набор API: ExcelApi 1,9]

lockAspectRatio: boolean;

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

boolean

Примеры

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/master/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

Задает имя фигуры.

[Набор API: ExcelApi 1,9]

name: string;

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

string

parentGroup

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

[Набор API: ExcelApi 1,9]

readonly parentGroup: Excel.Shape;

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

placement

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

[Набор API: ExcelApi 1,10]

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

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

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

rotation

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

[Набор API: ExcelApi 1,9]

rotation: number;

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

number

Примеры

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/master/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

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

[Набор API: ExcelApi 1,9]

readonly textFrame: Excel.TextFrame;

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

top

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

[Набор API: ExcelApi 1,9]

top: number;

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

number

type

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

[Набор API: ExcelApi 1,9]

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

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

Excel.ShapeType | "Unsupported" | "Image" | "GeometricShape" | "Group" | "Line"

visible

Указывает, отображается ли фигура.

[Набор API: ExcelApi 1,9]

visible: boolean;

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

boolean

width

Задает ширину фигуры в пунктах. При задании с отрицательным значением или нулем в качестве входных данных создается исключение недопустимого аргумента.

[Набор API: ExcelApi 1,9]

width: number;

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

number

zOrderPosition

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

[Набор API: ExcelApi 1,9]

readonly zOrderPosition: number;

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

number

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

copyTo(destinationSheet)

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

[Набор API: ExcelApi 1,10]

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

Параметры

destinationSheet
Worksheet | string

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

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

delete()

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

[Набор API: ExcelApi 1,9]

delete(): void;

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

void

Примеры

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/master/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.

[Набор API: ExcelApi 1,9]

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

Параметры

format
Excel.PictureFormat

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

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

Примеры

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/master/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)

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

[Набор API: ExcelApi 1,9]

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

Параметры

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

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

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

incrementLeft(increment)

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

[Набор API: ExcelApi 1,9]

incrementLeft(increment: number): void;

Параметры

increment
number

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

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

void

Примеры

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/master/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 свойство, чтобы задать абсолютный поворот фигуры.

[Набор API: ExcelApi 1,9]

incrementRotation(increment: number): void;

Параметры

increment
number

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

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

void

Примеры

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/master/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)

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

[Набор API: ExcelApi 1,9]

incrementTop(increment: number): void;

Параметры

increment
number

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

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

void

Примеры

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/master/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

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

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

load(propertyNames)

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

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

Параметры

propertyNames
string | string[]

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

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

load(propertyNamesAndPaths)

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

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

Параметры

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

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

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

scaleHeight(scaleFactor, scaleType, scaleFrom)

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

[Набор API: ExcelApi 1,9]

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/master/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, scaleFrom)

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

[Набор API: ExcelApi 1,9]

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

Параметры

scaleFactor
number

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

scaleTypeString
"CurrentSize" | "OriginalSize"

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

scaleFrom
"ScaleFromTopLeft" | "ScaleFromMiddle" | "ScaleFromBottomRight"

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

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

void

scaleWidth(scaleFactor, scaleType, scaleFrom)

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

[Набор API: ExcelApi 1,9]

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

Параметры

scaleFactor
number

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

scaleType
Excel.ShapeScaleType

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

scaleFrom
Excel.ShapeScaleFrom

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

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

void

scaleWidth(scaleFactor, scaleTypeString, scaleFrom)

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

[Набор API: ExcelApi 1,9]

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

Параметры

scaleFactor
number

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

scaleTypeString
"CurrentSize" | "OriginalSize"

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

scaleFrom
"ScaleFromTopLeft" | "ScaleFromMiddle" | "ScaleFromBottomRight"

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

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

void

set(properties, options)

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

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

Параметры

properties
Interfaces.ShapeUpdateData

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

options
OfficeExtension.UpdateOptions

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

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

void

Комментарии

Этот метод имеет следующую дополнительную подпись:

set(properties: Excel.Shape): void

set(properties)

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

set(properties: Excel.Shape): void;

Параметры

properties
Excel.Shape

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

void

setZOrder(position)

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

[Набор API: ExcelApi 1,9]

setZOrder(position: Excel.ShapeZOrder): void;

Параметры

position
Excel.ShapeZOrder

Место перемещения фигуры в стеке z по отношению к другим фигурам. Дополнительные сведения см. в статье Excel. Шапезордер.

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

void

Примеры

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/master/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)

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

[Набор API: ExcelApi 1,9]

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

Параметры

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

Место перемещения фигуры в стеке z по отношению к другим фигурам. Дополнительные сведения см. в статье Excel. Шапезордер.

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

void

toJSON()

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

toJSON(): Excel.Interfaces.ShapeData;

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

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

onActivated

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

[Набор API: ExcelApi 1,9]

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

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

onDeactivated

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

[Набор API: ExcelApi 1,9]

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

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