在 PowerPoint 中添加和删除幻灯片

项目
04/07/2023

PowerPoint 加载项可以将幻灯片添加到演示文稿，并选择性地指定用于新幻灯片的幻灯片母版和母版布局。加载项还可以删除幻灯片。

用于添加幻灯片的 API 主要用于在编码时已知演示文稿中幻灯片母版和版式的场景，或者可以在运行时在数据源中找到。在这种情况下，你或客户必须创建和维护一个数据源，该数据源 (例如幻灯片母版和版式的名称或图像) 幻灯片母版和版式的 ID。在用户可以插入使用默认幻灯片母版和母版的默认版式的幻灯片的情况下，以及用户可以选择现有幻灯片并创建具有相同幻灯片母版和版式的新幻灯片， (但不) 相同的内容时，也可以使用 API。有关此内容的详细信息，请参阅选择要使用的幻灯片母版和版式。

使用 SlideCollection.add 添加幻灯片

使用 SlideCollection.add 方法添加幻灯片。下面是一个简单的示例，其中添加了使用演示文稿的默认幻灯片母版和该母版的第一个版式的幻灯片。方法始终将新幻灯片添加到演示文稿的末尾。示例如下。

async function addSlide() {
  await PowerPoint.run(async function(context) {
    context.presentation.slides.add();

    await context.sync();
  });
}

选择要使用的幻灯片母版和版式

使用 AddSlideOptions 参数可控制新幻灯片使用哪个幻灯片母版以及母版中的布局。示例如下。关于此代码，请注意以下几点：

可以包括对象的任一属性或两个属性 AddSlideOptions 。
如果使用这两个属性，则指定的布局必须属于指定的主控形状，否则将引发错误。
masterId如果属性不存在 (或其值为空字符串) ，则使用默认幻灯片母版，并且 layoutId 必须是该幻灯片母版的布局。
默认幻灯片母版是演示文稿中最后一张幻灯片使用的幻灯片母版。 (在演示文稿中当前没有幻灯片的异常情况下，默认幻灯片母版是演示文稿中的第一个幻灯片母版。)
layoutId如果属性不存在 (或其值为空字符串) ，则使用由 masterId 指定的主控形状的第一个布局。
这两个属性都是三种可能形式之一的字符串： nnnnnnnnnn#、 #mmmmmmm 或 nnnnnnnnnn#mmmmmmm，其中 nnnnnnnnnn 是 主控形状或布局的 ID (通常为 10 位) ， mmmmmmmmm 是主控形状或布局的创建 ID (通常为 6 - 10 位) 。一些示例包括 2147483690#2908289500、 2147483690#和 #2908289500。

async function addSlide() {
    await PowerPoint.run(async function(context) {
        context.presentation.slides.add({
            slideMasterId: "2147483690#2908289500",
            layoutId: "2147483691#2499880"
        });
    
        await context.sync();
    });
}

用户无法发现幻灯片母版或版式的 ID 或创建 ID。因此，仅当在编码时知道 ID，或者外接程序可以在运行时发现它们时，才能真正使用 AddSlideOptions 参数。由于用户无法记住 ID，因此你还需要一种方法来让用户选择幻灯片（可能按名称或图像），然后将每个标题或图像与幻灯片的 ID 相关联。

因此， AddSlideOptions 参数主要用于加载项设计为处理一组特定的幻灯片母版和布局（其 ID 已知）的方案。在这种情况下，你或客户必须创建和维护一个数据源，该数据源将选择条件 (（例如幻灯片母版和版式名称或图像) 与相应的 ID 或创建 ID）相关联。

让用户选择匹配的幻灯片

如果你的加载项可以在新幻灯片使用现有幻灯片使用的幻灯片母版和版式的相同组合的情况下使用，则外接程序可以 (1) 提示用户选择幻灯片， (2) 阅读幻灯片母版和版式的 ID。以下步骤演示如何读取 ID 并添加具有匹配母版和版式的幻灯片。

创建一个函数来获取所选幻灯片的索引。示例如下。关于此代码，请注意以下几点：
- 它使用常见 JavaScript API 的 Office.context.document.getSelectedDataAsync 方法。
- 对 getSelectedDataAsync 的调用嵌入在 Promise 返回函数中。有关执行此操作的原因和方法的详细信息，请参阅在承诺返回函数中包装通用 API。
- getSelectedDataAsync 返回数组，因为可以选择多个幻灯片。在此方案中，用户只选择了一张幻灯片，因此代码获取第一张 (第 0) 张幻灯片，这是唯一选择的幻灯片。
- 幻灯片 index 的值是用户在缩略图窗格中的幻灯片旁边看到的从 1 开始的值。
```
function getSelectedSlideIndex() {
    return new OfficeExtension.Promise<number>(function(resolve, reject) {
        Office.context.document.getSelectedDataAsync(Office.CoercionType.SlideRange, function(asyncResult) {
            try {
                if (asyncResult.status === Office.AsyncResultStatus.Failed) {
                    reject(console.error(asyncResult.error.message));
                } else {
                    resolve(asyncResult.value.slides[0].index);
                }
            } 
            catch (error) {
                reject(console.log(error));
            }
        });
    });
}
```

在添加幻灯片的主函数的 PowerPoint.run () 中调用新函数。示例如下。

async function addSlideWithMatchingLayout() {
    await PowerPoint.run(async function(context) {

        let selectedSlideIndex = await getSelectedSlideIndex();

        // Decrement the index because the value returned by getSelectedSlideIndex()
        // is 1-based, but SlideCollection.getItemAt() is 0-based.
        const realSlideIndex = selectedSlideIndex - 1;
        const selectedSlide = context.presentation.slides.getItemAt(realSlideIndex).load("slideMaster/id, layout/id");

        await context.sync();

        context.presentation.slides.add({
            slideMasterId: selectedSlide.slideMaster.id,
            layoutId: selectedSlide.layout.id
        });

        await context.sync();
    });
}

删除幻灯片

通过获取对代表幻灯片的 Slide 对象的引用并调用 Slide.delete 方法删除幻灯片。下面是删除第 4 张幻灯片的示例。

async function deleteSlide() {
    await PowerPoint.run(async function(context) {

        // The slide index is zero-based. 
        const slide = context.presentation.slides.getItemAt(3);
        slide.delete();

        await context.sync();
    });
}

在 PowerPoint 中添加和删除幻灯片

使用 SlideCollection.add 添加幻灯片

选择要使用的幻灯片母版和版式

让用户选择匹配的幻灯片

删除幻灯片

反馈

其他资源