Excel.ShapeCollection class

Пакет:: excel

Представляет набор всех фигур листа.

Extends: OfficeExtension.ClientObject

Свойства

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

Методы

addGeometricShape(geometricShapeType)	Добавляет геометрическую фигуру на лист. Возвращает объект, `Shape` представляющий новую фигуру.
addGeometricShape(geometricShapeType)	Добавляет геометрическую фигуру на лист. Возвращает объект, `Shape` представляющий новую фигуру.
addGroup(values)	Группирует подмножество фигур на листе этой коллекции. Возвращает объект, `Shape` представляющий новую группу фигур.
addImage(base64ImageString)	Создание изображения из строки в кодировке Base64 и добавление его на лист. Возвращает объект, `Shape` представляющий новое изображение.
addLine(startLeft, startTop, endLeft, endTop, connectorType)	Добавляет линию на лист. Возвращает объект, `Shape` который представляет новую строку.
addLine(startLeft, startTop, endLeft, endTop, connectorType)	Добавляет линию на лист. Возвращает объект, `Shape` который представляет новую строку.
addLocalImageReference(address)	Создание ссылки на локальное изображение, хранящегося по адресу ячейки, и отображение ее в виде плавающей фигуры над ячейками.
addSvg(xml)	Создает изображение SVG (масштабируемая векторная графика) из строки XML и добавляет его на лист. Возвращает объект, `Shape` представляющий новое изображение.
addTextBox(text)	Добавляет текстовое поле на лист с указанным текстом в качестве содержимого. Возвращает объект, `Shape` представляющий новое текстовое поле.
getCount()	Возвращает количество фигур на листе.
getItem(key)	Получает фигуру с ее именем или идентификатором.
getItemAt(index)	Получает фигуру с помощью ее позиции в коллекции.
getItemOrNullObject(key)	Получает фигуру с ее именем или идентификатором. Если объекта-фигуры не существует, этот метод возвращает объект со свойством `isNullObject` , установленным в `true`значение . Дополнительные сведения см. в разделе Методы и свойства *OrNullObject.
load(options)	Добавляет в очередь команду для загрузки указанных свойств объекта. Перед чтением свойств требуется вызвать метод `context.sync()`.
load(propertyNames)	Добавляет в очередь команду для загрузки указанных свойств объекта. Перед чтением свойств требуется вызвать метод `context.sync()`.
load(propertyNamesAndPaths)	Добавляет в очередь команду для загрузки указанных свойств объекта. Перед чтением свойств требуется вызвать метод `context.sync()`.
toJSON()	Переопределяет метод JavaScript `toJSON()` , чтобы обеспечить более полезные выходные данные при передаче объекта API в `JSON.stringify()`. (`JSON.stringify`, в свою очередь, вызывает `toJSON` метод переданного ему объекта.) В то время как исходный `Excel.ShapeCollection` объект является объектом API, `toJSON` метод возвращает простой объект JavaScript (типизированный как `Excel.Interfaces.ShapeCollectionData`), который содержит массив «items» с неглубокими копиями любых загруженных свойств из элементов коллекции.

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

context

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

context: RequestContext;

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

Excel.RequestContext

items

Получает загруженные дочерние элементы в этой коллекции.

readonly items: Excel.Shape[];

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

Excel.Shape[]

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

addGeometricShape(geometricShapeType)

Добавляет геометрическую фигуру на лист. Возвращает объект, Shape представляющий новую фигуру.

addGeometricShape(geometricShapeType: Excel.GeometricShapeType): Excel.Shape;

Параметры

geometricShapeType: Excel.GeometricShapeType

Представляет тип геометрической фигуры. См. Excel.GeometricShapeType дополнительные сведения.

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

Excel.Shape

Примеры

// 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.hexagon);
    shape.left = 5;
    shape.top = 5;
    shape.height = 175;
    shape.width = 200;
    await context.sync();
});

addGeometricShape(geometricShapeType)

Добавляет геометрическую фигуру на лист. Возвращает объект, Shape представляющий новую фигуру.

addGeometricShape(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.Shape;

Параметры

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 дополнительные сведения.

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

Excel.Shape

addGroup(values)

Группирует подмножество фигур на листе этой коллекции. Возвращает объект, Shape представляющий новую группу фигур.

addGroup(values: Array<string | Shape>): Excel.Shape;

Параметры

values: Array<string | Excel.Shape>

Массив идентификаторов фигур или объектов фигур.

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

Excel.Shape

Примеры

// 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 square = sheet.shapes.getItem("Square");
    const pentagon = sheet.shapes.getItem("Pentagon");
    const octagon = sheet.shapes.getItem("Octagon");

    const shapeGroup = sheet.shapes.addGroup([square, pentagon, octagon]);
    shapeGroup.name = "Group";
    console.log("Shapes grouped");

    await context.sync();
});

addImage(base64ImageString)

Создание изображения из строки в кодировке Base64 и добавление его на лист. Возвращает объект, Shape представляющий новое изображение.

addImage(base64ImageString: string): Excel.Shape;

Параметры

base64ImageString: string

Строка в кодировке Base64, представляющая изображение в формате JPEG или PNG.

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

Excel.Shape

Примеры

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

const myFile = document.getElementById("selectedFile") as HTMLInputElement;
const reader = new FileReader();

reader.onload = (event) => {
    Excel.run((context) => {
        const startIndex = reader.result.toString().indexOf("base64,");
        const myBase64 = reader.result.toString().substr(startIndex + 7);
        const sheet = context.workbook.worksheets.getItem("Shapes");
        const image = sheet.shapes.addImage(myBase64);
        image.name = "Image";
        return context.sync();
    });
};

// Read in the image file as a data URL.
reader.readAsDataURL(myFile.files[0]);

addLine(startLeft, startTop, endLeft, endTop, connectorType)

Добавляет линию на лист. Возвращает объект, Shape который представляет новую строку.

addLine(startLeft: number, startTop: number, endLeft: number, endTop: number, connectorType?: Excel.ConnectorType): Excel.Shape;

Параметры

startLeft: number

Расстояние в точках от начала строки до левого края листа.

startTop: number

Расстояние (в точках) от начала строки до верха листа.

endLeft: number

Расстояние в точках от конца строки до левого края листа.

endTop: number

Расстояние (в точках) от конца строки до верхнего края листа.

connectorType: Excel.ConnectorType

Представляет тип соединителя. См. Excel.ConnectorType дополнительные сведения.

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

Excel.Shape

Примеры

// 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.addLine(200, 50, 300, 150, Excel.ConnectorType.straight);
    line.name = "StraightLine";
    await context.sync();
});

addLine(startLeft, startTop, endLeft, endTop, connectorType)

Добавляет линию на лист. Возвращает объект, Shape который представляет новую строку.

addLine(startLeft: number, startTop: number, endLeft: number, endTop: number, connectorType?: "Straight" | "Elbow" | "Curve"): Excel.Shape;

Параметры

startLeft: number

Расстояние в точках от начала строки до левого края листа.

startTop: number

Расстояние (в точках) от начала строки до верха листа.

endLeft: number

Расстояние в точках от конца строки до левого края листа.

endTop: number

Расстояние (в точках) от конца строки до верхнего края листа.

connectorType: "Straight" | "Elbow" | "Curve"

Представляет тип соединителя. См. Excel.ConnectorType дополнительные сведения.

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

Excel.Shape

addLocalImageReference(address)

Примечание

Этот API предоставляется в качестве предварительной версии для разработчиков и может быть изменен на основе полученных нами отзывов. Не используйте этот API в рабочей среде.

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

addLocalImageReference(address: string): Excel.Shape;

Параметры

address: string

Адрес ячейки, содержащей локальное изображение.

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

Excel.Shape

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

addSvg(xml)

Примечание

Создает изображение SVG (масштабируемая векторная графика) из строки XML и добавляет его на лист. Возвращает объект, Shape представляющий новое изображение.

addSvg(xml: string): Excel.Shape;

Параметры

xml: string

Строка XML, представляющая SVG.

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

Excel.Shape

addTextBox(text)

Добавляет текстовое поле на лист с указанным текстом в качестве содержимого. Возвращает объект, Shape представляющий новое текстовое поле.

addTextBox(text?: string): Excel.Shape;

Параметры

text: string

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

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

Excel.Shape

Примеры

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

await Excel.run(async (context) => {
    const shapes = context.workbook.worksheets.getItem("Shapes").shapes;
    const textbox: Excel.Shape = shapes.addTextBox("A box with text");
    textbox.left = 100;
    textbox.top = 100;
    textbox.height = 20;
    textbox.width = 175;
    textbox.name = "Textbox";
    await context.sync();
});

getCount()

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

getCount(): OfficeExtension.ClientResult<number>;

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

OfficeExtension.ClientResult<number>

getItem(key)

Получает фигуру с ее именем или идентификатором.

getItem(key: string): Excel.Shape;

Параметры

key: string

Имя или идентификатор фигуры, которую нужно извлечь.

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

Excel.Shape

Примеры

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

getItemAt(index)

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

getItemAt(index: number): Excel.Shape;

Параметры

index: number

Отсчитываемый от нуля индекс фигуры, который нужно извлечь.

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

Excel.Shape

getItemOrNullObject(key)

Получает фигуру с ее именем или идентификатором. Если объекта-фигуры не существует, этот метод возвращает объект со свойством isNullObject , установленным в trueзначение . Дополнительные сведения см. в разделе Методы и свойства *OrNullObject.

getItemOrNullObject(key: string): Excel.Shape;

Параметры

key: string

Имя или идентификатор фигуры, которую нужно извлечь.

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

Excel.Shape

load(options)

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

load(options?: Excel.Interfaces.ShapeCollectionLoadOptions & Excel.Interfaces.CollectionLoadOptions): Excel.ShapeCollection;

Параметры

options: Excel.Interfaces.ShapeCollectionLoadOptions & Excel.Interfaces.CollectionLoadOptions

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

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

Excel.ShapeCollection

load(propertyNames)

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

Параметры

propertyNames: string | string[]

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

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

Excel.ShapeCollection

load(propertyNamesAndPaths)

load(propertyNamesAndPaths?: OfficeExtension.LoadOption): Excel.ShapeCollection;

Параметры

propertyNamesAndPaths: OfficeExtension.LoadOption

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

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

Excel.ShapeCollection

toJSON()

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

toJSON(): Excel.Interfaces.ShapeCollectionData;

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

Excel.Interfaces.ShapeCollectionData

Обратная связь

Были ли сведения на этой странице полезными?

Excel.ShapeCollection class

Комментарии

Используется

Свойства

Методы

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

context

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

items

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

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

addGeometricShape(geometricShapeType)

Параметры

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

Комментарии

Примеры

addGeometricShape(geometricShapeType)

Параметры

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

Комментарии

addGroup(values)

Параметры

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

Комментарии

Примеры

addImage(base64ImageString)

Параметры

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

Комментарии

Примеры

addLine(startLeft, startTop, endLeft, endTop, connectorType)

Параметры

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

Комментарии

Примеры

addLine(startLeft, startTop, endLeft, endTop, connectorType)

Параметры

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

Комментарии

addLocalImageReference(address)

Параметры

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

Комментарии

addSvg(xml)

Параметры

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

Комментарии

addTextBox(text)

Параметры

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

Комментарии

Примеры

getCount()

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

Комментарии

getItem(key)

Параметры

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

Комментарии

Примеры

getItemAt(index)

Параметры

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

Комментарии

getItemOrNullObject(key)

Параметры

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

Комментарии

load(options)

Параметры

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

load(propertyNames)

Параметры

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

load(propertyNamesAndPaths)

Параметры

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

toJSON()

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

Обратная связь