Freigeben über

Verwenden von benutzerdefinierten Tags für Präsentationen, Folien und Formen in PowerPoint

  • Artikel

Ein Add-In kann benutzerdefinierte Metadaten in Form von Schlüssel-Wert-Paaren, sogenannten "Tags", an Präsentationen, bestimmte Folien und bestimmte Formen auf einer Folie anfügen.

Es gibt zwei Hauptszenarien für die Verwendung von Tags:

  • Wenn ein Tag auf eine Folie oder eine Form angewendet wird, kann das Objekt für die Batchverarbeitung kategorisiert werden. Angenommen, eine Präsentation enthält einige Folien, die in Präsentationen in der Region "Osten", aber nicht in der Region "Westen" enthalten sein sollten. Ebenso gibt es alternative Folien, die nur im Westen angezeigt werden sollten. Ihr Add-In kann ein Tag mit dem Schlüssel REGION und dem Wert East erstellen und es auf die Folien anwenden, die nur im Osten verwendet werden sollen. Der Tagwert wird für die Folien, die nur in der Region "Westen" angezeigt werden sollen, auf West festgelegt. Kurz vor einer Präsentation im Osten führt eine Schaltfläche im Add-In Code aus, der alle Folien durchläuft, die den Wert des REGION Tags überprüfen. Folien, auf denen sich der Bereich befindet West , werden gelöscht. Der Benutzer schließt dann das Add-In und startet die Bildschirmpräsentation.
  • Wenn ein Tag auf eine Präsentation angewendet wird, ist es praktisch eine benutzerdefinierte Eigenschaft im Präsentationsdokument (ähnlich einer CustomProperty in Word).

Markieren von Folien und Formen

Ein Tag ist ein Schlüssel-Wert-Paar, bei dem der Wert immer vom Typ string ist und durch ein Tag-Objekt dargestellt wird. Jeder Typ von übergeordneten Objekten, z. B. ein Presentation-, Slide- oder Shape-Objekt , verfügt über eine tags Eigenschaft vom Typ TagsCollection.

Hinzufügen, Aktualisieren und Löschen von Tags

Um einem -Objekt ein Tag hinzuzufügen, rufen Sie die TagCollection.add-Methode der -Eigenschaft des übergeordneten tags Objekts auf. Der folgende Code fügt der ersten Folie einer Präsentation zwei Tags hinzu. Bei diesem Code ist Folgendes zu beachten:

  • Der erste Parameter der add -Methode ist der Schlüssel im Schlüssel-Wert-Paar.
  • Der zweite Parameter ist der Wert.
  • Der Schlüssel wird in Großbuchstaben geschrieben. Dies ist für die add -Methode nicht unbedingt obligatorisch. Der Schlüssel wird jedoch immer in PowerPoint als Großbuchstaben gespeichert, und einige tagbezogene Methoden erfordern, dass der Schlüssel in Großbuchstaben ausgedrückt wird. Daher empfehlen wir als bewährte Methode, dass Sie in Ihrem Code für einen Tagschlüssel immer Großbuchstaben verwenden.
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();
  });
}

Die add -Methode wird auch verwendet, um ein Tag zu aktualisieren. Der folgende Code ändert den Wert des PLANET Tags.

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

    await context.sync();
  });
}

Um ein Tag zu löschen, rufen Sie die delete -Methode für das übergeordnete TagsCollection Objekt auf, und übergeben Sie den Schlüssel des Tags als Parameter. Ein Beispiel finden Sie unter Festlegen von benutzerdefinierten Metadaten für die Präsentation.

Verwenden von Tags zum selektiven Verarbeiten von Folien und Formen

Betrachten Sie das folgende Szenario: Contoso Consulting verfügt über eine Präsentation, die sie allen neuen Kunden zeigt. Einige Folien sollten jedoch nur Kunden angezeigt werden, die für den Status "Premium" bezahlt haben. Vor dem Anzeigen der Präsentation für Nicht-Premium-Kunden erstellen sie eine Kopie davon und löschen die Folien, die nur Premium-Kunden sehen sollten. Mit einem Add-In kann Contoso markieren, welche Folien für Premium-Kunden bestimmt sind, und diese Folien bei Bedarf löschen. In der folgenden Liste werden die wichtigsten Codierungsschritte zum Erstellen dieser Funktionalität beschrieben.

  1. Erstellen Sie eine Funktion, die die aktuell ausgewählte Folie als für Premium Kunden vorgesehen markiert. Bei diesem Code ist Folgendes zu beachten:

    • Die getSelectedSlideIndex Funktion wird im nächsten Schritt definiert. Er gibt den 1-basierten Index der aktuell ausgewählten Folie zurück.
    • Der von der getSelectedSlideIndex Funktion zurückgegebene Wert muss verringert werden, da die SlideCollection.getItemAt-Methode 0-basiert ist.
    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. Der folgende Code erstellt eine Methode, um den Index der ausgewählten Folie abzurufen. Bei diesem Code ist Folgendes zu beachten:

    • Sie verwendet die Office.context.document.getSelectedDataAsync-Methode der allgemeinen JavaScript-APIs.
    • Der Aufruf von getSelectedDataAsync ist in eine Zusagerückgabefunktion eingebettet. Weitere Informationen dazu, warum und wie Dies geschieht, finden Sie unter Umschließen allgemeiner APIs in Funktionen zur Rückgabe von Zusagen.
    • getSelectedDataAsync gibt ein Array zurück, da mehrere Folien ausgewählt werden können. In diesem Szenario hat der Benutzer nur eine ausgewählt, sodass der Code die erste (0.) Folie erhält, die als einzige ausgewählt ist.
    • Der index Wert der Folie ist der 1-basierte Wert, den der Benutzer neben der Folie im Miniaturansichtenbereich der PowerPoint-Benutzeroberfläche sieht.
    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. Der folgende Code erstellt eine Funktion zum Löschen von Folien, die für Premium-Kunden markiert sind. Bei diesem Code ist Folgendes zu beachten:

    • Da die key Eigenschaften und value der Tags nach context.syncgelesen werden, müssen sie zuerst geladen werden.
    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();
  });
}

Festlegen benutzerdefinierter Metadaten für die Präsentation

Add-Ins können auch Tags auf die gesamte Präsentation anwenden. Dadurch können Sie Tags für Metadaten auf Dokumentebene verwenden, ähnlich wie die CustomProperty-Klassein Word. Im Gegensatz zur Word-Klasse CustomProperty kann der Wert eines PowerPoint-Tags jedoch nur vom Typ stringsein.

Der folgende Code ist ein Beispiel für das Hinzufügen eines Tags zu einer Präsentation.

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

    await context.sync();
  });
}

Der folgende Code ist ein Beispiel für das Löschen eines Tags aus einer Präsentation. Beachten Sie, dass der Schlüssel des Tags an die delete -Methode des übergeordneten TagsCollection Objekts übergeben wird.

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

    await context.sync();
  });
}