PowerPoint.ShapeCollection class
Represents the collection of shapes.
- Extends
Remarks
[ API set: PowerPointApi 1.3 ]
Properties
| context | The request context associated with the object. This connects the add-in's process to the Office host application's process. |
| items | Gets the loaded child items in this collection. |
Methods
| add |
Adds a geometric shape to the slide. Returns a |
| add |
Adds a geometric shape to the slide. Returns a |
| add |
Adds a line to the slide. Returns a |
| add |
Adds a line to the slide. Returns a |
| add |
Adds a text box to the slide with the provided text as the content. Returns a |
| get |
Gets the number of shapes in the collection. |
| get |
Gets a shape using its unique ID. An error is thrown if the shape does not exist. |
| get |
Gets a shape using its zero-based index in the collection. An error is thrown if the index is out of range. |
| get |
Gets a shape using its unique ID. If such a shape does not exist, an object with an |
| load(options) | Queues up a command to load the specified properties of the object. You must call |
| load(property |
Queues up a command to load the specified properties of the object. You must call |
| load(property |
Queues up a command to load the specified properties of the object. You must call |
| toJSON() | Overrides the JavaScript |
Property Details
context
The request context associated with the object. This connects the add-in's process to the Office host application's process.
context: RequestContext;Property Value
items
Gets the loaded child items in this collection.
readonly items: PowerPoint.Shape[];Property Value
Method Details
addGeometricShape(geometricShapeType, options)
Adds a geometric shape to the slide. Returns a Shape object that represents the new shape.
addGeometricShape(geometricShapeType: PowerPoint.GeometricShapeType, options?: PowerPoint.ShapeAddOptions): PowerPoint.Shape;Parameters
- geometricShapeType
- PowerPoint.GeometricShapeType
Specifies the type of the geometric shape. See PowerPoint.GeometricShapeType for details.
- options
- PowerPoint.ShapeAddOptions
An optional parameter to specify the additional options such as the position of the shape.
Returns
The newly inserted shape.
Remarks
[ API set: PowerPointApi 1.4 ]
Examples
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/powerpoint/shapes/shapes.yaml
// This function gets the collection of shapes on the first slide,
// and adds a hexagon shape to the collection, while specifying its
// location and size. Then it names the shape.
await PowerPoint.run(async (context) => {
const shapes = context.presentation.slides.getItemAt(0).shapes;
const hexagon = shapes.addGeometricShape(PowerPoint.GeometricShapeType.hexagon,
{
left: 100,
top: 100,
height: 150,
width: 150
});
hexagon.name = "Hexagon";
await context.sync();
});
addGeometricShape(geometricShapeTypeString, options)
Adds a geometric shape to the slide. Returns a Shape object that represents the new shape.
addGeometricShape(geometricShapeTypeString: "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", options?: PowerPoint.ShapeAddOptions): PowerPoint.Shape;Parameters
- geometricShapeTypeString
-
"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"
Specifies the type of the geometric shape. See PowerPoint.GeometricShapeType for details.
- options
- PowerPoint.ShapeAddOptions
An optional parameter to specify the additional options such as the position of the shape.
Returns
The newly inserted shape.
Remarks
addLine(connectorType, options)
Adds a line to the slide. Returns a Shape object that represents the new line.
addLine(connectorType?: PowerPoint.ConnectorType, options?: PowerPoint.ShapeAddOptions): PowerPoint.Shape;Parameters
- connectorType
- PowerPoint.ConnectorType
Specifies the connector type of the line. If not provided, straight connector type will be used. See PowerPoint.ConnectorType for details.
- options
- PowerPoint.ShapeAddOptions
An optional parameter to specify the additional options such as the position of the shape object that contains the line.
Returns
The newly inserted shape.
Remarks
[ API set: PowerPointApi 1.4 ]
Examples
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/powerpoint/shapes/shapes.yaml
// This function gets the collection of shapes on the first slide,
// and adds a line to the collection, while specifying its
// start and end points. Then it names the shape.
await PowerPoint.run(async (context) => {
const shapes = context.presentation.slides.getItemAt(0).shapes;
// For a line, left and top are the coordinates of the start point,
// while height and width are the coordinates of the end point.
const line = shapes.addLine(PowerPoint.ConnectorType.straight,
{
left: 400,
top: 200,
height: 20,
width: 150
});
line.name = "StraightLine";
await context.sync();
});
addLine(connectorTypeString, options)
Adds a line to the slide. Returns a Shape object that represents the new line.
addLine(connectorTypeString?: "Straight" | "Elbow" | "Curve", options?: PowerPoint.ShapeAddOptions): PowerPoint.Shape;Parameters
- connectorTypeString
-
"Straight" | "Elbow" | "Curve"
Specifies the connector type of the line. If not provided, straight connector type will be used. See PowerPoint.ConnectorType for details.
- options
- PowerPoint.ShapeAddOptions
An optional parameter to specify the additional options such as the position of the shape object that contains the line.
Returns
The newly inserted shape.
Remarks
addTextBox(text, options)
Adds a text box to the slide with the provided text as the content. Returns a Shape object that represents the new text box.
addTextBox(text: string, options?: PowerPoint.ShapeAddOptions): PowerPoint.Shape;Parameters
- text
-
string
Specifies the text that will be shown in the created text box.
- options
- PowerPoint.ShapeAddOptions
An optional parameter to specify the additional options such as the position of the text box.
Returns
The newly inserted shape.
Remarks
[ API set: PowerPointApi 1.4 ]
Examples
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/powerpoint/shapes/shapes.yaml
// This function gets the collection of shapes on the first slide,
// and adds a text box to the collection, while specifying its text,
// location, and size. Then it names the text box.
await PowerPoint.run(async (context) => {
const shapes = context.presentation.slides.getItemAt(0).shapes;
const textbox = shapes.addTextBox("Hello!",
{
left: 100,
top: 300,
height: 300,
width: 450
});
textbox.name = "Textbox";
return context.sync();
});
getCount()
Gets the number of shapes in the collection.
getCount(): OfficeExtension.ClientResult<number>;Returns
OfficeExtension.ClientResult<number>
The number of shapes in the collection.
Remarks
getItem(key)
Gets a shape using its unique ID. An error is thrown if the shape does not exist.
getItem(key: string): PowerPoint.Shape;Parameters
- key
-
string
The ID of the shape.
Returns
The shape with the unique ID. If such a shape does not exist, an error is thrown.
Remarks
getItemAt(index)
Gets a shape using its zero-based index in the collection. An error is thrown if the index is out of range.
getItemAt(index: number): PowerPoint.Shape;Parameters
- index
-
number
The index of the shape in the collection.
Returns
The shape at the given index. An error is thrown if index is out of range.
Remarks
[ API set: PowerPointApi 1.3 ]
Examples
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/powerpoint/tags/tags.yaml
await PowerPoint.run(async function(context) {
const slide = context.presentation.slides.getItemAt(0);
const shape = slide.shapes.getItemAt(0);
shape.tags.add("MOUNTAIN", "Denali");
await context.sync();
const myShapeTag = shape.tags.getItem("MOUNTAIN");
myShapeTag.load("key, value");
await context.sync();
console.log("Added key " + JSON.stringify(myShapeTag.key) + " with value " + JSON.stringify(myShapeTag.value));
});
getItemOrNullObject(id)
Gets a shape using its unique ID. If such a shape does not exist, an object with an isNullObject property set to true is returned.
getItemOrNullObject(id: string): PowerPoint.Shape;Parameters
- id
-
string
The ID of the shape.
Returns
The shape with the unique ID. If such a shape does not exist, an object with an isNullObject property set to true is returned.
Remarks
load(options)
Queues up a command to load the specified properties of the object. You must call context.sync() before reading the properties.
load(options?: PowerPoint.Interfaces.ShapeCollectionLoadOptions & PowerPoint.Interfaces.CollectionLoadOptions): PowerPoint.ShapeCollection;Parameters
- options
-
PowerPoint.Interfaces.ShapeCollectionLoadOptions & PowerPoint.Interfaces.CollectionLoadOptions
Provides options for which properties of the object to load.
Returns
load(propertyNames)
Queues up a command to load the specified properties of the object. You must call context.sync() before reading the properties.
load(propertyNames?: string | string[]): PowerPoint.ShapeCollection;Parameters
- propertyNames
-
string | string[]
A comma-delimited string or an array of strings that specify the properties to load.
Returns
load(propertyNamesAndPaths)
Queues up a command to load the specified properties of the object. You must call context.sync() before reading the properties.
load(propertyNamesAndPaths?: OfficeExtension.LoadOption): PowerPoint.ShapeCollection;Parameters
- propertyNamesAndPaths
- OfficeExtension.LoadOption
propertyNamesAndPaths.select is a comma-delimited string that specifies the properties to load, and propertyNamesAndPaths.expand is a comma-delimited string that specifies the navigation properties to load.
Returns
toJSON()
Overrides the JavaScript toJSON() method in order to provide more useful output when an API object is passed to JSON.stringify(). (JSON.stringify, in turn, calls the toJSON method of the object that is passed to it.) Whereas the original PowerPoint.ShapeCollection object is an API object, the toJSON method returns a plain JavaScript object (typed as PowerPoint.Interfaces.ShapeCollectionData) that contains an "items" array with shallow copies of any loaded properties from the collection's items.
toJSON(): PowerPoint.Interfaces.ShapeCollectionData;Returns
Office Add-ins
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for