Binden und Aktualisieren von Shapes in einer PowerPoint-Präsentation

Verwenden Sie Shape-Bindungen, wenn Das Add-In das gleiche Shape später suchen und aktualisieren muss, z. B. beim Aktualisieren einer Zahl aus einer externen Datenquelle.

Eine Bindung erstellt einen stabilen Bezeichner für ein Shape. Ihr Add-In kann diesen Bezeichner verwenden, um das Shape erneut abzurufen, es zu aktualisieren und Fälle zu behandeln, in denen das Shape gelöscht wurde.

Bindungen bieten zwei wichtige Vorteile:

• Sie stellen eine Beziehung zwischen dem Add-In und der Form im Dokument her. Das Dokument behält Bindungen bei, sodass Sie später darauf zugreifen können.
• Sie ermöglichen den Zugriff auf Shape-Eigenschaften zum Lesen oder Aktualisieren, ohne dass der Benutzer Shapes auswählen muss.

Die folgende Abbildung zeigt, wie ein Add-In an zwei Formen auf einer Folie gebunden werden kann. Jede Form verfügt über eine Bindungs-ID, die vom Add-In erstellt wurde: star und pie. Mithilfe der Bindungs-ID kann das Add-In auf die gewünschte Form zugreifen, um seine Eigenschaften zu aktualisieren.

Szenario: Synchronisieren von Shapes mit einer Datenquelle

Ein gängiges Szenario besteht darin, Präsentationsvisuals aus einer Datenquelle auf dem neuesten Stand zu halten. Anstatt Bilder manuell zu ersetzen, kann ein Add-In die neuesten Daten abrufen, in ein Base64-codiertes Bild konvertieren und die richtige Form mithilfe seiner Bindungs-ID aktualisieren.

In einer allgemeinen Implementierung sollten Sie zwei Komponenten zum Binden einer Form in PowerPoint und zum Aktualisieren mit einem neuen Bild aus einer Datenquelle in Betracht ziehen.

1. Die Datenquelle. Dies ist eine beliebige Datenquelle oder Objektbibliothek wie Microsoft SharePoint oder Microsoft OneDrive.
2. Das PowerPoint-Add-In. Das Add-In ruft Daten aus der Datenquelle basierend auf den Anforderungen des Benutzers ab. Die Daten werden in ein Base64-codiertes Bild konvertiert. Dies ist der einzige Fülltyp, den die gebundene Form akzeptieren kann. Es fügt ein Shape auf Anforderung des Benutzers ein und bindet es an einen eindeutigen Bezeichner. Anschließend wird das Shape mit dem Base64-Bild basierend auf der ursprünglichen Datenquelle gefüllt. Shapes werden auf Anforderung des Benutzers aktualisiert, und das Add-In verwendet den Bindungsbezeichner, um die Form zu finden und das Bild mit dem zuletzt gespeicherten Base64-Bild zu aktualisieren.

Erstellen einer gebundenen Form in PowerPoint

Verwenden Sie BindingCollection.add , um eine Bindung zu erstellen, die auf eine bestimmte Form verweist.

Das folgende Beispiel zeigt, wie Sie eine Form auf der ersten ausgewählten Folie erstellen.

await PowerPoint.run(async (context) => {
    const slides = context.presentation.getSelectedSlides();

    // Insert new shape on first selected slide.
    const myShape = slides
        .getItemAt(0)
        .shapes.addGeometricShape(PowerPoint.GeometricShapeType.rectangle, {
            top: 100,
            left: 30,
            width: 200,
            height: 200
        });

    // Fill shape with a Base64-encoded image.
    // Note: The image is typically created from a data source request.
    const productsImage = "...Base64 image data...";
    myShape.fill.setImage(productsImage);

    await context.sync();
});

Rufen Sie auf BindingCollection.add , um die Form der PowerPoint-Bindungsauflistung hinzuzufügen. Das folgende Beispiel wird aus dem vorherigen Beispiel fortgesetzt und fügt eine neue Bindung für myShapehinzu.

// Create a binding ID to track the shape for later updates.
const bindingId = "productChart";
// Create a binding by adding the shape to the bindings collection.
context.presentation.bindings.add(myShape, PowerPoint.BindingType.shape, bindingId);

Aktualisieren einer gebundenen Form mit aktualisierten Daten

Nachdem die Bilddaten aktualisiert wurden, aktualisieren Sie das Shape-Bild, indem Sie es über den Bindungsbezeichner suchen. Im folgenden Codebeispiel wird gezeigt, wie Sie eine gebundene Form mit dem Bezeichner finden und mit einem aktualisierten Bild füllen. Das Image wird vom Add-In basierend auf der Datenquellenanforderung aktualisiert oder direkt von der Datenquelle bereitgestellt.

async function updateBinding(bindingId, image) {
    await PowerPoint.run(async (context) => {
        try {
            // Get the shape based on binding ID.
            const myShape = context.presentation.bindings
                .getItem(bindingId)
                .getShape();

            // Update the shape to latest image.
            myShape.fill.setImage(image);
            await context.sync();

        } catch (err) {
            console.error(err);
        }
    });
}

Löschen einer Bindung

Im folgenden Beispiel wird gezeigt, wie Sie eine Bindung löschen, indem Sie sie aus der bindings-Auflistung löschen.

async function deleteBinding(bindingId) {
    await PowerPoint.run(async (context) => {
        context.presentation.bindings.getItem(bindingId).delete();
        await context.sync();
    });
}

Laden von Bindungen

Wenn ein Benutzer eine Präsentation öffnet und das Add-In zum ersten Mal geladen wird, können Sie alle Bindungen laden, um weiterhin mit ihnen zu arbeiten. Der folgende Code zeigt, wie alle Bindungen in einer Präsentation geladen und in der Konsole angezeigt werden.

async function loadBindings() {
    await PowerPoint.run(async (context) => {
        try {
            const myBindings = context.presentation.bindings;
            myBindings.load("items");
            await context.sync();

            // Log all binding IDs to console.
            if (myBindings.items.length > 0) {
                myBindings.items.forEach((binding) => {
                    console.log(binding.id);
                });
            }
        } catch (err) {
            console.error(err);
        }
    });
}

Fehlerbehandlung beim Löschen einer Bindung oder Form

Wenn Sie eine Form löschen, entfernt PowerPoint auch die zugehörige Bindung aus der Bindungsauflistung. Verweise auf diese Bindung oder Form können fehlschlagen, wenn Sie Methoden aufrufen oder auf Eigenschaften zugreifen. Behandeln Sie diese Fehlerszenarien, wenn Ihr Add-In Objekte speichert oder Shape speichertBinding.

Der folgende Code zeigt einen Ansatz zur Fehlerbehandlung, wenn ein Bindungsobjekt auf eine gelöschte Bindung verweist. Verwenden Sie eine try/catch-Anweisung, und rufen Sie dann eine Funktion auf, um alle Bindungs- und Formverweise erneut zu laden, wenn ein Fehler auftritt.

async function getShapeFromBindingID(id) {
    await PowerPoint.run(async (context) => {
        try {
            const binding = context.presentation.bindings.getItem(id);
            const shape = binding.getShape();

            await context.sync();
            return shape;
        } catch (err) {
            console.log(err);
            return undefined;
        }
    });
}

Siehe auch

Wenn Sie die visuelle Aktualität beibehalten, können Sie auch die Shape-Layering mithilfe von Shape.zOrderPosition überprüfen.

• Erstellen und Formatieren von Formen in PowerPoint-Add-Ins
• PowerPoint-JavaScript-Objektmodell in Office-Add-Ins
• Erstellen des ersten PowerPoint-Aufgabenbereich-Add-Ins
• Lernprogramm: Erstellen eines PowerPoint-Aufgabenbereich-Add-Ins
• Einrichten einer Bindung an Regionen in einem Dokument oder Arbeitsblatt
• JavaScript-API-Referenz für PowerPoint