Skip to content

Commit 21ae391

Browse files
ElizabethSamuel-MSFTAlexJerabek
ElizabethSamuel-MSFT
and
AlexJerabek
authored
[PowerPoint] (Overview) Refresh (#5209)
* [PowerPoint] (Overview) Refresh * Apply suggestions from code review Co-authored-by: Alex Jerabek <[email protected]> --------- Co-authored-by: Alex Jerabek <[email protected]>
1 parent d87e32e commit 21ae391

File tree

1 file changed

+81
-109
lines changed

1 file changed

+81
-109
lines changed

‎docs/powerpoint/powerpoint-add-ins.md

Lines changed: 81 additions & 109 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
title: PowerPoint add-ins
33
description: Learn how to use PowerPoint add-ins to build engaging solutions for presentations across platforms including Windows, iPad, Mac, and in a browser.
4-
ms.date: 10/16/2024
4+
ms.date: 06/05/2025
55
ms.topic: overview
66
ms.custom: scenarios:getting-started
77
ms.localizationpriority: high
@@ -11,128 +11,98 @@ ms.localizationpriority: high
1111

1212
You can use PowerPoint add-ins to build engaging solutions for your users' presentations across platforms including Windows, iPad, Mac, and in a browser. You can create two types of PowerPoint add-ins:
1313

14-
- Use **content add-ins** to add dynamic HTML5 content to your presentations. For example, see the [LucidChart Diagrams for PowerPoint](https://appsource.microsoft.com/product/office/wa104380117) add-in, which you can use to inject an interactive diagram from LucidChart into your deck. To create your own content add-in, you can start with [Build your first PowerPoint content add-in](../quickstarts/powerpoint-quickstart-content.md).
15-
1614
- Use **task pane add-ins** to bring in reference information or insert data into the presentation via a service. For example, see the [Pexels - Free Stock Photos](https://appsource.microsoft.com/product/office/wa104379997) add-in, which you can use to add professional photos to your presentation. To create your own task pane add-in, you can start with [Build your first PowerPoint task pane add-in](../quickstarts/powerpoint-quickstart-yo.md).
1715

18-
## PowerPoint add-in scenarios
19-
20-
The code examples in this article demonstrate some basic tasks for developing add-ins for PowerPoint. Please note the following:
21-
22-
- To display information, these examples use the `app.showNotification` function, which is included in the Visual Studio Office Add-ins project templates. If you aren't using Visual Studio to develop your add-in, you'll need replace the `showNotification` function with your own code.
23-
24-
- Several of these examples also use a `Globals` object that's declared beyond the scope of these functions as:
25-
26-
`let Globals = {activeViewHandler:0, firstSlideId:0};`
27-
28-
- To use these examples, your add-in project must [reference Office.js v1.1 library or later](../develop/referencing-the-javascript-api-for-office-library-from-its-cdn.md).
29-
30-
## Detect the presentation's active view and handle the ActiveViewChanged event
16+
- Use **content add-ins** to add dynamic HTML5 content to your presentations. For example, see the [LucidChart Diagrams for PowerPoint](https://appsource.microsoft.com/product/office/wa104380117) add-in, which injects interactive diagrams from LucidChart into your deck. To create your own content add-in, start with [Build your first PowerPoint content add-in](../quickstarts/powerpoint-quickstart-content.md).
3117

32-
If you're building a content add-in, you'll need to get the presentation's active view and handle the `ActiveViewChanged` event, as part of your `Office.onReady` handler.
33-
34-
> [!NOTE]
35-
> In PowerPoint on the web, the [Document.ActiveViewChanged](/javascript/api/office/office.document) event will never fire as Slide Show mode is treated as a new session. In this case, the add-in must fetch the active view on load, as shown in the following code sample.
18+
## PowerPoint add-in scenarios
3619

37-
Note the following about the code sample:
20+
The code examples in this article demonstrate some basic tasks that can be useful when developing add-ins for PowerPoint.
3821

39-
- The `getActiveFileView` function calls the [Document.getActiveViewAsync](/javascript/api/office/office.document#office-office-document-getactiveviewasync-member(1)) method to return whether the presentation's current view is "edit" (any of the views in which you can edit slides, such as **Normal** or **Outline View**) or "read" (**Slide Show** or **Reading View**).
22+
## Add a new slide then navigate to it
4023

41-
- The `registerActiveViewChanged` function calls the [addHandlerAsync](/javascript/api/office/office.document#office-office-document-addhandlerasync-member(1)) method to register a handler for the [Document.ActiveViewChanged](/javascript/api/office/office.document) event.
24+
In the following code sample, the `addAndNavigateToNewSlide` function calls the [SlideCollection.add](/javascript/api/powerpoint/powerpoint.slidecollection#powerpoint-powerpoint-slidecollection-add-member(1)) method to add a new slide to the presentation. The function then calls the [Presentation.setSelectedSlides](/javascript/api/powerpoint/powerpoint.presentation#powerpoint-powerpoint-presentation-setselectedslides-member(1)) method to navigate to the new slide.
4225

4326
```js
44-
// General Office.onReady function. Called after the add-in loads and Office JS is initialized.
45-
Office.onReady(function() {
46-
// Get whether the current view is edit or read.
47-
const currentView = getActiveFileView();
48-
49-
// Register for the active view changed handler.
50-
registerActiveViewChanged();
51-
52-
// Render the content based off of the currentView.
53-
//....
54-
});
55-
56-
function getActiveFileView()
57-
{
58-
Office.context.document.getActiveViewAsync(function (asyncResult) {
59-
if (asyncResult.status === Office.AsyncResultStatus.Failed) {
60-
app.showNotification("Action failed with error: " + asyncResult.error.message);
61-
} else {
62-
app.showNotification(asyncResult.value);
63-
}
64-
});
65-
66-
}
67-
68-
function registerActiveViewChanged() {
69-
Globals.activeViewHandler = function (args) {
70-
app.showNotification(JSON.stringify(args));
71-
}
72-
73-
Office.context.document.addHandlerAsync(Office.EventType.ActiveViewChanged, Globals.activeViewHandler,
74-
function (asyncResult) {
75-
if (asyncResult.status === Office.AsyncResultStatus.Failed) {
76-
app.showNotification("Action failed with error: " + asyncResult.error.message);
77-
} else {
78-
app.showNotification(asyncResult.status);
79-
}
80-
});
27+
async function addAndNavigateToNewSlide() {
28+
// Adds a new slide then navigates to it.
29+
await PowerPoint.run(async (context) => {
30+
const slideCountResult = context.presentation.slides.getCount();
31+
context.presentation.slides.add();
32+
await context.sync();
33+
34+
const newSlide = context.presentation.slides.getItemAt(slideCountResult.value);
35+
newSlide.load("id");
36+
await context.sync();
37+
38+
console.log(`Added slide - ID: ${newSlide.id}`);
39+
40+
// Navigate to the new slide.
41+
context.presentation.setSelectedSlides([newSlide.id]);
42+
await context.sync();
43+
});
8144
}
8245
```
8346

8447
## Navigate to a particular slide in the presentation
8548

86-
In the following code sample, the `getSelectedRange` function calls the [Document.getSelectedDataAsync](/javascript/api/office/office.document#office-office-document-getselecteddataasync-member(1)) method to get the JSON object returned by `asyncResult.value`, which contains an array named `slides`. The `slides` array contains the IDs, titles, and indexes of selected range of slides (or of the current slide, if multiple slides aren't selected). It also saves the ID of the first slide in the selected range to a global variable.
49+
In the following code sample, the `getSelectedSlides` function calls the [Presentation.getSelectedSlides](/javascript/api/powerpoint/powerpoint.presentation#powerpoint-powerpoint-presentation-getselectedslides-member(1)) method to get the selected slides then logs their IDs. The function can then act on the current slide (or first slide from the selection).
8750

8851
```js
89-
function getSelectedRange() {
90-
// Gets the ID, title, and index of the current slide (or selected slides) and store the first slide ID. */
91-
Globals.firstSlideId = 0;
92-
93-
Office.context.document.getSelectedDataAsync(Office.CoercionType.SlideRange, function (asyncResult) {
94-
if (asyncResult.status === Office.AsyncResultStatus.Failed) {
95-
app.showNotification("Action failed with error: " + asyncResult.error.message);
96-
} else {
97-
Globals.firstSlideId = asyncResult.value.slides[0].id;
98-
app.showNotification(JSON.stringify(asyncResult.value));
99-
}
52+
async function getSelectedSlides() {
53+
// Gets the ID of the current slide (or selected slides).
54+
await PowerPoint.run(async (context) => {
55+
const selectedSlides = context.presentation.getSelectedSlides();
56+
selectedSlides.load("items/id");
57+
await context.sync();
58+
59+
if (selectedSlides.items.length === 0) {
60+
console.warn("No slides were selected.");
61+
return;
62+
}
63+
64+
console.log("IDs of selected slides:");
65+
selectedSlides.items.forEach(item => {
66+
console.log(item.id);
10067
});
101-
}
102-
```
10368

104-
In the following code sample, the `goToFirstSlide` function calls the [Document.goToByIdAsync](/javascript/api/office/office.document#office-office-document-gotobyidasync-member(1)) method to navigate to the first slide that was identified by the `getSelectedRange` function shown previously.
69+
// Navigate to first selected slide.
70+
const currentSlide = selectedSlides.items[0];
71+
console.log(`Navigating to slide with ID ${currentSlide.id} ...`);
72+
context.presentation.setSelectedSlides([currentSlide.id]);
10573

106-
```js
107-
function goToFirstSlide() {
108-
Office.context.document.goToByIdAsync(Globals.firstSlideId, Office.GoToType.Slide, function (asyncResult) {
109-
if (asyncResult.status === Office.AsyncResultStatus.Failed) {
110-
app.showNotification("Action failed with error: " + asyncResult.error.message);
111-
} else {
112-
app.showNotification("Navigation successful");
113-
}
114-
});
74+
// Perform actions on current slide...
75+
});
11576
}
11677
```
11778

11879
## Navigate between slides in the presentation
11980

120-
In the following code sample, the `goToSlideByIndex` function calls the `Document.goToByIdAsync` method to navigate to the next slide in the presentation.
81+
In the following code sample, the `goToSlideByIndex` function calls the `Presentation.setSelectedSlides` method to navigate to the first slide in the presentation, which has the index 0. The maximum slide index you can navigate to in this sample is `slideCountResult.value - 1`.
12182

12283
```js
123-
function goToSlideByIndex() {
124-
const goToFirst = Office.Index.First;
125-
const goToLast = Office.Index.Last;
126-
const goToPrevious = Office.Index.Previous;
127-
const goToNext = Office.Index.Next;
128-
129-
Office.context.document.goToByIdAsync(goToNext, Office.GoToType.Index, function (asyncResult) {
130-
if (asyncResult.status === Office.AsyncResultStatus.Failed) {
131-
app.showNotification("Action failed with error: " + asyncResult.error.message);
132-
} else {
133-
app.showNotification("Navigation successful");
134-
}
135-
});
84+
async function goToSlideByIndex() {
85+
await PowerPoint.run(async (context) => {
86+
// Gets the number of slides in the presentation.
87+
const slideCountResult = context.presentation.slides.getCount();
88+
await context.sync();
89+
90+
if (slideCountResult.value === 0) {
91+
console.warn("There are no slides.");
92+
return;
93+
}
94+
95+
const slide = context.presentation.slides.getItemAt(0); // First slide
96+
//const slide = context.presentation.slides.getItemAt(slideCountResult.value - 1); // Last slide
97+
slide.load("id");
98+
await context.sync();
99+
100+
console.log(`Slide ID: ${slide.id}`);
101+
102+
// Navigate to the slide.
103+
context.presentation.setSelectedSlides([slide.id]);
104+
await context.sync();
105+
});
136106
}
137107
```
138108

@@ -142,15 +112,15 @@ In the following code sample, the `getFileUrl` function calls the [Document.get
142112

143113
```js
144114
function getFileUrl() {
145-
// Gets the URL of the current file.
146-
Office.context.document.getFilePropertiesAsync(function (asyncResult) {
147-
const fileUrl = asyncResult.value.url;
148-
if (fileUrl === "") {
149-
app.showNotification("The file hasn't been saved yet. Save the file and try again.");
150-
} else {
151-
app.showNotification(fileUrl);
152-
}
153-
});
115+
// Gets the URL of the current file.
116+
Office.context.document.getFilePropertiesAsync(function (asyncResult) {
117+
const fileUrl = asyncResult.value.url;
118+
if (fileUrl === "") {
119+
console.warn("The file hasn't been saved yet. Save the file and try again.");
120+
} else {
121+
console.log(`File URL: ${fileUrl}`);
122+
}
123+
});
154124
}
155125
```
156126

@@ -165,7 +135,7 @@ PowerPoint.createPresentation();
165135
The `createPresentation` method can also create a copy of an existing presentation. The method accepts a Base64-encoded string representation of an .pptx file as an optional parameter. The resulting presentation will be a copy of that file, assuming the string argument is a valid .pptx file. The [FileReader](https://developer.mozilla.org/docs/Web/API/FileReader) class can be used to convert a file into the required Base64-encoded string, as demonstrated in the following example.
166136

167137
```js
168-
const myFile = document.getElementById("file");
138+
const myFile = document.getElementById("file") as HTMLInputElement;
169139
const reader = new FileReader();
170140

171141
reader.onload = function (event) {
@@ -180,6 +150,8 @@ reader.onload = function (event) {
180150
reader.readAsDataURL(myFile.files[0]);
181151
```
182152

153+
To see a full code sample that includes an HTML implementation, see [Create presentation](https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/powerpoint/document/create-presentation.yaml).
154+
183155
## See also
184156

185157
- [Developing Office Add-ins](../develop/develop-overview.md)
@@ -190,5 +162,5 @@ reader.readAsDataURL(myFile.files[0]);
190162
- [PowerPoint Code Samples](https://developer.microsoft.com/microsoft-365/gallery/?filterBy=Samples,PowerPoint)
191163
- [How to save add-in state and settings per document for content and task pane add-ins](../develop/persisting-add-in-state-and-settings.md#how-to-save-add-in-state-and-settings-per-document-for-content-and-task-pane-add-ins)
192164
- [Read and write data to the active selection in a document or spreadsheet](../develop/read-and-write-data-to-the-active-selection-in-a-document-or-spreadsheet.md)
193-
- [Get the whole document from an add-in for PowerPoint or Word](../powerpoint/get-the-whole-document-from-an-add-in-for-powerpoint.md)
165+
- [Get the whole document from an add-in for PowerPoint or Word](../develop/get-the-whole-document-from-an-add-in-for-powerpoint-or-word.md)
194166
- [Use document themes in your PowerPoint add-ins](use-document-themes-in-your-powerpoint-add-ins.md)

0 commit comments

Comments
 (0)