PowerPoint.ShapeScopedCollection class
Represents a collection of shapes.
- Extends
[ API set: PowerPointApi 1.5 ]
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/powerpoint/shapes/get-set-shapes.yaml
// Changes the selected shapes fill color to red.
await PowerPoint.run(async (context) => {
const shapes: PowerPoint.ShapeScopedCollection = context.presentation.getSelectedShapes();
const shapeCount = shapes.getCount();
shapes.load("items");
await context.sync();
shapes.items.map((shape) => {
shape.fill.setSolidColor("red");
});
await context.sync();
});
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. |
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 |
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
Gets the loaded child items in this collection.
readonly items: PowerPoint.Shape[];
Property Value
Gets the number of shapes in the collection.
getCount(): OfficeExtension.ClientResult<number>;
Returns
OfficeExtension.ClientResult<number>
The number of shapes in the collection.
Remarks
[ API set: PowerPointApi 1.5 ]
Examples
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/powerpoint/shapes/get-set-shapes.yaml
// Gets the shapes you selected on the slide and displays their IDs on the task pane.
await PowerPoint.run(async (context) => {
let finalTable = "";
const shapes: PowerPoint.ShapeScopedCollection = context.presentation.getSelectedShapes();
const shapeCount = shapes.getCount();
await context.sync();
finalTable += "<br>getSelectedShapes.getCount returned:<b>" + shapeCount.value + "</b><br>";
finalTable +=
"<br><table border=1 cellpadding=3 cellspacing=0><tr><td bgcolor=#3333EE><font color=white>Index</font></td><td bgcolor=#3333EE><font color=white>Id</font></td></tr>";
shapes.load("items");
await context.sync();
shapes.items.map((shape, index) => {
finalTable += "<tr><td>" + index + "</td><td>" + shape.id + "</td></tr>";
});
finalTable += "</table>";
$("#outputSpan").empty();
$("#outputSpan").append(finalTable);
});
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
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
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
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.ShapeScopedCollectionLoadOptions & PowerPoint.Interfaces.CollectionLoadOptions): PowerPoint.ShapeScopedCollection;
Parameters
- options
-
PowerPoint.Interfaces.ShapeScopedCollectionLoadOptions & PowerPoint.Interfaces.CollectionLoadOptions
Provides options for which properties of the object to load.
Returns
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.ShapeScopedCollection;
Parameters
- propertyNames
-
string | string[]
A comma-delimited string or an array of strings that specify the properties to load.
Returns
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.ShapeScopedCollection;
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
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.ShapeScopedCollection
object is an API object, the toJSON
method returns a plain JavaScript object (typed as PowerPoint.Interfaces.ShapeScopedCollectionData
) that contains an "items" array with shallow copies of any loaded properties from the collection's items.
toJSON(): PowerPoint.Interfaces.ShapeScopedCollectionData;
Returns
Office Add-ins feedback
Office Add-ins is an open source project. Select a link to provide feedback: