Compartir a través de

Uso de etiquetas personalizadas para presentaciones, diapositivas y formas en PowerPoint

  • Artículo

Un complemento puede adjuntar metadatos personalizados, en forma de pares clave-valor, denominados "etiquetas", a presentaciones, diapositivas específicas y formas específicas en una diapositiva.

Hay dos escenarios principales para usar etiquetas:

  • Cuando se aplica a una diapositiva o una forma, una etiqueta permite clasificar el objeto para el procesamiento por lotes. Por ejemplo, supongamos que una presentación tiene algunas diapositivas que deben incluirse en presentaciones en la región Este, pero no en la región Oeste. Del mismo modo, hay diapositivas alternativas que deben mostrarse solo a Oeste. El complemento puede crear una etiqueta con la clave REGION y el valor East y aplicarla a las diapositivas que solo se deben usar en el este. El valor de la etiqueta se establece en West para las diapositivas que solo deben mostrarse en la región Oeste. Justo antes de una presentación en el Este, un botón del complemento ejecuta código que recorre en bucle todas las diapositivas comprobando el valor de la REGION etiqueta. Diapositivas donde se West elimina la región. A continuación, el usuario cierra el complemento e inicia la presentación con diapositivas.
  • Cuando se aplica a una presentación, una etiqueta es efectivamente una propiedad personalizada en el documento de presentación (similar a customProperty en Word).

Etiquetar diapositivas y formas

Una etiqueta es un par clave-valor, donde el valor siempre es de tipo string y se representa mediante un objeto Tag . Cada tipo de objeto primario, como un objeto Presentation, Slide o Shape , tiene una tags propiedad de tipo TagsCollection.

Agregar, actualizar y eliminar etiquetas

Para agregar una etiqueta a un objeto, llame al método TagCollection.add de la propiedad del tags objeto primario. El código siguiente agrega dos etiquetas a la primera diapositiva de una presentación. Sobre este código, tenga en cuenta:

  • El primer parámetro del add método es la clave del par clave-valor.
  • El segundo parámetro es el valor.
  • La clave está en mayúsculas. Esto no es estrictamente obligatorio para el add método; sin embargo, PowerPoint siempre almacena la clave en mayúsculas y algunos métodos relacionados con etiquetas requieren que la clave se exprese en mayúsculas, por lo que se recomienda, como procedimiento recomendado, usar siempre mayúsculas en el código para una clave de etiqueta.
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();
  });
}

El add método también se usa para actualizar una etiqueta. El código siguiente cambia el valor de la PLANET etiqueta.

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 eliminar una etiqueta, llame al delete método en su objeto primario TagsCollection y pase la clave de la etiqueta como parámetro. Para obtener un ejemplo, vea Establecer metadatos personalizados en la presentación.

Uso de etiquetas para procesar de forma selectiva diapositivas y formas

Tenga en cuenta el siguiente escenario: Contoso Consulting tiene una presentación que muestran a todos los nuevos clientes. Pero algunas diapositivas solo se deben mostrar a los clientes que hayan pagado por el estado "premium". Antes de mostrar la presentación a los clientes que no son premium, hacen una copia de ella y eliminan las diapositivas que solo deben ver los clientes premium. Un complemento permite a Contoso etiquetar qué diapositivas son para clientes premium y eliminar estas diapositivas cuando sea necesario. En la lista siguiente se describen los principales pasos de codificación para crear esta funcionalidad.

  1. Cree una función que etiquete la diapositiva seleccionada actualmente como destinada a los Premium clientes. Sobre este código, tenga en cuenta:

    • La getSelectedSlideIndex función se define en el paso siguiente. Devuelve el índice basado en 1 de la diapositiva seleccionada actualmente.
    • El valor devuelto por la getSelectedSlideIndex función debe reducirse porque el método SlideCollection.getItemAt se basa en 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. El código siguiente crea un método para obtener el índice de la diapositiva seleccionada. Sobre este código, tenga en cuenta:

    • Usa el método Office.context.document.getSelectedDataAsync de las API comunes de JavaScript.
    • La llamada a getSelectedDataAsync se inserta en una función que devuelve promesas. Para obtener más información sobre por qué y cómo hacerlo, vea Encapsular las API comunes en funciones que devuelven promesas.
    • getSelectedDataAsync devuelve una matriz porque se pueden seleccionar varias diapositivas. En este escenario, el usuario ha seleccionado solo una, por lo que el código obtiene la primera (0ª) diapositiva, que es la única seleccionada.
    • El index valor de la diapositiva es el valor basado en 1 que el usuario ve junto a la diapositiva en el panel de miniaturas de la interfaz de usuario de 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. El código siguiente crea una función para eliminar diapositivas etiquetadas para clientes premium. Sobre este código, tenga en cuenta:

    • Dado que las key propiedades y value de las etiquetas se van a leer después de context.sync, se deben cargar primero.
    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();
  });
}

Establecer metadatos personalizados en la presentación

Los complementos también pueden aplicar etiquetas a la presentación en su conjunto. Esto le permite usar etiquetas para metadatos de nivel de documento similares a cómo se usa la clase CustomPropertyen Word. Pero a diferencia de la clase Word CustomProperty , el valor de una etiqueta de PowerPoint solo puede ser de tipo string.

El código siguiente es un ejemplo de cómo agregar una etiqueta a una presentación.

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

    await context.sync();
  });
}

El código siguiente es un ejemplo de eliminación de una etiqueta de una presentación. Tenga en cuenta que la clave de la etiqueta se pasa al delete método del objeto primario TagsCollection .

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

    await context.sync();
  });
}