Использование пользовательских тегов для презентаций, слайдов и фигур в PowerPoint

  • Статья

Надстройка может присоединять пользовательские метаданные в виде пар "ключ-значение", называемых "тегами", к презентациям, определенным слайдам и определенным фигурам на слайде.

Существует два основных сценария использования тегов:

  • При применении к слайду или фигуре тег позволяет классифицировать объект для пакетной обработки. Например, предположим, что презентация содержит некоторые слайды, которые должны быть включены в презентации для восточного региона, но не западного региона. Аналогичным образом, существуют альтернативные слайды, которые должны быть показаны только на Западе. Надстройка может создать тег с ключом REGION и значением East и применить его к слайдам, которые должны использоваться только на востоке. Для слайдов, которые должны отображаться только в регионе Запад, для тега задано West значение . Непосредственно перед презентацией на востоке кнопка в надстройке выполняет код, который циклически проходит по всем слайдам, проверяя значение тега REGION . Слайды, на которых находится West регион, удаляются. Затем пользователь закрывает надстройку и запускает слайд-шоу.
  • При применении к презентации тег фактически является пользовательским свойством в документе презентации (аналогично CustomProperty в Word).

Добавление тегов к слайдам и фигурам

Тег — это пара "ключ-значение", где значение всегда имеет тип string и представлено объектом Tag . Каждый тип родительского объекта, например объект Presentation, Slide или Shape , имеет tags свойство типа TagsCollection.

Добавление, обновление и удаление тегов

Чтобы добавить тег к объекту, вызовите метод TagCollection.add свойства родительского объекта tags . Следующий код добавляет два тега на первый слайд презентации. Вот что нужно знать об этом коде:

  • Первым параметром 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();
  });
}

Чтобы удалить тег, вызовите метод родительского deleteTagsCollection объекта и передайте ключ тега в качестве параметра. Пример см. в разделе Настройка пользовательских метаданных в презентации.

Использование тегов для выборочной обработки слайдов и фигур

Рассмотрим следующий сценарий: компания Contoso Consulting проводит презентацию, которая будет показана всем новым клиентам. Но некоторые слайды должны быть показаны только клиентам, которые заплатили за статус "премиум". Перед показом презентации пользователям, не относящихся к категории "Премиум", они делают ее копию и удаляют слайды, которые должны видеть только клиенты уровня "Премиум". Надстройка позволяет Компании Contoso пометить, какие слайды предназначены для клиентов ценовой категории "Премиум", и удалять эти слайды при необходимости. В следующем списке описаны основные шаги программирования для создания этой функции.

  1. Создайте функцию, которая помеет текущий выбранный слайд как предназначенную для 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();
  });
}

  2. Следующий код создает метод для получения индекса выбранного слайда. Вот что нужно знать об этом коде:

    • Он использует метод Office.context.document.getSelectedDataAsync общих API JavaScript.
    • Вызов встраивается getSelectedDataAsync в функцию, возвращающую обещание. Дополнительные сведения о том, почему и как это сделать, см. в статье Перенос общих API в функции возврата обещаний.
    • getSelectedDataAsync возвращает массив, так как можно выбрать несколько слайдов. В этом сценарии пользователь выбрал только один, поэтому код получает первый (0-й) слайд, который является единственным выбранным.
    • Значение index слайда — это значение из 1, которое пользователь видит рядом с слайдом в области эскизов пользовательского интерфейса PowerPoint.
    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));
            }
        });
    });
}

  3. В следующем коде создается функция для удаления слайдов, помеченных для клиентов ценовой категории Premium. Вот что нужно знать об этом коде:

    • 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();
  });
}

Настройка пользовательских метаданных в презентации

Надстройки также могут применять теги к презентации в целом. Это позволяет использовать теги для метаданных уровня документа, аналогично тому, как класс CustomPropertyиспользуется в Word. Но в отличие от класса 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();
  });
}