PowerPoint.Shape class
Represents a single shape in the slide.
- Extends
Remarks
[ API set: PowerPointApi 1.3 ]
Examples
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/powerpoint/shapes/get-shapes-by-type.yaml
// Changes the transparency of every geometric shape in the slide.
await PowerPoint.run(async (context) => {
// Get the type of shape for every shape in the collection.
const shapes: PowerPoint.ShapeCollection = context.presentation.slides.getItemAt(0).shapes;
shapes.load("type");
await context.sync();
// Change the shape transparency to be halfway transparent.
shapes.items.forEach((shape) => {
if (shape.type === PowerPoint.ShapeType.geometricShape) {
shape.fill.transparency = 0.5;
}
});
await context.sync();
});
Properties
| context | The request context associated with the object. This connects the add-in's process to the Office host application's process. |
| custom |
Returns a collection of custom XML parts in the shape. |
| fill | Returns the fill formatting of this shape. |
| height | Specifies the height, in points, of the shape. Throws an |
| id | Gets the unique ID of the shape. |
| left | The distance, in points, from the left side of the shape to the left side of the slide. |
| line |
Returns the line formatting of this shape. |
| name | Specifies the name of this shape. |
| tags | Returns a collection of tags in the shape. |
| text |
Returns the text frame object of this shape. |
| top | The distance, in points, from the top edge of the shape to the top edge of the slide. |
| type | Returns the type of this shape. See PowerPoint.ShapeType for details. |
| width | Specifies the width, in points, of the shape. Throws an |
Methods
| delete() | Deletes the shape from the shape collection. Does nothing if the shape does not exist. |
| get |
Returns the parent PowerPoint.Slide object that holds this |
| get |
Returns the parent PowerPoint.SlideLayout object that holds this |
| get |
Returns the parent PowerPoint.SlideLayout object that holds this |
| get |
Returns the parent PowerPoint.SlideMaster object that holds this |
| get |
Returns the parent PowerPoint.SlideMaster object that holds this |
| get |
Returns the parent PowerPoint.Slide object that holds this |
| 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
customXmlParts
Note
This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.
Returns a collection of custom XML parts in the shape.
readonly customXmlParts: PowerPoint.CustomXmlPartCollection;Property Value
Remarks
fill
Returns the fill formatting of this shape.
readonly fill: PowerPoint.ShapeFill;Property Value
Remarks
[ API set: PowerPointApi 1.4 ]
Examples
// 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();
});
height
Specifies the height, in points, of the shape. Throws an InvalidArgument exception when set with a negative value.
height: number;Property Value
number
Remarks
[ API set: PowerPointApi 1.4 ]
Examples
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/powerpoint/shapes/get-set-shapes.yaml
// Arranges the selected shapes in a line from left to right.
await PowerPoint.run(async (context) => {
const shapes: PowerPoint.ShapeScopedCollection = context.presentation.getSelectedShapes();
const shapeCount = shapes.getCount();
shapes.load("items");
await context.sync();
let maxHeight = 0;
shapes.items.map((shape) => {
shape.load("width,height");
});
await context.sync();
shapes.items.map((shape) => {
shape.left = currentLeft;
shape.top = currentTop;
currentLeft += shape.width;
if (shape.height > maxHeight) maxHeight = shape.height;
});
await context.sync();
currentLeft = 0;
if (currentTop > slideHeight - 200) currentTop = 0;
});
id
Gets the unique ID of the shape.
readonly id: string;Property Value
string
Remarks
left
The distance, in points, from the left side of the shape to the left side of the slide.
left: number;Property Value
number
Remarks
[ API set: PowerPointApi 1.4 ]
Examples
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/powerpoint/shapes/get-set-shapes.yaml
// Arranges the selected shapes in a line from left to right.
await PowerPoint.run(async (context) => {
const shapes: PowerPoint.ShapeScopedCollection = context.presentation.getSelectedShapes();
const shapeCount = shapes.getCount();
shapes.load("items");
await context.sync();
let maxHeight = 0;
shapes.items.map((shape) => {
shape.load("width,height");
});
await context.sync();
shapes.items.map((shape) => {
shape.left = currentLeft;
shape.top = currentTop;
currentLeft += shape.width;
if (shape.height > maxHeight) maxHeight = shape.height;
});
await context.sync();
currentLeft = 0;
if (currentTop > slideHeight - 200) currentTop = 0;
});
lineFormat
Returns the line formatting of this shape.
readonly lineFormat: PowerPoint.ShapeLineFormat;Property Value
Remarks
name
Specifies the name of this shape.
name: string;Property Value
string
Remarks
tags
Returns a collection of tags in the shape.
readonly tags: PowerPoint.TagCollection;Property Value
Remarks
textFrame
Returns the text frame object of this shape.
readonly textFrame: PowerPoint.TextFrame;Property Value
Remarks
top
The distance, in points, from the top edge of the shape to the top edge of the slide.
top: number;Property Value
number
Remarks
[ API set: PowerPointApi 1.4 ]
Examples
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/powerpoint/shapes/get-set-shapes.yaml
// Arranges the selected shapes in a line from left to right.
await PowerPoint.run(async (context) => {
const shapes: PowerPoint.ShapeScopedCollection = context.presentation.getSelectedShapes();
const shapeCount = shapes.getCount();
shapes.load("items");
await context.sync();
let maxHeight = 0;
shapes.items.map((shape) => {
shape.load("width,height");
});
await context.sync();
shapes.items.map((shape) => {
shape.left = currentLeft;
shape.top = currentTop;
currentLeft += shape.width;
if (shape.height > maxHeight) maxHeight = shape.height;
});
await context.sync();
currentLeft = 0;
if (currentTop > slideHeight - 200) currentTop = 0;
});
type
Returns the type of this shape. See PowerPoint.ShapeType for details.
readonly type: PowerPoint.ShapeType | "Unsupported" | "Image" | "GeometricShape" | "Group" | "Line" | "Table" | "Callout" | "Chart" | "ContentApp" | "Diagram" | "Freeform" | "Graphic" | "Ink" | "Media" | "Model3D" | "Ole" | "Placeholder" | "SmartArt" | "TextBox";Property Value
PowerPoint.ShapeType | "Unsupported" | "Image" | "GeometricShape" | "Group" | "Line" | "Table" | "Callout" | "Chart" | "ContentApp" | "Diagram" | "Freeform" | "Graphic" | "Ink" | "Media" | "Model3D" | "Ole" | "Placeholder" | "SmartArt" | "TextBox"
Remarks
[ API set: PowerPointApi 1.4 ]
Examples
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/powerpoint/shapes/get-shapes-by-type.yaml
// Changes the transparency of every geometric shape in the slide.
await PowerPoint.run(async (context) => {
// Get the type of shape for every shape in the collection.
const shapes: PowerPoint.ShapeCollection = context.presentation.slides.getItemAt(0).shapes;
shapes.load("type");
await context.sync();
// Change the shape transparency to be halfway transparent.
shapes.items.forEach((shape) => {
if (shape.type === PowerPoint.ShapeType.geometricShape) {
shape.fill.transparency = 0.5;
}
});
await context.sync();
});
width
Specifies the width, in points, of the shape. Throws an InvalidArgument exception when set with a negative value.
width: number;Property Value
number
Remarks
[ API set: PowerPointApi 1.4 ]
Examples
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/powerpoint/shapes/get-set-shapes.yaml
// Arranges the selected shapes in a line from left to right.
await PowerPoint.run(async (context) => {
const shapes: PowerPoint.ShapeScopedCollection = context.presentation.getSelectedShapes();
const shapeCount = shapes.getCount();
shapes.load("items");
await context.sync();
let maxHeight = 0;
shapes.items.map((shape) => {
shape.load("width,height");
});
await context.sync();
shapes.items.map((shape) => {
shape.left = currentLeft;
shape.top = currentTop;
currentLeft += shape.width;
if (shape.height > maxHeight) maxHeight = shape.height;
});
await context.sync();
currentLeft = 0;
if (currentTop > slideHeight - 200) currentTop = 0;
});
Method Details
delete()
Deletes the shape from the shape collection. Does nothing if the shape does not exist.
delete(): void;Returns
void
Remarks
[ API set: PowerPointApi 1.3 ]
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 then iterates through them, deleting each one.
await PowerPoint.run(async (context) => {
const slide: PowerPoint.Slide = context.presentation.slides.getItemAt(0);
const shapes: PowerPoint.ShapeCollection = slide.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();
});
getParentSlide()
Returns the parent PowerPoint.Slide object that holds this Shape. Throws an exception if this shape does not belong to a Slide.
getParentSlide(): PowerPoint.Slide;Returns
Remarks
getParentSlideLayout()
Returns the parent PowerPoint.SlideLayout object that holds this Shape. Throws an exception if this shape does not belong to a SlideLayout.
getParentSlideLayout(): PowerPoint.SlideLayout;Returns
Remarks
getParentSlideLayoutOrNullObject()
Returns the parent PowerPoint.SlideLayout object that holds this Shape. If this shape does not belong to a SlideLayout, an object with an isNullObject property set to true is returned.
getParentSlideLayoutOrNullObject(): PowerPoint.SlideLayout;Returns
Remarks
getParentSlideMaster()
Returns the parent PowerPoint.SlideMaster object that holds this Shape. Throws an exception if this shape does not belong to a SlideMaster.
getParentSlideMaster(): PowerPoint.SlideMaster;Returns
Remarks
getParentSlideMasterOrNullObject()
Returns the parent PowerPoint.SlideMaster object that holds this Shape. If this shape does not belong to a SlideMaster, an object with an isNullObject property set to true is returned.
getParentSlideMasterOrNullObject(): PowerPoint.SlideMaster;Returns
Remarks
getParentSlideOrNullObject()
Returns the parent PowerPoint.Slide object that holds this Shape. If this shape does not belong to a Slide, an object with an isNullObject property set to true is returned.
getParentSlideOrNullObject(): PowerPoint.Slide;Returns
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.ShapeLoadOptions): PowerPoint.Shape;Parameters
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.Shape;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?: {
select?: string;
expand?: string;
}): PowerPoint.Shape;Parameters
- propertyNamesAndPaths
-
{ select?: string; expand?: string; }
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.Shape object is an API object, the toJSON method returns a plain JavaScript object (typed as PowerPoint.Interfaces.ShapeData) that contains shallow copies of any loaded child properties from the original object.
toJSON(): PowerPoint.Interfaces.ShapeData;Returns
Office Add-ins