Einrichten einer Bindung an Regionen in einem Dokument oder Arbeitsblatt

Verwenden Sie eine Bindung, wenn Ihr Add-In zuverlässigen Zugriff auf einen bestimmten Bereich einer Excel-Arbeitsmappe oder eines Word-Dokuments benötigt. Eine Bindung ordnet dem Bereich eine eindeutige ID zu, sodass Ihr Add-In zu diesem zurückkehren kann, nachdem der Benutzer seine Auswahl geändert oder das Dokument erneut geöffnet hat.

Mit einer Bindung kann Ihr Add-In:

• Greifen Sie auf allgemeine Datenstrukturen wie Tabellen, Bereiche oder Text zu.
• Daten lesen und schreiben, ohne dass der Benutzer zuerst die Region auswählen muss.
• Überwachen Sie Daten- und Auswahländerungen innerhalb der gebundenen Region.
• Pflegen Sie die Beziehung zwischen mehreren Sitzungen, da die Bindung mit dem Dokument gespeichert wird.

Auswählen des richtigen Bindungstyps

Office unterstützt drei Bindungstypen. Wählen Sie einen Typ basierend auf der Region und den Daten aus, die das Add-In lesen oder schreiben muss.

Geben Sie den Typ mit dem bindingType Parameter an, wenn Sie eine Bindung mithilfe von addFromSelectionAsync, addFromPromptAsync oder addFromNamedItemAsync erstellen.

Textbindung

Eine Textbindung stellt einen Dokumentbereich als Text dar.

In Word funktionieren die meisten zusammenhängenden Auswahlen. In Excel kann die Textbindung nur für die Auswahl einzelner Zelle verwendet werden. Excel unterstützt nur Nur-Text, während Word drei Formate unterstützt: Nur-Text, HTML und Open XML für Office.

Matrixbindung

Eine Matrixbindung stellt einen festen Bereich tabellarischer Daten ohne Überschriften dar.

Lesen oder schreiben Sie Matrixdaten als zweidimensional Array (ein Array von Arrays in JavaScript). Beispielsweise sehen zwei Zeilen mit string Werten in zwei Spalten aus [['a', 'b'], ['c', 'd']]wie , und eine einzelne Spalte mit drei Zeilen sieht aus wie [['a'], ['b'], ['c']].

In Excel funktioniert jede zusammenhängende Auswahl von Zellen für die Matrixbindung. In Word wird die Matrixbindung nur für Tabellen unterstützt.

Tabellenbindung

Eine Tabellenbindung stellt eine Tabelle mit Überschriften dar.

Daten in einer Tabellenbindung werden als TableData-Objekt gelesen oder geschrieben. Das TableData Objekt macht Daten über die headersrows und-Eigenschaften verfügbar.

Jede Excel- oder Word-Tabelle kann die Basis einer Tabellenbindung sein. Nachdem Sie eine Tabellenbindung eingerichtet haben, werden neue Zeilen oder Spalten, die Benutzer der Tabelle hinzufügen, automatisch in die Bindung aufgenommen.

Nachdem Sie eine Bindung mit einer der drei "addFrom"-Methoden erstellt haben, können Sie mit den Daten und Eigenschaften der Bindung arbeiten, indem Sie das entsprechende Objekt verwenden: MatrixBinding, TableBinding oder TextBinding. Alle drei Objekte erben die getDataAsync - und setDataAsync-Methoden vom Binding Objekt für die Interaktion mit gebundenen Daten.

Erstellen einer Bindung aus der aktuellen Auswahl

Im folgenden Beispiel wird der aktuellen Auswahl mit der addFromSelectionAsync-Methode eine Textbindung hinzugefügt, die aufgerufen wirdmyBinding.

Office.context.document.bindings.addFromSelectionAsync(Office.BindingType.Text, { id: 'myBinding' }, function (asyncResult) {
    if (asyncResult.status == Office.AsyncResultStatus.Failed) {
        write('Action failed. Error: ' + asyncResult.error.message);
    } else {
        write('Added new binding with type: ' + asyncResult.value.type + ' and id: ' + asyncResult.value.id);
    }
});

// Function that writes to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += message;
}

In diesem Beispiel ist der Bindungstyp Text, sodass eine TextBinding-Instanz für die Auswahl erstellt wird. Unterschiedliche Bindungstypen machen unterschiedliche Daten und Vorgänge verfügbar. Office.BindingType ist eine Aufzählung verfügbarer Bindungstypen.

Der zweite optionale Parameter gibt die ID der neuen Bindung an. Wenn Sie keine ID angeben, wird automatisch eine generiert.

Die anonyme Funktion, die als letzter Rückrufparameter übergeben wird, wird ausgeführt, wenn die Bindungserstellung abgeschlossen ist. Die Funktion empfängt einen einzelnen Parameter, asyncResult, der Zugriff auf ein AsyncResult-Objekt mit dem Status des Aufrufs bietet. Die AsyncResult.value Eigenschaft enthält einen Verweis auf ein Binding-Objekt des angegebenen Typs für die neu erstellte Bindung. Sie können dieses Binding-Objekt verwenden, um Daten abzurufen und festzulegen.

Erstellen einer Bindung über eine Eingabeaufforderung

Die folgende Funktion fügt eine Textbindung hinzu, die mithilfe der addFromPromptAsync-Methode aufgerufen wirdmyBinding. Mit dieser Methode können Benutzer den Bereich für die Bindung über die integrierte Bereichsauswahlaufforderung der Anwendung angeben.

function bindFromPrompt() {
    Office.context.document.bindings.addFromPromptAsync(Office.BindingType.Text, { id: 'myBinding' }, function (asyncResult) {
        if (asyncResult.status == Office.AsyncResultStatus.Failed) {
            write('Action failed. Error: ' + asyncResult.error.message);
        } else {
            write('Added new binding with type: ' + asyncResult.value.type + ' and id: ' + asyncResult.value.id);
        }
    });
}

// Function that writes to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += message;
}

In diesem Beispiel ist der Bindungstyp Text, sodass für die Auswahl des Benutzers in der Eingabeaufforderung eine TextBinding-Instanz erstellt wird.

Der zweite Parameter enthält die ID der neuen Bindung. Wenn Sie keine ID angeben, wird automatisch eine generiert.

Die als dritter Rückrufparameter übergebene anonyme Funktion wird nach Abschluss der Bindungserstellung ausgeführt. Wenn die Rückruffunktion ausgeführt wird, enthält das AsyncResult-Objekt den Status des Aufrufs und die neu erstellte Bindung.

Der folgende Screenshot zeigt die integrierte Eingabeaufforderung für die Bereichsauswahl in Excel.

Hinzufügen einer Bindung zu einem benannten Element

Die folgende Funktion fügt dem vorhandenen myRange benannten Element mithilfe der addFromNamedItemAsync-Methode eine Bindung als "Matrix"-Bindung hinzu und weist die Bindungen id als "myMatrix" zu.

function bindNamedItem() {
    Office.context.document.bindings.addFromNamedItemAsync("myRange", "matrix", {id:'myMatrix'}, function (result) {
        if (result.status == 'succeeded'){
            write('Added new binding with type: ' + result.value.type + ' and id: ' + result.value.id);
            }
        else
            write('Error: ' + result.error.message);
    });
}

// Function that writes to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += message;
}

In Excel bezieht sich der itemName Parameter addFromNamedItemAsync auf einen vorhandenen benannten Bereich, einen mit der A1-Bezugsart ("A1:A3") angegebenen Bereich oder eine Tabelle. Standardmäßig weist Excel die Namen "Tabelle1" für die erste Tabelle, "Tabelle2" für die zweite Tabelle usw. zu. Um einer Tabelle auf der Excel-Benutzeroberfläche einen aussagekräftigen Namen zuzuweisen, verwenden Sie die Eigenschaft Tabellenname auf der Registerkarte Tabellentools | Registerkarte "Entwurf ".

Die folgende Funktion erstellt in Excel eine Bindung an die ersten drei Zellen in Spalte A ("A1:A3"), weist die ID "MyCities"zu und schreibt dann drei Ortsnamen in diese Bindung.

 function bindingFromA1Range() {
    Office.context.document.bindings.addFromNamedItemAsync("A1:A3", "matrix", { id: "MyCities" },
        function (asyncResult) {
            if (asyncResult.status == "failed") {
                write('Error: ' + asyncResult.error.message);
            } else {
                // Write data to the new binding.
                Office.select("bindings#MyCities").setDataAsync([['Berlin'], ['Munich'], ['Duisburg']], { coercionType: "matrix" },
                    function (asyncResult) {
                        if (asyncResult.status == "failed") {
                            write('Error: ' + asyncResult.error.message);
                        }
                    });
            }
        });
}
// Function that writes to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += message;
}

In Word bezieht sich der itemName Parameter addFromNamedItemAsync auf die Title Eigenschaft eines Rich Text Inhaltssteuerelements. (Eine Bindung kann nur an das Rich Text-Inhaltssteuerelement eingerichtet werden.)

Standardmäßig ist einem Inhaltssteuerelement kein Title Wert zugewiesen. Um einen bedeutungsvollen Namen in der Word-Benutzeroberfläche zuzuweisen, verwenden Sie nach dem Einfügen eines Rich-Text-Inhaltssteuerelements aus der Gruppe Steuerelemente auf der Registerkarte "Entwicklertools" den Befehl Eigenschaften in der Gruppe "Steuerelemente", um das Dialogfeld "Eigenschaften des Inhaltssteuerelements" anzuzeigen. Legen Sie dann die Title Eigenschaft des Inhaltssteuerelements auf den Namen fest, auf den Sie im Code verweisen möchten.

Die folgende Funktion erstellt in Word eine Textbindung an ein Rich-Text-Inhaltssteuerelement mit dem Namen "FirstName", weist die ID"firstName" zu und zeigt diese Informationen dann an.

function bindContentControl() {
    Office.context.document.bindings.addFromNamedItemAsync('FirstName',
        Office.BindingType.Text, {id:'firstName'},
        function (result) {
            if (result.status === Office.AsyncResultStatus.Succeeded) {
                write('Control bound. Binding.id: '
                    + result.value.id + ' Binding.type: ' + result.value.type);
            } else {
                write('Error:', result.error.message);
            }
    });
}
// Function that writes to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += message;
}

Abrufen aller Bindungen

Im folgenden Beispiel werden alle Bindungen in einem Dokument mithilfe der getAllAsync-Methode abgerufen.

Office.context.document.bindings.getAllAsync(function (asyncResult) {
    let bindingString = '';
    for (let i in asyncResult.value) {
        bindingString += asyncResult.value[i].id + '\n';
    }
    write('Existing bindings: ' + bindingString);
});

// Function that writes to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += message;
}

Die als Parameter übergebene callback anonyme Funktion wird nach Abschluss des Vorgangs ausgeführt. Die Funktion wird mit einem einzelnen Parameter aufgerufen, asyncResultder ein Array der Bindungen im Dokument enthält. Das Array wird zur Erstellung einer Zeichenfolge wiederholt, die die IDs der Bindungen enthält. Anschließend wird die Zeichenfolge im Nachrichtenfeld angezeigt.

Abrufen einer Bindung nach ID mit getByIdAsync

Im folgenden Beispiel wird die getByIdAsync-Methode verwendet, um eine Bindung in einem Dokument abzurufen, indem dessen ID angegeben wird. In diesem Beispiel wird davon ausgegangen, dass dem Dokument mithilfe einer der weiter oben in diesem Artikel beschriebenen Methoden eine Bindung mit dem Namen 'myBinding' hinzugefügt wurde.

Office.context.document.bindings.getByIdAsync('myBinding', function (asyncResult) {
    if (asyncResult.status == Office.AsyncResultStatus.Failed) {
        write('Action failed. Error: ' + asyncResult.error.message);
    }
    else {
        write('Retrieved binding with type: ' + asyncResult.value.type + ' and id: ' + asyncResult.value.id);
    }
});

// Function that writes to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += message;
}

In diesem Beispiel ist der erste id Parameter die ID der abzurufenden Bindung.

Die als zweiter Rückrufparameter übergebene anonyme Funktion wird nach Abschluss des Vorgangs ausgeführt. Die Funktion wird mit einem einzelnen Parameter, asyncResult, aufgerufen, der den Status des Aufrufs und die Bindung mit der ID "myBinding" enthält.

Abrufen einer Bindung nach ID mithilfe Office.select

Im folgenden Beispiel wird die Office.select-Funktion verwendet, um eine Binding-Objektzusage in einem Dokument abzurufen, indem dessen ID in einer Selektorzeichenfolge angegeben wird. Anschließend wird die getDataAsync-Methode aufgerufen, um Daten aus der angegebenen Bindung abzurufen. In diesem Beispiel wird davon ausgegangen, dass dem Dokument mithilfe einer der weiter oben in diesem Artikel beschriebenen Methoden eine Bindung mit dem Namen 'myBinding' hinzugefügt wurde.

Office.select("bindings#myBinding", function onError(){}).getDataAsync(function (asyncResult) {
    if (asyncResult.status == Office.AsyncResultStatus.Failed) {
        write('Action failed. Error: ' + asyncResult.error.message);
    } else {
        write(asyncResult.value);
    }
});

// Function that writes to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += message;
}

Wenn die select Funktionszusage erfolgreich ein Binding-Objekt zurückgibt, macht dieses Objekt nur die folgenden vier Methoden verfügbar: getDataAsync, setDataAsync, addHandlerAsync und removeHandlerAsync. Wenn die Zusage kein Binding-Objekt zurückgeben kann, kann der onError Rückruf verwendet werden, um auf ein asyncResult.error-Objekt zuzugreifen, um weitere Informationen zu erhalten. Wenn Sie einen Member des Binding-Objekts aufrufen müssen, bei dem es sich nicht um die vier Methoden handelt, die durch die von der select Funktion zurückgegebene Zusage des Binding-Objekts verfügbar gemacht werden, verwenden Sie stattdessen die getByIdAsync-Methode, indem Sie die Document.bindings-Eigenschaft und die getByIdAsync-Methode verwenden, um das Binding-Objekt abzurufen.

Freigeben einer Bindung nach ID

Im folgenden Beispiel wird die releaseByIdAsync-Methode verwendet, um eine Bindung in einem Dokument durch Angabe der zugehörigen ID freizugeben.

Office.context.document.bindings.releaseByIdAsync('myBinding', function (asyncResult) {
    write('Released myBinding!');
});

// Function that writes to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += message;
}

In diesem Beispiel ist der erste id Parameter die ID der zu releaseierenden Bindung.

Die anonyme Funktion, die als zweiter Parameter übergeben wird, ist ein Rückruf, der ausgeführt wird, wenn der Vorgang abgeschlossen ist. Die Funktion wird mit einem einzelnen Parameter, asyncResult, aufgerufen, der den Status des Aufrufs enthält.

Lesen von Daten aus einer Bindung

Im folgenden Beispiel wird die getDataAsync-Methode verwendet, um Daten aus einer vorhandenen Bindung abzurufen.

myBinding.getDataAsync(function (asyncResult) {
    if (asyncResult.status == Office.AsyncResultStatus.Failed) {
        write('Action failed. Error: ' + asyncResult.error.message);
    } else {
        write(asyncResult.value);
    }
});

// Function that writes to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += message;
}

myBinding ist eine Variable, die eine vorhandene Textbindung in dem Dokument enthält. Alternativ können Sie Office.select verwenden, um über ihre ID auf die Bindung zuzugreifen und den Aufruf der getDataAsync-Methode wie folgt zu starten:

Office.select("bindings#myBindingID").getDataAsync

Die an die Methode übergebene anonyme Funktion ist ein Rückruf, der ausgeführt wird, wenn der Vorgang abgeschlossen ist. Die Eigenschaft AsyncResult.value enthält die Daten in myBinding. Der Typ des Werts ist vom Bindungstyp abhängig. Die Bindung in diesem Beispiel ist eine Textbindung, sodass der Wert eine Zeichenfolge enthält. Weitere Beispiele zum Arbeiten mit Matrix- und Tabellenbindungen finden Sie im Thema zur getDataAsync-Methode.

Schreiben von Daten in eine Bindung

Im folgenden Beispiel wird die setDataAsync-Methode verwendet, um Daten in einer vorhandenen Bindung festzulegen.

myBinding.setDataAsync('Hello World!', function (asyncResult) { });

myBinding ist eine Variable, die eine vorhandene Textbindung in dem Dokument enthält.

In diesem Beispiel ist der erste Parameter der Wert, der festgelegt werden myBindingsoll. Da es sich dabei um eine Textbindung handelt, ist der Wert vom Typ string. Unterschiedliche Bindungstypen akzeptieren unterschiedliche Datentypen.

Die an die Methode übergebene anonyme Funktion ist ein Rückruf, der ausgeführt wird, wenn der Vorgang abgeschlossen ist. Die Funktion wird mit einem einzelnen Parameter aufgerufen, asyncResultder den Status des Ergebnisses enthält.

Erkennen von Änderungen an Daten oder Auswahlen in einer Bindung

Die folgende Funktion fügt einen Ereignishandler an das DataChanged-Ereignis einer Bindung mit der ID "MyBinding" an.

function addHandler() {
Office.select("bindings#MyBinding").addHandlerAsync(
    Office.EventType.BindingDataChanged, dataChanged);
}
function dataChanged(eventArgs) {
    write('Bound data changed in binding: ' + eventArgs.binding.id);
}
// Function that writes to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += message;
}

myBinding ist eine Variable, die eine vorhandene Textbindung in dem Dokument enthält.

Der erste eventType-Parameter von addHandlerAsync gibt den Namen des zu abonnierenden Ereignisses an. Office.EventType ist eine Enumeration von verfügbaren Ereignistypwerten. Office.EventType.BindingDataChanged wird die Zeichenfolge "bindingDataChanged" ergeben.

Die dataChanged Funktion, die als zweiter Handlerparameter übergeben wird, ist ein Ereignishandler, der ausgeführt wird, wenn die Daten in der Bindung geändert werden. Die Funktion wird mit einem einzigen Parameter, eventArgs, aufgerufen, der einen Verweis zu der Bindung enthält. Diese Bindung kann zum Abrufen der aktualisierten Daten verwendet werden.

Entsprechend können Sie feststellen, wenn ein Benutzer die Auswahl in einer Bindung ändert, indem Sie an das SelectionChanged-Ereignis einer Bindung einen Ereignishandler anfügen. Geben Sie dazu den eventType Parameter von addHandlerAsync als Office.EventType.BindingSelectionChanged oder "bindingSelectionChanged"an.

Sie können mehrere Ereignishandler für ein bestimmtes Ereignis hinzufügen, indem Sie addHandlerAsync erneut aufrufen und eine zusätzliche Ereignishandlerfunktion für den handler Parameter übergeben. Der Name jeder Ereignishandlerfunktion muss eindeutig sein.

Entfernen eines Ereignishandlers

Um einen Ereignishandler für ein Ereignis zu entfernen, rufen Sie removeHandlerAsync auf und übergeben den Ereignistyp als ersten eventType-Parameter und den Namen der zu entfernenden Ereignishandlerfunktion als zweiten Handlerparameter . Die folgende Funktion entfernt beispielsweise die Ereignishandlerfunktion, die dataChanged im Beispiel des vorherigen Abschnitts hinzugefügt wurde.

function removeEventHandlerFromBinding() {
    Office.select("bindings#MyBinding").removeHandlerAsync(
        Office.EventType.BindingDataChanged, {handler:dataChanged});
}

Siehe auch

• Grundlegendes zur JavaScript-API für Office
• Asynchrone Programmierung in Office-Add-Ins
• Lesen und Schreiben von Daten in die aktive Auswahl in einem Dokument oder Arbeitsblatt