Programmgesteuertes Hinzufügen und Löschen von PowerPoint-Folien

Schnelles Hinzufügen und Entfernen von Folien zu einer PowerPoint-Präsentation mithilfe eines Add-Ins.

  • Fügen Sie Folien programmgesteuert mit SlideCollection.add() hinzu, und steuern Sie bei Bedarf master und Layouts.
  • Passen Sie die master oder das Layout einer vorhandenen Folie an, oder wählen Sie spezifische slideMasterId und layoutId zur Laufzeit aus.
  • Löschen von Folien nach Verweis oder Index; schließen Sie immer nach Änderungen ein await context.sync() .
  • Geschätzte Zeit: Probieren Sie die kurzen Beispiele in ca. 2–5 Minuten aus.

Die APIs zum Hinzufügen von Folien werden hauptsächlich in Szenarien verwendet, in denen die IDs der Folienmaster und Layouts in der Präsentation zur Codierungszeit bekannt sind oder zur Laufzeit in einer Datenquelle gefunden werden können. In einem solchen Szenario müssen Entweder Sie oder der Kunde eine Datenquelle erstellen und verwalten, die das Auswahlkriterium (z. B. die Namen oder Bilder von Folienmastern und Layouts) mit den IDs der Folienmaster und Layouts korreliert. Die APIs können auch in Szenarien verwendet werden, in denen der Benutzer Folien einfügen kann, die das Standardfolien-master und das Standardlayout des master verwenden, sowie in Szenarien, in denen der Benutzer eine vorhandene Folie auswählen und eine neue mit der gleichen Folie master und Layout (aber nicht den gleichen Inhalt) erstellen kann. Weitere Informationen hierzu finden Sie unter Auswählen der zu verwendenden Folie master und Layouts.

Hinzufügen einer Folie mit SlideCollection.add

Fügen Sie Folien mit der SlideCollection.add-Methode hinzu. Im folgenden Beispiel wird eine Folie, die die Standardfolie der Präsentation verwendet, master und das erste Layout dieser master hinzugefügt. Die -Methode fügt am Ende der Präsentation immer neue Folien hinzu.

async function addSlide() {
  await PowerPoint.run(async function(context) {
    context.presentation.slides.add();

    await context.sync();
  });
}

Auswählen der zu verwendenden master und layouts

Verwenden Sie den AddSlideOptions-Parameter, um zu steuern, welche Folie master für die neue Folie verwendet wird und welches Layout innerhalb der master verwendet wird. Es folgt ein Beispiel. Bei diesem Code ist Folgendes zu beachten:

  • Sie können eine oder beide Eigenschaften des AddSlideOptions -Objekts einschließen.
  • Wenn beide Eigenschaften verwendet werden, muss das angegebene Layout zum angegebenen master gehören, andernfalls wird ein Fehler ausgelöst.
  • Wenn die masterId Eigenschaft nicht vorhanden ist (oder ihr Wert eine leere Zeichenfolge ist), wird die Standardfolie master verwendet, und die layoutId muss ein Layout dieser Folie master sein.
  • Die Standardfolie master ist die Folie master, die von der letzten Folie in der Präsentation verwendet wird. (In dem ungewöhnlichen Fall, in dem sich derzeit keine Folien in der Präsentation befinden, ist die Standardfolie master die erste Folie master in der Präsentation.)
  • Wenn die layoutId Eigenschaft nicht vorhanden ist (oder ihr Wert eine leere Zeichenfolge ist), wird das erste Layout des master verwendet, das masterId von angegeben wird.
  • Beide Eigenschaften sind Zeichenfolgen einer von drei möglichen Formen: nnnnnnnnnnnnn,##mmmmmmmmm oder nnnnnnnnnnmmmmmmmmmmm#, wobei nnnnnnnn die ID des master oder Layouts (in der Regel 10 Ziffern) und mmmmmmmmmmm die Erstellungs-ID des master oder layouts ist (in der Regel 6 bis 10 Ziffern). Beispiele hierfür sind 2147483690#2908289500, 2147483690#und #2908289500.
async function addSlide() {
    await PowerPoint.run(async function(context) {
        context.presentation.slides.add({
            slideMasterId: "2147483690#2908289500",
            layoutId: "2147483691#2499880"
        });
    
        await context.sync();
    });
}

Es gibt keine praktische Möglichkeit, die ID oder Die Erstellungs-ID einer Folie master oder Layouts zu ermitteln. Aus diesem Grund können Sie den AddSlideOptions Parameter wirklich nur verwenden, wenn Sie die IDs zur Codierungszeit kennen oder ihr Add-In sie zur Laufzeit ermitteln kann. Da von Benutzern nicht erwartet werden kann, dass sie sich die IDs merken, benötigen Sie auch eine Möglichkeit, es dem Benutzer zu ermöglichen, Folien auszuwählen, z. B. anhand des Namens oder anhand eines Bilds, und dann jeden Titel oder jedes Bild mit der ID der Folie korrelieren.

Dementsprechend wird der AddSlideOptions Parameter hauptsächlich in Szenarien verwendet, in denen das Add-In für die Arbeit mit einem bestimmten Satz von Folienmastern und Layouts konzipiert ist, deren IDs bekannt sind. In einem solchen Szenario müssen Entweder Sie oder der Kunde eine Datenquelle erstellen und verwalten, die ein Auswahlkriterium (z. B. Folien-master- und Layoutnamen oder -bilder) mit den entsprechenden IDs oder Erstellungs-IDs korreliert.

Lassen Sie den Benutzer eine passende Folie auswählen

Wenn Ihr Add-In in Szenarien verwendet werden kann, in denen die neue Folie dieselbe Kombination aus Folien master und Layout verwenden sollte, die von einer vorhandenen Folie verwendet wird, kann Ihr Add-In (1) den Benutzer auffordern, eine Folie auszuwählen, und (2) die IDs der Folie master und Layout lesen. Die folgenden Schritte zeigen, wie Sie die IDs lesen und eine Folie mit einem passenden master und Layout hinzufügen.

  1. Erstellen Sie eine Funktion, um den Index der ausgewählten Folie abzurufen. Es folgt ein Beispiel. 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 Promise-rückgabende Funktion 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 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));
            }
        });
    });
}

  2. Rufen Sie Ihre neue Funktion in PowerPoint.run() der Hauptfunktion auf, die die Folie hinzufügt. Es folgt ein Beispiel.

    async function addSlideWithMatchingLayout() {
    await PowerPoint.run(async function(context) {

        let selectedSlideIndex = await getSelectedSlideIndex();

        // Decrement the index because the value returned by getSelectedSlideIndex()
        // is 1-based, but SlideCollection.getItemAt() is 0-based.
        const realSlideIndex = selectedSlideIndex - 1;
        const selectedSlide = context.presentation.slides.getItemAt(realSlideIndex).load("slideMaster/id, layout/id");

        await context.sync();

        context.presentation.slides.add({
            slideMasterId: selectedSlide.slideMaster.id,
            layoutId: selectedSlide.layout.id
        });

        await context.sync();
    });
}

Löschen von Folien

Löschen Sie eine Folie, indem Sie einen Verweis auf das Slide-Objekt abrufen, das die Folie darstellt, und dann die Slide.delete-Methode aufrufen. Im folgenden Beispiel wird die 4. Folie gelöscht.

async function deleteSlide() {
    await PowerPoint.run(async function(context) {

        // The slide index is zero-based. 
        const slide = context.presentation.slides.getItemAt(3);
        slide.delete();

        await context.sync();
    });
}

Überlegungen

  • Master-/Layout-IDs sind nicht transparent: slideMasterId und layoutId sind ID-Zeichenfolgen (häufig lange numerische Token). Es gibt keine Benutzeroberfläche, auf der Benutzer sie ermitteln können, daher sollte Ihr Add-In Anzeigenamen oder Miniaturansichten zur Laufzeit den IDs zuordnen.
  • Indexunterschiede: Office.context.document.getSelectedDataAsync(Office.CoercionType.SlideRange) Gibt 1-basierte Folienindizes zurück. slides.getItemAt(...) ist 0-basiert– subtrahiert 1, wenn der Wert verwendet wird.
  • Aufruf context.sync() nach Mutationen: Das Hinzufügen oder Löschen von Folien wirkt sich auf das Dokument aus. Schließen Sie nach dem Aufruf add() oder delete() immer einawait context.sync(), um sicherzustellen, dass Änderungen angewendet werden.
  • Layout muss zu master gehören: Wenn Sie sowohl als layoutIdauch slideMasterId angeben, muss das Layout zu diesem master gehören, andernfalls wird ein Fehler ausgelöst.
  • Arbeiten an Kopien für Massenänderungen: Das Löschen von Folien erfolgt sofort. Erwägen Sie beim Ausführen von Batchlöschvorgängen, Benutzer aufzufordern oder eine Kopie auszuführen.
  • Last updated on