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. |
| group | Returns the |
| 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. |
| level | Returns the level of the specified shape.
|
| line |
Returns the line formatting of this shape. |
| name | Specifies the name of this shape. |
| parent |
Returns the parent group of this shape. If the shape isn't part of a group, then this method returns the |
| placeholder |
Returns the properties that apply specifically to this placeholder. If the shape type isn't |
| 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 |
| z |
Returns the z-order position of the shape, with 0 representing the bottom of the order stack. Every shape on a slide has a unique z-order, but each slide also has a unique z-order stack, so two shapes on separate slides could have the same z-order number. |
Methods
| delete() | Deletes the shape from the shape collection. Does nothing if the shape doesn't 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 |
| get |
Returns the |
| 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 |
| set |
Moves the specified shape up or down the collection's z-order, which shifts it in front of or behind other shapes. |
| set |
Moves the specified shape up or down the collection's z-order, which shifts it in front of or behind other shapes. |
| 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
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();
});
group
Returns the ShapeGroup associated with the shape. If the shape type isn't group, then this method returns the GeneralException error.
readonly group: PowerPoint.ShapeGroup;Property Value
Remarks
[ API set: PowerPointApi 1.8 ]
Examples
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/powerpoint/shapes/group-ungroup-shapes.yaml
await PowerPoint.run(async (context) => {
// Ungroups the first shape group on the current slide.
// Get the shapes on the current slide.
context.presentation.load("slides");
const slide: PowerPoint.Slide = context.presentation.getSelectedSlides().getItemAt(0);
slide.load("shapes/items/type,shapes/items/id");
await context.sync();
const shapes: PowerPoint.ShapeCollection = slide.shapes;
const shapeGroups = shapes.items.filter((item) => item.type === PowerPoint.ShapeType.group);
if (shapeGroups.length === 0) {
console.warn("No shape groups on the current slide, so nothing to ungroup.");
return;
}
// Ungroup the first grouped shapes.
const firstGroupId = shapeGroups[0].id;
const shapeGroupToUngroup = shapes.getItem(firstGroupId);
shapeGroupToUngroup.group.ungroup();
await context.sync();
console.log(`Ungrouped shapes with group ID: ${firstGroupId}`);
});
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;
});
level
Returns the level of the specified shape.
A level of 0 means the shape isn't part of a group.
A level of 1 means the shape is part of a top-level group.
A level greater than 1 indicates the shape is a nested group.
readonly level: number;Property Value
number
Remarks
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
parentGroup
Returns the parent group of this shape. If the shape isn't part of a group, then this method returns the GeneralException error.
readonly parentGroup: PowerPoint.Shape;Property Value
Remarks
placeholderFormat
Returns the properties that apply specifically to this placeholder. If the shape type isn't placeholder, then this method returns the GeneralException error.
readonly placeholderFormat: PowerPoint.PlaceholderFormat;Property Value
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;
});
zOrderPosition
Returns the z-order position of the shape, with 0 representing the bottom of the order stack. Every shape on a slide has a unique z-order, but each slide also has a unique z-order stack, so two shapes on separate slides could have the same z-order number.
readonly zOrderPosition: number;Property Value
number
Remarks
[ API set: PowerPointApi 1.8 ]
Examples
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/powerpoint/shapes/binding-to-shapes.yaml
async function changeZOrder(operation: PowerPoint.ShapeZOrder) {
// Changes the z-order position of the selected shapes.
return PowerPoint.run(async (context) => {
const selectedShapes = context.presentation.getSelectedShapes();
selectedShapes.load();
await context.sync();
if (selectedShapes.items.length === 0) {
console.log("No shapes are selected.");
} else {
let direction = 1; // Start with bottom-most (lowest number).
// Start with top-most when sending to back or bringing forward.
switch (operation) {
case PowerPoint.ShapeZOrder.bringForward:
case PowerPoint.ShapeZOrder.sendToBack:
direction = -1; // Reverse direction.
break;
}
// Change the z-order position for each of the selected shapes,
// starting with the bottom-most when bringing to front or sending backward,
// or top-most when sending to back or bringing forward,
// so the selected shapes retain their relative z-order positions after they're changed.
selectedShapes.items
.sort((a, b) => (a.zOrderPosition - b.zOrderPosition) * direction)
.forEach((shape) => {
try {
const originalZOrderPosition = shape.zOrderPosition;
shape.setZOrder(operation);
console.log(`Changed z-order of shape ${shape.id}.`);
} catch (err) {
console.log(`Unable to change z-order of shape ${shape.id}. ${err.message}`);
}
});
await context.sync();
}
});
}
Method Details
delete()
Deletes the shape from the shape collection. Does nothing if the shape doesn't 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 doesn't 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 doesn't belong to a SlideLayout.
getParentSlideLayout(): PowerPoint.SlideLayout;Returns
Remarks
getParentSlideLayoutOrNullObject()
Returns the parent PowerPoint.SlideLayout object that holds this Shape. If this shape doesn't belong to a SlideLayout, an object with an isNullObject property set to true is returned. For further information, see *OrNullObject methods and properties.
getParentSlideLayoutOrNullObject(): PowerPoint.SlideLayout;Returns
Remarks
getParentSlideMaster()
Returns the parent PowerPoint.SlideMaster object that holds this Shape. Throws an exception if this shape doesn't belong to a SlideMaster.
getParentSlideMaster(): PowerPoint.SlideMaster;Returns
Remarks
getParentSlideMasterOrNullObject()
Returns the parent PowerPoint.SlideMaster object that holds this Shape. If this shape doesn't belong to a SlideMaster, an object with an isNullObject property set to true is returned. For further information, see *OrNullObject methods and properties.
getParentSlideMasterOrNullObject(): PowerPoint.SlideMaster;Returns
Remarks
getParentSlideOrNullObject()
Returns the parent PowerPoint.Slide object that holds this Shape. If this shape doesn't belong to a Slide, an object with an isNullObject property set to true is returned. For further information, see *OrNullObject methods and properties.
getParentSlideOrNullObject(): PowerPoint.Slide;Returns
Remarks
getTable()
Returns the Table object if this shape is a table.
getTable(): PowerPoint.Table;Returns
Remarks
[ API set: PowerPointApi 1.8 ]
Examples
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/powerpoint/shapes/add-modify-tables.yaml
// Gets the table from a shape.
await PowerPoint.run(async (context) => {
const shapes = context.presentation.getSelectedShapes();
const shapeCount = shapes.getCount();
shapes.load("items");
await context.sync();
if (shapeCount.value > 0) {
const shape = shapes.getItemAt(0);
shape.load("type");
await context.sync();
// The shape type can indicate whether the shape is a table.
const isTable = shape.type === PowerPoint.ShapeType.table;
if (isTable) {
// Get the Table object for the Shape which is a table.
const table = shape.getTable();
table.load();
await context.sync();
// Get the Table row and column count.
console.log("Table RowCount:" + table.rowCount + " and columnCount: " + table.columnCount);
} else console.log("Selected shape isn't table.");
} else console.log("No shape selected.");
});
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
setZOrder(position)
Moves the specified shape up or down the collection's z-order, which shifts it in front of or behind other shapes.
setZOrder(position: PowerPoint.ShapeZOrder): void;Parameters
- position
- PowerPoint.ShapeZOrder
Specifies how to move the shape within the z-order stack. Uses the ShapeZOrder enum.
Returns
void
Remarks
[ API set: PowerPointApi 1.8 ]
Examples
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/powerpoint/shapes/binding-to-shapes.yaml
async function changeZOrder(operation: PowerPoint.ShapeZOrder) {
// Changes the z-order position of the selected shapes.
return PowerPoint.run(async (context) => {
const selectedShapes = context.presentation.getSelectedShapes();
selectedShapes.load();
await context.sync();
if (selectedShapes.items.length === 0) {
console.log("No shapes are selected.");
} else {
let direction = 1; // Start with bottom-most (lowest number).
// Start with top-most when sending to back or bringing forward.
switch (operation) {
case PowerPoint.ShapeZOrder.bringForward:
case PowerPoint.ShapeZOrder.sendToBack:
direction = -1; // Reverse direction.
break;
}
// Change the z-order position for each of the selected shapes,
// starting with the bottom-most when bringing to front or sending backward,
// or top-most when sending to back or bringing forward,
// so the selected shapes retain their relative z-order positions after they're changed.
selectedShapes.items
.sort((a, b) => (a.zOrderPosition - b.zOrderPosition) * direction)
.forEach((shape) => {
try {
const originalZOrderPosition = shape.zOrderPosition;
shape.setZOrder(operation);
console.log(`Changed z-order of shape ${shape.id}.`);
} catch (err) {
console.log(`Unable to change z-order of shape ${shape.id}. ${err.message}`);
}
});
await context.sync();
}
});
}
setZOrder(positionString)
Moves the specified shape up or down the collection's z-order, which shifts it in front of or behind other shapes.
setZOrder(positionString: "BringForward" | "BringToFront" | "SendBackward" | "SendToBack"): void;Parameters
- positionString
-
"BringForward" | "BringToFront" | "SendBackward" | "SendToBack"
Specifies how to move the shape within the z-order stack. Uses the ShapeZOrder enum.
Returns
void
Remarks
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's 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;