Einrichten einer Bindung an Regionen in einem Dokument oder Arbeitsblatt

  • Artikel

Bindungsbasierter Datenzugriff ermöglicht Inhalts- und Aufgabenbereich-Add-Ins den konsistenten Zugriff auf einen bestimmten Bereich eines Dokuments oder einer Tabelle mithilfe eines Bezeichners. Das Add-In muss zunächst eine Bindung herstellen, indem es eine der Methoden aufruft, die einen Teil des Dokuments einem eindeutigen Bezeichner zuordnet: addFromPromptAsync, addFromSelectionAsync oder addFromNamedItemAsync. Nachdem die Bindung eingerichtet wurde, kann das Add-in über die bereitgestellte ID auf die Daten im zugeordneten Bereich des Dokuments oder Arbeitsblatts zugreifen. Das Erstellen von Bindungen bietet dem Add-In den folgenden Wert.

  • Zugriff auf allgemeine Datenstrukturen in allen unterstützten Office-Anwendungen, z. B. Tabellen, Bereiche oder Text (eine fortlaufende Folge von Zeichen).
  • Lese-/Schreibzugriffvorgänge, ohne dass der Benutzer eine Auswahl vornehmen muss
  • Herstellung einer Beziehung zwischen dem Add-In und den Daten im Dokument. Bindungen bleiben im Dokument erhalten, und es kann zu einem späteren Zeitpunkt auf diese zugegriffen werden.

Die Herstellung einer Bindung ermöglicht auch das Abonnieren von Daten- und Auswahländerungsereignissen in diesem bestimmten Bereich des Dokuments oder der Tabelle. Dies bedeutet, dass das Add-in nur von Änderungen benachrichtigt wird, die in dem gebundenen Bereich stattfinden und nicht von solchen, innerhalb des gesamten Dokuments oder der gesamten Tabelle.

Das Bindings-Objekt macht eine getAllAsync-Methode verfügbar, die den Zugriff auf alle in dem Dokument oder in der Tabelle hergestellten Bindungen ermöglicht. Auf eine einzelne Bindung kann über ihre ID über die Bindungen zugegriffen werden. getByIdAsync-Methode oder Office.select-Funktion . Mithilfe einer der folgenden Methoden des Bindings-Objekts können neue Bindungen hergestellt und vorhandene entfernt werden: addFromSelectionAsync, addFromPromptAsync, addFromNamedItemAsync oder releaseByIdAsync.

Bindungstypen

Es gibt drei verschiedene Typen von Bindungen , die Sie mit dem bindingType-Parameter angeben, wenn Sie eine Bindung mit den Methoden addFromSelectionAsync, addFromPromptAsync oder addFromNamedItemAsync erstellen.

  1. Textbindung : Bindet an einen Bereich des Dokuments, der als Text dargestellt werden kann.

    In Word sind die meisten zusammenhängenden Auswahlen gültig, während in Excel nur Auswahlen mit einer Zelle das Ziel einer Textbindung sein können. In Excel wird nur unformatierter Text unterstützt. Word unterstützt drei Formate: Nur-Text, HTML und Open XML für Office.

  2. Matrixbindung : Bindet an einen festen Bereich eines Dokuments, der tabellarische Daten ohne Kopfzeilen enthält. Daten in einer Matrixbindung werden als zweidimensionales Array geschrieben oder gelesen, das in JavaScript als Array von Arrays implementiert wird. Beispielsweise können zwei Zeilen mit Zeichenfolgenwerten in zwei Spalten als [['a', 'b'], ['c', 'd']]geschrieben oder gelesen werden, und eine einzelne Spalte mit drei Zeilen kann als [['a'], ['b'], ['c']]geschrieben oder gelesen werden.

    In Excel kann eine beliebige Auswahl benachbarter Zellen für die Herstellung einer Matrixbindung verwendet werden. In Word wird die Matrixbindung nur für Tabellen unterstützt.

  3. Tabellenbindung : Bindet an einen Bereich eines Dokuments, der eine Tabelle mit Kopfzeilen enthält. Daten in einer Tabellenbindung werden als TableData-Objekt geschrieben oder gelesen. Das TableData -Objekt macht die Daten über die headers Eigenschaften und rows verfügbar.

    Jede Excel- oder Word-Tabelle kann die Basis einer Tabellenbindung sein. Nach Herstellen einer Tabellenbindung wird jede neue Zeile oder Spalte, die Benutzer der Tabelle hinzugefügt haben, automatisch in die Bindung einbezogen.

Nachdem eine Bindung mit einer der drei "addFrom"-Methoden des Bindings Objekts erstellt wurde, können Sie mit den Daten und Eigenschaften der Bindung arbeiten, indem Sie die Methoden des entsprechenden Objekts verwenden: MatrixBinding, TableBinding oder TextBinding. Diese drei Objekte erben die Methoden getDataAsyncund setDataAsync des Binding-Objekts, die Ihnen die Interaktion mit den gebundenen Daten ermöglichen.

Hinweis

Wann sollten Matrix- und wann Tabellenbindungen verwendet werden? Wenn die tabellarischen Daten, mit denen Sie arbeiten, eine Ergebniszeile enthalten, müssen Sie eine Matrixbindung verwenden, falls das Skript Ihres Add-Ins auf Werte in der Ergebniszeile zugreifen oder erkennen muss, dass sich die Auswahl des Benutzers in der Ergebniszeile befindet. Wenn Sie eine Tabellenbindung für tabellarische Daten herstellen, die eine Ergebniszeile enthalten, spiegeln die Eigenschaft TableBinding.rowCount sowie die Eigenschaften rowCount und startRow des BindingSelectionChangedEventArgs-Objekts in Ereignishandlern mit ihren Werten nicht die Ergebniszeile wider. Um diese Einschränkung zu umgehen und mit der Ergebniszeile zu arbeiten, müssen Sie eine Matrixbindung herstellen.

Hinzufügen einer Bindung zur aktuellen Auswahl des Benutzers

Im folgenden Beispiel wird gezeigt, wie Sie eine Textbindung namens myBinding zur aktuellen Auswahl in einem Dokument mithilfe der addFromSelectionAsync-Methode hinzufügen.

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 festgelegte Bindungstyp „Text“. Dies bedeutet, dass für die Auswahl ein TextBinding-Objekt erstellt wird. Unterschiedliche Bindungstypen machen unterschiedliche Daten und Vorgänge verfügbar. Office.BindingType ist eine Enumeration verfügbarer Bindungstypwerte.

Der zweite optionale Parameter ist ein Objekt, das die ID der neu zu erstellenden Bindung festlegt. Wenn keine ID festgelegt wird, wird diese automatisch generiert.

Die anonyme Funktion, die als letzter Rückrufparameter an die -Methode übergeben wird, wird ausgeführt, wenn die Erstellung der Bindung abgeschlossen ist. Die Funktion wird mit einem einzigen Parameter, asyncResult, aufgerufen, der den Zugriff auf ein AsyncResult-Objekt ermöglicht, das den Status des Aufrufs enthält. Die AsyncResult.value-Eigenschaft enthält einen Verweis auf ein Binding-Objekt des Typs, der für die neu erstellte Bindung angegeben ist. Sie können dieses Binding-Objekt verwenden, um Daten abzurufen und festzulegen.

Hinzufügen einer Bindung von einer Eingabeaufforderung

Im folgenden Beispiel wird gezeigt, wie eine Textbindung mit dem Namen myBinding mithilfe der addFromPromptAsync-Methode hinzugefügt wird. Diese Methode ermöglicht dem Benutzer das Festlegen des Bereichs für die Bindung, indem die in die Anwendung integrierte Eingabeaufforderung für die Bereichsauswahl verwendet wird.

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 festgelegte Bindungstyp „Text“. Dies bedeutet, dass für die von dem Benutzer in der Eingabeaufforderung angegebene Auswahl ein TextBinding-Objekt erstellt wird.

Der zweite Parameter ist ein Objekt, das die ID der neu zu erstellenden Bindung enthält. Wenn keine ID festgelegt wird, wird diese automatisch generiert.

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

Abbildung 1 zeigt die integrierte Eingabeaufforderung für die Bereichsauswahl in Excel.

Abbildung 1: Datenauswahlfenster in Excel

Das Dialogfeld Daten auswählen.

Hinzufügen einer Bindung zu einem benannten Element

Im folgenden Beispiel wird gezeigt, wie Sie dem vorhandenen myRange benannten Element mithilfe der addFromNamedItemAsync-Methode eine Bindung als Matrixbindung hinzufügen und die der Bindung id als "myMatrix" zuweisen.

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 kann der itemName Parameter der addFromNamedItemAsync-Methode auf einen vorhandenen benannten Bereich, einen bereich verweisen, der mit dem A1 Verweisformat ("A1:A3")angegeben wird, oder auf eine Tabelle. Standardmäßig wird in Excel der ersten hinzugefügten Tabelle der Name "Tabelle1" und der zweiten hinzugefügten Tabelle der Name "Tabelle2" zugewiesen und so weiter. Um einer Tabelle in der Excel-Benutzeroberfläche einen aussagekräftigen Namen zuzuweisen, verwenden Sie die Table Name -Eigenschaft in den Tabellentools | Registerkarte "Entwurf" des Menübands.

Hinweis

Wenn Sie in Excel eine Tabelle als benanntes Element angeben, müssen Sie den Namen vollständig qualifizieren, um den Arbeitsblattnamen in den Namen der Tabelle in diesem Format einzuschließen: "Sheet1!Table1"

Im folgenden Beispiel wird eine Bindung in Excel an die ersten drei Zellen in Spalte A ( "A1:A3") erstellt, die id "MyCities"zugewiesen und dann drei Stadtnamen in diese Bindung geschrieben.

 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 der addFromNamedItemAsync-Methode 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. To assign a meaningful name in the Word UI, after inserting a Rich Text content control from the Controls group on the Developer tab of the ribbon, use the Properties command in the Controls group to display the Content Control Properties dialog box. Legen Sie dann die Title -Eigenschaft des Inhaltssteuerelements auf den Namen fest, auf den Sie im Code verweisen möchten.

Im folgenden Beispiel wird eine Textbindung in Word an ein Rich-Text-Inhaltssteuerelement namens "FirstName"erstellt, die ID"firstName" zugewiesen und dann diese Informationen angezeigt.

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 wird erläutert, wie Sie mithilfe der Bindings.getAllAsync-Methode alle Bindungen in einem Dokument abrufen.

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 an die Methode ü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 unter Verwendung der "getByIdAsync"-Methode des "Bindings"-Objekts

Das folgende Beispiel veranschaulicht die Verwendung der getByIdAsync-Methode, um eine Bindung in einem Dokument durch die Angabe ihrer ID abzurufen. In diesem Beispiel wird davon ausgegangen, dass dem Dokument mithilfe einer der in diesem Thema bereits erläuterten Methoden eine Bindung namens '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; 
}

Im Beispiel ist der erste id Parameter die ID der abzurufenden Bindung.

Die anonyme Funktion, die als zweiter Rückrufparameter an die -Methode übergeben wird, wird ausgeführt, wenn der Vorgang abgeschlossen ist. Die Funktion wird mit einem einzigen Parameter, asyncResult, aufgerufen, der den Status des Aufrufs und die Bindung mit der ID "myBinding" enthält.

Abrufen einer Bindung nach ID mithilfe der Select-Funktion des Office-Objekts

Im folgenden Beispiel wird gezeigt, wie die Office.select-Funktion verwendet wird, um eine Binding-Objektzusage in einem Dokument abzurufen, indem die ZUGEHÖRIGE ID in einer Selektorzeichenfolge angegeben wird. Diese ruft anschließend die Binding.getDataAsync-Methode auf, um die Daten von der angegebenen Bindung abzurufen. In diesem Beispiel wird davon ausgegangen, dass dem Dokument mithilfe einer der in diesem Thema bereits erläuterten Methoden eine Bindung namens '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; 
}

Hinweis

Wenn die select Funktionszusage erfolgreich ein Binding-Objekt zurückgibt, macht dieses Objekt nur die folgenden vier Methoden des Objekts 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 Anderen Member des Binding-Objekts als die vier Methoden aufrufen müssen, die von der Von der select Funktion zurückgegebenen Binding-Objektzusage verfügbar gemacht werden, verwenden Sie stattdessen die getByIdAsync-Methode mithilfe der Document.bindings-Eigenschaft und Bindungen. getByIdAsync-Methode zum Abrufen des Binding-Objekts .

Freigeben einer Bindung nach ID

Das folgende Beispiel veranschaulicht die Verwendung der releaseByIdAsync-Methode, um eine Bindung in einem Dokument durch die 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 dem Beispiel ist der erste id-Parameter die ID der freizugebenden Bindung.

Die anonyme Funktion, die als zweiter Parameter 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, asyncResult, der die status des Aufrufs enthält.

Lesen von Daten aus einer Bindung

Das folgende Beispiel verdeutlicht die Verwendung der getDataAsync-Methode, 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 auf die Bindung über deren ID zuzugreifen, und den Aufruf zur getDataAsync-Methode folgendermaßen 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. Daher enthält der Wert eine Zeichenfolge. Weitere Beispiele zum Arbeiten mit Matrix- und Tabellenbindungen finden Sie im Thema zur getDataAsync-Methode.

Schreiben von Daten in eine Bindung

Das folgende Beispiel veranschaulicht die Verwendung der setDataAsync-Methode, 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.

Im 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 der Auswahl in einer Bindung

Das folgende Beispiel veranschaulicht das Anhängen eines Ereignishandlers an das DataChanged-Ereignis einer Bindung mit der ID „MyBinding“.

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 der addHandlerAsync-Methode 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 Funktion, die als zweiter Handlerparameter an die -Methode ü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 zu diesem Zweck den eventType-Parameter der addHandlerAsync-Methode als Office.EventType.BindingSelectionChanged oder "bindingSelectionChanged" an.

Sie können einem bestimmten Ereignis mehrere Ereignishandler hinzufügen, indem Sie erneut die addHandlerAsync-Methode aufrufen und eine zusätzliche Ereignishandlerfunktion für den handler-Parameter übergeben. Dies funktioniert ordnungsgemäß, solange der Name jeder Ereignishandlerfunktion eindeutig ist.

Entfernen eines Ereignishandlers

Um einen Ereignishandler für ein Ereignis zu entfernen, rufen Sie die removeHandlerAsync-Methode auf, indem Sie den Ereignistyp als ersten eventType-Parameter übergeben und den Namen der zu entfernenden Ereignishandlerfunktion als zweiten handler-Parameter. Beispielsweise wird mit der folgenden Funktion die im Beispiel des vorherigen Abschnitts hinzugefügte Ereignishandlerfunktion dataChanged entfernt.

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

Wichtig

Wenn der optionale Handlerparameter beim Aufruf der removeHandlerAsync-Methode weggelassen wird, werden alle Ereignishandler für den angegebenen eventType entfernt.

Siehe auch