在 PowerPoint 中对演示文稿、幻灯片和形状使用自定义标记

项目
04/07/2023

加载项可以将自定义元数据以键值对的形式（称为“标记”）附加到演示文稿、特定幻灯片和幻灯片上的特定形状。

使用标记有两种主要方案：

应用于幻灯片或形状时，标记允许对对象进行分类以便进行批处理。例如，假设演示文稿包含一些幻灯片，这些幻灯片应包含在东部区域而不是西部区域的演示文稿中。同样，还有一些替代幻灯片应仅向西方显示。加载项可以使用键 REGION 和值 East 创建标记，并将其应用于只能在东部使用的幻灯片。对于只应显示到西部区域的幻灯片，标记的值设置为 West 。在向“东部”演示之前，加载项中的一个按钮运行循环访问所有幻灯片的代码，检查标记的值 REGION 。将删除该区域的 West 幻灯片。然后，用户关闭加载项并启动幻灯片放映。
应用于演示文稿时，标记实际上是演示文稿文档中的自定义属性， (类似于 Word) 中的 CustomProperty 。

标记幻灯片和形状

标记是键值对，值始终为类型 string ，由 Tag 对象表示。每种类型的父对象（如 Presentation、 Slide 或 Shape 对象）都有一个 tagsTagsCollection 类型的属性。

添加、更新和删除标记

若要向对象添加标记，请调用父对象的属性的 tagsTagCollection.add 方法。以下代码向演示文稿的第一张幻灯片添加两个标记。关于此代码，请注意以下几点：

方法的第一个参数 add 是键值对中的键。
第二个参数是值。
键以大写字母显示。此方法并非严格要求 add 这样做;但是，PowerPoint 始终将密钥存储为大写，并且 某些与标记相关的方法确实要求以大写形式表示密钥，因此我们建议最好始终在代码中使用大写形式来表示标记键。

async function addMultipleSlideTags() {
  await PowerPoint.run(async function(context) {
    const slide = context.presentation.slides.getItemAt(0);
    slide.tags.add("OCEAN", "Arctic");
    slide.tags.add("PLANET", "Jupiter");

    await context.sync();
  });
}

方法 add 还用于更新标记。以下代码更改标记的值 PLANET 。

async function updateTag() {
  await PowerPoint.run(async function(context) {
    const slide = context.presentation.slides.getItemAt(0);
    slide.tags.add("PLANET", "Mars");

    await context.sync();
  });
}

若要删除标记，请 delete 对它的父 TagsCollection 对象调用方法，并将标记的键作为参数传递。有关示例，请参阅设置演示文稿上的自定义元数据。

使用标记选择性地处理幻灯片和形状

请考虑以下方案：Contoso Consulting 向所有新客户展示了一个演示文稿。但某些幻灯片应仅向已支付“高级”状态费用的客户显示。在向非高级客户显示演示文稿之前，他们会创建演示文稿的副本，并删除只有高级客户才能看到的幻灯片。加载项使 Contoso 能够标记哪些幻灯片适用于高级客户，并在需要时删除这些幻灯片。以下列表概述了创建此功能的主要编码步骤。

创建一个函数，该函数按客户预期 Premium 标记当前所选幻灯片。关于此代码，请注意以下几点：

下 getSelectedSlideIndex 一步将定义函数。它返回当前所选幻灯片的从 1 开始的索引。
函数返回 getSelectedSlideIndex 的值必须递减，因为 SlideCollection.getItemAt 方法从 0 开始。

async function addTagToSelectedSlide() {
  await PowerPoint.run(async function(context) {
    let selectedSlideIndex = await getSelectedSlideIndex();
    selectedSlideIndex = selectedSlideIndex - 1;
    const slide = context.presentation.slides.getItemAt(selectedSlideIndex);
    slide.tags.add("CUSTOMER_TYPE", "Premium");

    await context.sync();
  });
}

以下代码创建一个方法来获取所选幻灯片的索引。关于此代码，请注意以下几点：
- 它使用常见 JavaScript API 的 Office.context.document.getSelectedDataAsync 方法。
- 对 getSelectedDataAsync 的调用嵌入到 promise-returning 函数中。有关执行此操作的原因和方法的详细信息，请参阅在承诺返回函数中包装通用 API。
- getSelectedDataAsync 返回数组，因为可以选择多个幻灯片。在此方案中，用户只选择了一张幻灯片，因此代码获取第一张 (第 0) 张幻灯片，这是唯一选择的幻灯片。
- 幻灯片 index 的值是用户在 PowerPoint UI 缩略图窗格中的幻灯片旁边看到的从 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));
            }
        });
    });
}
```

以下代码创建一个函数，用于删除为高级客户标记的幻灯片。关于此代码，请注意以下几点：

key由于标记的和 value 属性将在之后context.sync读取，因此必须首先加载它们。

async function deleteSlidesByAudience() {
  await PowerPoint.run(async function(context) {
    const slides = context.presentation.slides;
    slides.load("tags/key, tags/value");

    await context.sync();

    for (let i = 0; i < slides.items.length; i++) {
      let currentSlide = slides.items[i];
      for (let j = 0; j < currentSlide.tags.items.length; j++) {
        let currentTag = currentSlide.tags.items[j];
        if (currentTag.key === "CUSTOMER_TYPE" && currentTag.value === "Premium") {
          currentSlide.delete();
        }
      }
    }

    await context.sync();
  });
}

在演示文稿上设置自定义元数据

加载项还可以将标记作为一个整体应用于演示文稿。这使你能够将标记用于文档级元数据，类似于在 Word 中使用 CustomProperty类的方式。但与 Word CustomProperty 类不同，PowerPoint 标记的值只能为类型 string。

以下代码是向演示文稿添加标记的示例。

async function addPresentationTag() {
  await PowerPoint.run(async function (context) {
    let presentationTags = context.presentation.tags;
    presentationTags.add("SECURITY", "Internal-Audience-Only");

    await context.sync();
  });
}

以下代码是从演示文稿中删除标记的示例。请注意，标记的键将传递给 delete 父 TagsCollection 对象的方法。

async function deletePresentationTag() {
  await PowerPoint.run(async function (context) {
    let presentationTags = context.presentation.tags;
    presentationTags.delete("SECURITY");

    await context.sync();
  });
}

通过

在 PowerPoint 中对演示文稿、幻灯片和形状使用自定义标记

标记幻灯片和形状

添加、更新和删除标记

使用标记选择性地处理幻灯片和形状

在演示文稿上设置自定义元数据

其他资源