Einrichten einer Bindung an Regionen in einem Dokument oder Arbeitsblatt

Mit Bindungen kann Ihr Add-In konsistent auf bestimmte Regionen eines Dokuments oder einer Kalkulationstabelle zugreifen. Stellen Sie sich eine Bindung als Lesezeichen vor, die eine bestimmte Position speichert, auch wenn Benutzer ihre Auswahl ändern oder an einer anderen Stelle im Dokument navigieren. Hier finden Sie insbesondere die Bindungen, die Ihr Add-In bieten.

• Greifen Sie auf allgemeine Datenstrukturen in unterstützten Office-Anwendungen zu, z. B. Tabellen, Bereiche oder Text.
• Lesen und Schreiben von Daten , ohne dass Benutzer zuerst eine Auswahl treffen müssen.
• Erstellen Sie dauerhafte Beziehungen zwischen Ihrem Add-In und Dokumentdaten. Bindungen werden mit dem Dokument gespeichert und funktionieren sitzungsübergreifend.

Um eine Bindung zu erstellen, rufen Sie eine der folgenden Bindings-Objektmethoden auf, um einen Dokumentbereich einem eindeutigen Bezeichner zuzuordnen: addFromPromptAsync, addFromSelectionAsync oder addFromNamedItemAsync. Nachdem Sie die Bindung eingerichtet haben, verwenden Sie ihren Bezeichner, um jederzeit aus dieser Region zu lesen oder in diese zu schreiben.

Sie können auch Daten- und Auswahländerungsereignisse für bestimmte gebundene Regionen abonnieren. Dies bedeutet, dass Ihr Add-In nur über Änderungen innerhalb des gebundenen Bereichs benachrichtigt wird, nicht über das gesamte Dokument.

Auswählen des richtigen Bindungstyps

Office unterstützt drei verschiedene Arten von Bindungen. Sie geben den Typ mit dem bindingType-Parameter an, wenn Sie eine Bindung mit addFromSelectionAsync, addFromPromptAsync oder addFromNamedItemAsync erstellen.

Textbindung

Textbindung : Bindet an einen Dokumentbereich, der als Text dargestellt werden kann.

In Word funktionieren die meisten zusammenhängenden Auswahlen. In Excel können nur einzelne Zellauswahlen Textbindung verwenden. Excel unterstützt nur Nur-Text, während Word drei Formate unterstützt: Nur-Text, HTML und Open XML für Office.

Matrixbindung

Matrixbindung : Bindet an einen festen Bereich, der tabellarische Daten ohne Header enthält.

Daten in einer Matrixbindung werden als zweidimensionales Array (ein Array von Arrays in JavaScript) gelesen oder geschrieben. Beispielsweise würden zwei Zeilen mit Zeichenfolgenwerten in zwei Spalten wie [['a', 'b'], ['c', 'd']]aussehen, und eine einzelne Spalte mit drei Zeilen wäre [['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

Tabellenbindung : Bindet an einen Dokumentbereich, der eine Tabelle mit Kopfzeilen enthält.

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

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

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 Methoden getDataAsync und setDataAsync vom -Objekt für die Binding Interaktion mit gebundenen Daten.

Erstellen einer Bindung aus der aktuellen Auswahl

Im folgenden Beispiel wird der aktuellen Auswahl mithilfe der addFromSelectionAsync-Methode eine Textbindung namens hinzugefügtmyBinding.

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 für die Auswahl erstellt wird. Unterschiedliche Bindungstypen machen unterschiedliche Daten und Vorgänge verfügbar. Office.BindingType ist eine Enumeration der verfügbaren 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 Erstellung der Bindung abgeschlossen ist. Die Funktion empfängt einen einzelnen Parameter, asyncResult, der Zugriff auf ein AsyncResult-Objekt mit dem status des Aufrufs ermöglicht. 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 mithilfe der addFromPromptAsync-Methode eine Textbindung namens myBinding hinzu. Mit dieser Methode können Benutzer den Bereich für die Bindung mithilfe der integrierten 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 eine TextBinding für die Auswahl des Benutzers in der Eingabeaufforderung erstellt wird.

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

Die anonyme Funktion, die als dritter Rückrufparameter übergeben wird, wird ausgeführt, wenn die Erstellung der Bindung abgeschlossen ist. Wenn die Rückruffunktion ausgeführt wird, enthält das AsyncResult-Objekt die status des Aufrufs und die neu erstellte Bindung.

Der folgende Screenshot zeigt die integrierte Eingabeaufforderung zur 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 der Bindung 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 von addFromNamedItemAsync auf einen vorhandenen benannten Bereich, einen Bereich, der mit der A1-Verweisformatvorlage ("A1:A3") angegeben ist, oder auf eine Tabelle. Standardmäßig weist Excel die Namen "Table1" für die erste Tabelle, "Table2" für die zweite Tabelle usw. zu. Um einer Tabelle in der Excel-Benutzeroberfläche einen aussagekräftigen Namen zuzuweisen, verwenden Sie die Eigenschaft Tabellenname in den 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 Stadtnamen 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; 
}

Für Word verweist der itemName Parameter von 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. Wenn Sie einen aussagekräftigen Namen in der Word Ui zuweisen möchten, 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 eine Textbindung in Word an ein Rich-Text-Inhaltssteuerelement namens "FirstName", weist die ID"firstName" zu und zeigt dann diese Informationen 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 anonyme Funktion, die übergeben wird, wenn der callback Parameter ausgeführt wird, wenn der Vorgang abgeschlossen ist. 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 mithilfe von getByIdAsync

Im folgenden Beispiel wird die getByIdAsync-Methode verwendet, um eine Bindung in einem Dokument abzurufen, indem ihre 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 anonyme Funktion, die übergeben wird, wenn der zweite Rückrufparameter ausgeführt wird, wenn der Vorgang abgeschlossen ist. Die Funktion wird mit einem einzelnen Parameter, asyncResult, aufgerufen, der die status des Aufrufs und die Bindung mit der ID "myBinding" enthält.

Abrufen einer Bindung nach ID mithilfe von Office.select

Im folgenden Beispiel wird die Office.select-Funktion verwendet, um eine Binding-Objektzusage in einem Dokument abzurufen, indem ihre 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, der nicht die vier Methoden ist, die von der Binding-Objektzusage bereitgestellt werden, die von der select Funktion zurückgegeben wird, 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 ihrer 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 bindung, die freigegeben werden soll.

Die anonyme Funktion, die als zweiter Parameter übergeben wird, ist ein Rückruf, der nach Abschluss des Vorgangs ausgeführt wird. Die Funktion wird mit einem einzelnen Parameter aufgerufen, asyncResult, der die 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 anhand ihrer ID auf die Bindung zuzugreifen und den Aufruf der getDataAsync-Methode wie folgt zu starten:

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

Die anonyme Funktion, die an die -Methode übergeben wird, ist ein Rückruf, der nach Abschluss des Vorgangs ausgeführt wird. 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 für myBindingfestgelegt werden soll. Da es sich dabei um eine Textbindung handelt, ist der Wert vom Typ string. Unterschiedliche Bindungstypen akzeptieren unterschiedliche Datentypen.

Die anonyme Funktion, die an die -Methode übergeben wird, ist ein Rückruf, der nach Abschluss des Vorgangs ausgeführt wird. Die Funktion wird mit einem einzelnen Parameter aufgerufen, asyncResultder die status des Ergebnisses enthält.

Erkennen von Änderungen an Daten oder auswahl 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 zur Zeichenfolge "bindingDataChanged" ausgewertet.

Die dataChanged als zweiter Handlerparameter übergebene Funktion 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, indem Sie den Ereignistyp als ersten eventType-Parameter und den Namen der zu entfernenden Ereignishandlerfunktion als zweiten Handlerparameter übergeben. Die folgende Funktion entfernt z. B. die dataChanged Ereignishandlerfunktion, die 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