Usar marcas personalizadas para apresentações, slides e formas no PowerPoint

  • Artigo

Um suplemento pode anexar metadados personalizados, na forma de pares de valor-chave, chamados de "marcas", a apresentações, slides específicos e formas específicas em um slide.

Há dois cenários principais para o uso de marcas:

  • Quando aplicado a um slide ou uma forma, uma marca permite que o objeto seja categorizado para processamento em lote. Por exemplo, suponha que uma apresentação tenha alguns slides que devem ser incluídos em apresentações para a região Leste, mas não para a região Oeste. Da mesma forma, há slides alternativos que devem ser mostrados apenas para o Ocidente. Seu suplemento pode criar uma marca com a chave REGION e o valor East e aplicá-la aos slides que só devem ser usados no Leste. O valor da marca é definido como para West os slides que só devem ser mostrados para a região Oeste. Pouco antes de uma apresentação para o Leste, um botão no suplemento executa o código que percorre todos os slides verificando o valor da REGION marca. Slides em que a região é West excluída. Em seguida, o usuário fecha o suplemento e inicia a apresentação de slides.
  • Quando aplicada a uma apresentação, uma marca é efetivamente uma propriedade personalizada no documento de apresentação (semelhante a uma CustomProperty no Word).

Marcar slides e formas

Uma marca é um par de valor-chave, em que o valor é sempre do tipo string e é representado por um objeto Tag . Cada tipo de objeto pai, como um objeto Presentation, Slide ou Shape , tem uma tags propriedade do tipo TagsCollection.

Adicionar, atualizar e excluir marcas

Para adicionar uma marca a um objeto, chame o método TagCollection.add da propriedade do tags objeto pai. O código a seguir adiciona duas marcas ao primeiro slide de uma apresentação. Sobre este código, observe:

  • O primeiro parâmetro do add método é a chave no par key-value.
  • O segundo parâmetro é o valor.
  • A chave está em letras maiúsculas. Isso não é estritamente obrigatório para o add método; no entanto, a chave é sempre armazenada pelo PowerPoint como maiúsculas e alguns métodos relacionados à marca exigem que a chave seja expressa em maiúsculas e minúsculas, portanto, recomendamos como prática recomendada que você sempre use maiúsculas no código para uma chave de marca.
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();
  });
}

O add método também é usado para atualizar uma marca. O código a seguir altera o valor da PLANET marca.

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

    await context.sync();
  });
}

Para excluir uma marca, chame o delete método em seu objeto pai TagsCollection e passe a chave da marca como o parâmetro. Para obter um exemplo, consulte Definir metadados personalizados na apresentação.

Usar marcas para processar seletivamente slides e formas

Considere o seguinte cenário: a Contoso Consulting tem uma apresentação que eles mostram para todos os novos clientes. Mas alguns slides só devem ser mostrados aos clientes que pagaram pelo status "premium". Antes de mostrar a apresentação para clientes não premium, eles fazem uma cópia dela e excluem os slides que somente os clientes premium devem ver. Um suplemento permite à Contoso marcar quais slides são para clientes premium e excluir esses slides quando necessário. A lista a seguir descreve as principais etapas de codificação para criar essa funcionalidade.

  1. Crie uma função que marque o slide selecionado atualmente como destinado aos Premium clientes. Sobre este código, observe:

    • A getSelectedSlideIndex função é definida na próxima etapa. Ele retorna o índice baseado em 1 do slide selecionado no momento.
    • O valor retornado pela getSelectedSlideIndex função precisa ser decremented porque o método SlideCollection.getItemAt é baseado em 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. O código a seguir cria um método para obter o índice do slide selecionado. Sobre este código, observe:

    • Ele usa o método Office.context.document.getSelectedDataAsync das APIs JavaScript Comuns.
    • A chamada a ser getSelectedDataAsync inserida em uma função de retorno de promessa. Para obter mais informações sobre por que e como fazer isso, consulte Encapsular APIs comuns em funções de retorno de promessas.
    • getSelectedDataAsync retorna uma matriz porque vários slides podem ser selecionados. Nesse cenário, o usuário selecionou apenas um, portanto, o código obtém o primeiro slide (0º), que é o único selecionado.
    • O index valor do slide é o valor baseado em 1 que o usuário vê ao lado do slide no painel miniaturas da interface do usuário do 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. O código a seguir cria uma função para excluir slides marcados para clientes premium. Sobre este código, observe:

    • Como as key propriedades e value das marcas serão lidas após o context.sync, elas devem ser carregadas primeiro.
    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();
  });
}

Definir metadados personalizados na apresentação

Os suplementos também podem aplicar marcas à apresentação como um todo. Isso permite que você use marcas para metadados no nível do documento semelhantes à forma como a classe CustomPropertyé usada no Word. Mas, ao contrário da classe Word CustomProperty , o valor de uma marca do PowerPoint só pode ser do tipo string.

O código a seguir é um exemplo de adição de uma marca a uma apresentação.

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

    await context.sync();
  });
}

O código a seguir é um exemplo de exclusão de uma marca de uma apresentação. Observe que a chave da marca é passada para o delete método do objeto pai TagsCollection .

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

    await context.sync();
  });
}