在 PowerPoint 演示文稿中插入幻灯片

项目
04/07/2023

PowerPoint 加载项可以使用 PowerPoint 特定于应用程序的 JavaScript 库将幻灯片从一个演示文稿插入当前演示文稿。您可以控制插入的幻灯片是保留源演示文稿的格式还是目标演示文稿的格式。

幻灯片插入 API 主要用于演示文稿模板方案：有少量的已知演示文稿充当可由加载项插入的幻灯片池。在这种情况下，你或客户必须创建和维护一个数据源，该数据源将选择条件 (（例如幻灯片标题或图像）) 与幻灯片 ID 相关联。在用户可以从任意演示文稿插入幻灯片的方案中，也可以使用 API，但在这种情况下，用户实际上只能插入源演示文稿 中的所有 幻灯片。有关此内容的详细信息，请参阅选择要插入的幻灯片。

将幻灯片从一个演示文稿插入到另一个演示文稿有两个步骤。

将源演示文稿文件 (.pptx) 转换为 base64 格式的字符串。
insertSlidesFromBase64使用方法将 base64 文件中的一张或多张幻灯片插入当前演示文稿。

将源演示文稿转换为 base64

可通过多种方式将文件转换为 base64。你使用哪种编程语言和库，以及是在外接程序的服务器端转换还是客户端转换取决于你的方案。最常见的是，你将使用 FileReader 对象在客户端上的 JavaScript 中执行转换。以下示例演示了这种做法。

首先获取对源 PowerPoint 文件的引用。在此示例中，我们将使用 <input> 类型的 file 控件来提示用户选择文件。将以下标记添加到外接程序页。
```
<section>
    <p>Select a PowerPoint presentation from which to insert slides</p>
    <form>
        <input type="file" id="file" />
    </form>
</section>
```
此标记将以下屏幕截图中的 UI 添加到页面。

注意

可通过许多其他方法获取 PowerPoint 文件。例如，如果文件存储在 OneDrive 或 SharePoint 上，则可以使用 Microsoft Graph 下载它。有关详细信息，请参阅在 Microsoft Graph 中使用文件和使用 Microsoft Graph 访问文件。
将以下代码添加到外接程序的 JavaScript，以将函数分配给输入控件的事件 change 。 (在下一步中创建 storeFileAsBase64 函数。)
```
$("#file").on("change", storeFileAsBase64);
```

添加以下代码。对于此代码，请注意以下事项。

方法 reader.readAsDataURL 将文件转换为 base64 并将其存储在属性中 reader.result 。方法完成后，它会触发 onload 事件处理程序。
事件处理程序 onload 剪裁编码文件的元数据，并将编码的字符串存储在全局变量中。
base64 编码的字符串全局存储，因为它将由你在后续步骤中创建的另一个函数读取。

let chosenFileBase64;

async function storeFileAsBase64() {
    const reader = new FileReader();

    reader.onload = async (event) => {
        const startIndex = reader.result.toString().indexOf("base64,");
        const copyBase64 = reader.result.toString().substr(startIndex + 7);

        chosenFileBase64 = copyBase64;
    };

    const myFile = document.getElementById("file") as HTMLInputElement;
    reader.readAsDataURL(myFile.files[0]);
}

使用 insertSlidesFromBase64 插入幻灯片

您的外接程序使用 Presentation.insertSlidesFromBase64 方法将另一个 PowerPoint 演示文稿中的幻灯片插入当前演示文稿。下面是一个简单的示例，其中源演示文稿中的所有幻灯片都插入到当前演示文稿的开头，插入的幻灯片保留源文件的格式。请注意， chosenFileBase64 这是一个全局变量，用于保存 PowerPoint 演示文稿文件的 base64 编码版本。

async function insertAllSlides() {
  await PowerPoint.run(async function(context) {
    context.presentation.insertSlidesFromBase64(chosenFileBase64);
    await context.sync();
  });
}

可以通过将 InsertSlideOptions 对象作为第二个参数 insertSlidesFromBase64传递给来控制插入结果的某些方面，包括幻灯片的插入位置以及它们是否获取源或目标格式。示例如下。关于此代码，请注意以下几点：

属性有两个可能的值 formatting ：“UseDestinationTheme”和“KeepSourceFormatting”。（可选）可以使用 InsertSlideFormatting 枚举， (例如 PowerPoint.InsertSlideFormatting.useDestinationTheme ，) 。
函数将紧接在属性指定的幻灯片之后插入源演示文稿中的 targetSlideId 幻灯片。此属性的值是三种可能形式之一的字符串：nnn#、#mmmmmmm 或nnn#mmmmmmmmm，其中 nnn 是幻灯片的 ID (通常为 3 位) ，mmmmmmmmm 是幻灯片的创建 ID (通常为 9 位数字 ) 。一些示例包括 267#763315295、 267#和 #763315295。

async function insertSlidesDestinationFormatting() {
  await PowerPoint.run(async function(context) {
    context.presentation
    .insertSlidesFromBase64(chosenFileBase64,
                            {
                                formatting: "UseDestinationTheme",
                                targetSlideId: "267#"
                            }
                          );
    await context.sync();
  });
}

当然，在编码时通常不知道目标幻灯片的 ID 或创建 ID。更常见的是，加载项会要求用户选择目标幻灯片。以下步骤演示如何获取当前所选幻灯片的 nnn# ID 并将其用作目标幻灯片。

使用通用 JavaScript API 的 Office.context.document.getSelectedDataAsync 方法创建一个函数，该函数获取当前所选幻灯片的 ID。示例如下。请注意，对 getSelectedDataAsync 的调用嵌入在 Promise 返回函数中。有关执行此操作的原因和方法的详细信息，请参阅在承诺返回函数中包装 Common-APIs。

function getSelectedSlideID() {
  return new OfficeExtension.Promise<string>(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].id);
        }
      }
      catch (error) {
        reject(console.log(error));
      }
    });
  })
}

在 main 函数的 PowerPoint.run () 中调用新函数，并传递它返回的 ID (与“#”符号) 连接作为targetSlideId参数的 InsertSlideOptions 属性值。示例如下。

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

        const selectedSlideID = await getSelectedSlideID();

        context.presentation.insertSlidesFromBase64(chosenFileBase64, {
            formatting: "UseDestinationTheme",
            targetSlideId: selectedSlideID + "#"
        });

        await context.sync();
    });
}

选择要插入的幻灯片

还可以使用 InsertSlideOptions 参数控制插入源演示文稿中的幻灯片。为此，可将源演示文稿的幻灯片 ID 数组分配给 sourceSlideIds 属性。下面是插入四张幻灯片的示例。请注意，数组中的每个字符串必须遵循用于 targetSlideId 属性的一种或另一种模式。

async function insertAfterSelectedSlide() {
    await PowerPoint.run(async function(context) {
        const selectedSlideID = await getSelectedSlideID();
        context.presentation.insertSlidesFromBase64(chosenFileBase64, {
            formatting: "UseDestinationTheme",
            targetSlideId: selectedSlideID + "#",
            sourceSlideIds: ["267#763315295", "256#", "#926310875", "1270#"]
        });

        await context.sync();
    });
}

注意

无论幻灯片在数组中的显示顺序如何，幻灯片都将按在源演示文稿中的相对顺序插入。

用户无法发现源演示文稿中幻灯片的 ID 或创建 ID。因此，仅当在编码时知道源 ID，或者外接程序可以在运行时从某些数据源检索它们时，才能真正使用 sourceSlideIds 属性。由于不能指望用户记住幻灯片 ID，因此你还需要一种方法，使用户能够按标题或图像选择幻灯片，然后将每个标题或图像与幻灯片的 ID 相关联。

因此， sourceSlideIds 属性主要用于演示文稿模板方案：外接程序设计为处理一组特定的演示文稿，这些演示文稿充当可插入的幻灯片池。在这种情况下，你或客户都必须创建和维护一个数据源，该数据源将选择条件 (（例如标题或图像) ）与幻灯片 ID 或幻灯片创建 ID 相关联，这些 ID 是从一组可能的源演示文稿构造的。

通过

在 PowerPoint 演示文稿中插入幻灯片

将源演示文稿转换为 base64

使用 insertSlidesFromBase64 插入幻灯片

选择要插入的幻灯片

其他资源