Einrichten einer Bindung an Regionen in einem Dokument oder ArbeitsblattBind to regions in a document or spreadsheet

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. Nach der Herstellung der Bindung kann das Add-In den bereitgestellten Bezeichner verwenden, um auf die Daten in dem zugeordneten Bereich des Dokuments oder der Tabelle zuzugreifen. Durch das Erstellen von Bindungen ergeben sich für das Add-In die folgenden Vorteile:Binding-based data access enables content and task pane add-ins to consistently access a particular region of a document or spreadsheet through an identifier. The add-in first needs to establish the binding by calling one of the methods that associates a portion of the document with a unique identifier: addFromPromptAsync, addFromSelectionAsync, or addFromNamedItemAsync. After the binding is established, the add-in can use the provided identifier to access the data contained in the associated region of the document or spreadsheet. Creating bindings provides the following value to your add-in:

  • Zugriff auf allgemeine Datenstrukturen in allen unterstützten Office-Anwendungen, z. B. Tabellen, Bereiche oder Text (eine fortlaufende Folge von Zeichen).Permits access to common data structures across supported Office applications, such as: tables, ranges, or text (a contiguous run of characters).

  • Lese-/Schreibzugriffvorgänge, ohne dass der Benutzer eine Auswahl vornehmen mussEnables read/write operations without requiring the user to make a selection.

  • 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.Establishes a relationship between the add-in and the data in the document. Bindings are persisted in the document, and can be accessed at a later time.

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.Establishing a binding also allows you to subscribe to data and selection change events that are scoped to that particular region of the document or spreadsheet. This means that the add-in is only notified of changes that happen within the bound region as opposed to general changes across the whole document or spreadsheet.

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 die einzelnen Bindungen kann über ihre ID unter Verwendung der Bindings.[getBindingByIdAsync]- oder der Office.select-Methode zugegriffen werden. Mithilfe einer der folgenden Methoden des Bindings-Objekts können neue Bindungen hergestellt und vorhandene entfernt werden: addFromSelectionAsync, addFromPromptAsync, addFromNamedItemAsync oder releaseByIdAsync.The Bindings object exposes a getAllAsync method that gives access to the set of all bindings established on the document or spreadsheet. An individual binding can be accessed by its ID using either the Bindings.getByIdAsync or Office.select methods. You can establish new bindings as well as remove existing ones by using one of the following methods of the Bindings object: addFromSelectionAsync, addFromPromptAsync, addFromNamedItemAsync, or releaseByIdAsync.

BindungstypenBinding types

Es gibt [drei unterschiedliche Arten von Bindungen] Office.BindingType, die Sie mit dem bindingType-Parameter angeben, wenn Sie eine Bindung mithilfe der Methode addFromSelectionAsync, addFromPromptAsync oder addFromNamedItemAsync erstellen:There are three different types of bindings that you specify with the bindingType parameter when you create a binding with the addFromSelectionAsync, addFromPromptAsync or addFromNamedItemAsync methods:

  1. Text Binding – Bindet einen Bereich des Dokuments, der als Text dargestellt werden kann.Text Binding - Binds to a region of the document that can be represented as text.

    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.In Word, most contiguous selections are valid, while in Excel only single cell selections can be the target of a text binding. In Excel, only plain text is supported. In Word, three formats are supported: plain text, HTML, and Open XML for Office.

  2. Matrix Binding – Bindet einen festen Bereich eines Dokuments, der tabellarische Daten ohne Kopfzeilen enthält. Daten in einer Matrixbindung werden als zweidimensionales Array-Objekt geschrieben bzw. gelesen, das in JavaScript als ein Array von Arrays implementiert wird. Beispielsweise können zwei Zeilen mit string-Werten in zwei Spalten als [['a', 'b'], ['c', 'd']] gelesen oder geschrieben werden, und eine einzelne Spalte mit drei Zeilen kann als [['a'], ['b'], ['c']] gelesen oder geschrieben werden.Matrix Binding - Binds to a fixed region of a document that contains tabular data without headers.Data in a matrix binding is written or read as a two dimensional Array, which in JavaScript is implemented as an array of arrays. For example, two rows of string values in two columns can be written or read as [['a', 'b'], ['c', 'd']], and a single column of three rows can be written or read as [['a'], ['b'], ['c']].

    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.In Excel, any contiguous selection of cells can be used to establish a matrix binding. In Word, only tables support matrix binding.

  3. Table Binding – Bindet 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 stellt die Daten über die Eigenschaften headers und rows zur Verfügung.Table Binding - Binds to a region of a document that contains a table with headers.Data in a table binding is written or read as a TableData object. The TableData object exposes the data through the headers and rows properties.

    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.Any Excel or Word table can be the basis for a table binding. After you establish a table binding, each new row or column a user adds to the table is automatically included in the binding.

Nachdem eine Bindung mithilfe einer der drei „addFrom“-Methoden des Bindings-Objekts erstellt wurde, können Sie mit den Daten und Eigenschaften der Bindung mithilfe der Methoden des entsprechenden Objekts arbeiten: 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.After a binding is created by using one of the three "addFrom" methods of the Bindings object, you can work with the binding's data and properties by using the methods of the corresponding object: MatrixBinding, TableBinding, or TextBinding. All three of these objects inherit the getDataAsync and setDataAsync methods of the Binding object that enable you to interact with the bound data.

Hinweis

Wann sollten Matrixbindungen 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.When should you use matrix versus table bindings? When the tabular data you are working with contains a total row, you must use a matrix binding if your add-in's script needs to access values in the total row or detect that the user's selection is in the total row. If you establish a table binding for tabular data that contains a total row, the TableBinding.rowCount property and the rowCount and startRow properties of the BindingSelectionChangedEventArgs object in event handlers won't reflect the total row in their values. To work around this limitation, you must use establish a matrix binding to work with the total row.

Hinzufügen einer Bindung zur aktuellen Auswahl des BenutzersAdd a binding to the user's current selection

Im folgenden Beispiel wird das Hinzufügen einer Textbindung namens myBinding zur aktuellen Auswahl in einem Dokument unter Verwendung der addFromSelectionAsync-Methode erläutert.The following example shows how to add a text binding called myBinding to the current selection in a document by using the addFromSelectionAsync method.

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.In this example, the specified binding type is text. This means that a TextBinding will be created for the selection. Different binding types expose different data and operations. Office.BindingType is an enumeration of available binding type values.

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.The second optional parameter is an object that specifies the ID of the new binding being created. If an ID is not specified, one is generated automatically.

Die anonyme Funktion, die als letzter callback-Parameter an die Funktion ü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.The anonymous function that is passed into the function as the final callback parameter is executed when the creation of the binding is complete. The function is called with a single parameter, asyncResult, which provides access to an AsyncResult object that provides the status of the call. The AsyncResult.value property contains a reference to a Binding object of the type that is specified for the newly created binding. You can use this Binding object to get and set data.

Hinzufügen einer Bindung von einer EingabeaufforderungAdd a binding from a prompt

Im folgenden Beispiel wird das Hinzufügen einer Textbindung namens myBinding mithilfe der Methode addFromPromptAsync erläutert. 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.The following example shows how to add a text binding called myBinding by using the addFromPromptAsync method. This method lets the user specify the range for the binding by using the application's built-in range selection prompt.

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.In this example, the specified binding type is text. This means that a TextBinding will be created for the selection that the user specifies in the prompt.

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.The second parameter is an object that contains the ID of the new binding being created. If an ID is not specified, one is generated automatically.

Die anonyme Funktion, die als dritter callback-Parameter in die Funktion ü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.The anonymous function passed into the function as the third callback parameter is executed when the creation of the binding is complete. When the callback function executes, the AsyncResult object contains the status of the call and the newly created binding.

Abbildung 1 zeigt die integrierte Eingabeaufforderung für die Bereichsauswahl in Excel.Figure 1 shows the built-in range selection prompt in Excel.

Abbildung 1: Datenauswahlfenster in ExcelFigure 1. Excel Select Data UI

Datenauswahlfenster in Excel

Hinzufügen einer Bindung zu einem benannten ElementAdd a binding to a named item

Das folgende Beispiel veranschaulicht das Hinzufügen einer Bindung zu dem vorhandenen benannten Element myRange als Matrixbindung unter Verwendung der addFromNamedItemAsync-Methode sowie das Zuweisen der id der Bindung als "myMatrix".The following example shows how to add a binding to the existing myRange named item as a "matrix" binding by using the addFromNamedItemAsync method, and assigns the binding's id as "myMatrix".

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 im A1-Verweisstil ("A1:A3") angegebenen Bereich oder eine Tabelle verweisen. 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 über die Excel-Benutzeroberfläche einen aussagefähigen Namen zuzuweisen, verwenden Sie die Eigenschaft Tabellenname auf der Registerkarte Tabellentools | Entwurf im Menüband.For Excel, the itemName parameter of the addFromNamedItemAsync method can refer to an existing named range, a range specified with the A1 reference style ("A1:A3"), or a table. By default, adding a table in Excel assigns the name "Table1" for the first table you add, "Table2" for the second table you add, and so on. To assign a meaningful name for a table in the Excel UI, use the Table Name property on the Table Tools | Design tab of the ribbon.

Hinweis

Wenn Sie in Excel eine Tabelle als benanntes Element festlegen, muss der Name vollständig qualifiziert werden, um den Arbeitsblattnamen im folgenden Format in den Tabellennamen einzufügen: "Sheet1!Table1"In Excel, when specifying a table as a named item, you must fully qualify the name to include the worksheet name in the name of the table in this format: "Sheet1!Table1"

Im folgenden Beispiel wird in Excel eine Bindung zu den ersten drei Zellen in Spalte A ( "A1:A3") erstellt und die id "MyCities" zugewiesen. Anschließend werden drei Städtenamen in diese Bindung geschrieben.The following example creates a binding in Excel to the first three cells in column A ( "A1:A3"), assigns the id "MyCities", and then writes three city names to that binding.

 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 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.)For Word, the itemName parameter of the addFromNamedItemAsync method refers to the Title property of a Rich Text content control. (You can't bind to content controls other than the Rich Text content control.)

Standardmäßig ist einem Inhaltssteuerelement kein Title*-Wert zugewiesen Um über die Word-Benutzeroberfläche einen aussagefähigen Namen zuzuweisen, nachdem Sie über die Gruppe Steuerelemente auf der Registerkarte Entwickler im Menüband ein Rich Text-Inhaltssteuerelement hinzugefügt haben, verwenden Sie den Befehl Eigenschaften in der Gruppe Steuerelemente. Das Dialogfeld Eigenschaften von Inhaltssteuerelementen wird geöffnet. Anschließend legen Sie für die Title-Eigenschaft des Inhaltssteuerelements den Namen fest, auf den Sie von Ihrem Code verweisen möchten.By default, a content control has no Title*value assigned. 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. Then set the Title property of the content control to the name you want to reference from your code.

Im folgenden Beispiel wird in Word eine Textbindung zu einem Rich-Text-Inhaltsteuerelement mit dem Namen "FirstName" erstellt und die id"firstName" zugewiesen. Anschließend werden diese Informationen angezeigt.The following example creates a text binding in Word to a rich text content control named "FirstName", assigns the id "firstName", and then displays that information.

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 BindungenGet all bindings

Im folgenden Beispiel wird erläutert, wie Sie mithilfe der Bindings.getAllAsync-Methode alle Bindungen in einem Dokument abrufen.The following example shows how to get all bindings in a document by using the Bindings.getAllAsync method.

Office.context.document.bindings.getAllAsync(function (asyncResult) {
    var bindingString = '';
    for (var 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 als callback-Parameter an die Funktion übergeben wird, wird ausgeführt, wenn der Vorgang abgeschlossen ist. Die Funktion wird mit einem einzigen Parameter aufgerufen, asyncResult, der ein Array der Bindungen in dem 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.The anonymous function that is passed into the function as the callback parameter is executed when the operation is complete. The function is called with a single parameter, asyncResult, which contains an array of the bindings in the document. The array is iterated to build a string that contains the IDs of the bindings. The string is then displayed in a message box.

Abrufen einer Bindung nach ID unter Verwendung der "getByIdAsync"-Methode des "Bindings"-ObjektsGet a binding by ID using the getByIdAsync method of the Bindings object

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.The following example shows how to use the getByIdAsync method to get a binding in a document by specifying its ID. This example assumes that a binding named 'myBinding' was added to the document using one of the methods described earlier in this topic.

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 dem Beispiel ist der erste id-Parameter die ID der abzurufenden Bindung.In the example, the first id parameter is the ID of the binding to retrieve.

Die anonyme Funktion, die als zweiter callback-Parameter in die Funktion ü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.The anonymous function that is passed into the function as the second callback parameter is executed when the operation is completed. The function is called with a single parameter, asyncResult, which contains the status of the call and the binding with the ID "myBinding".

Abrufen einer Bindung nach ID, unter Verwendung der "select"-Methode des "Office"-ObjektsGet a binding by ID using the select method of the Office object

Das folgende Beispiel veranschaulicht die Verwendung der Office.select-Methode, um ein Binding-Objektzusicherung in einem Dokument abzurufen, indem ihre ID in einer Auswahlzeichenfolge 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.The following example shows how to use the Office.select method to get a Binding object promise in a document by specifying its ID in a selector string. It then calls the Binding.getDataAsync method to get data from the specified binding. This example assumes that a binding named 'myBinding' was added to the document using one of the methods described earlier in this topic.

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-Methode 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 Zusicherung kein Binding-Objekt zurückgeben kann, kann der onError-Rückruf verwendet werden, um auf ein asyncResult.error-Objekt zuzugreifen und weitere Informationen abzurufen. Wenn Sie ein anderes Element des Binding-Objekts aufrufen müssen als die vier von der Binding-Objektzusicherung verfügbar gemachten, die von der select-Methode zurückgegeben wurden, verwenden Sie stattdessen die getByIdAsync-Methode, indem Sie die Document.bindings-Eigenschaft und die Bindings.getByIdAsync-Methode zum Abrufen des Binding**-Objekts verwenden.If the select method promise successfully returns a Binding object, that object exposes only the following four methods of the object: getDataAsync, setDataAsync, addHandlerAsync, and removeHandlerAsync. If the promise cannot return a Binding object, the onError callback can be used to access an asyncResult.error object to get more information.If you need to call a member of the Binding object other than the four methods exposed by the Binding object promise returned by the select method, instead use the getByIdAsync method by using the Document.bindings property and Bindings.getByIdAsync method to retrieve the Binding** object.

Freigeben einer Bindung nach IDRelease a binding by ID

Das folgende Beispiel veranschaulicht die Verwendung der releaseByIdAsync-Methode, um eine Bindung in einem Dokument durch die Angabe ihrer ID freizugeben.The following example shows how use the releaseByIdAsync method to release a binding in a document by specifying its ID.

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.In the example, the first id parameter is the ID of the binding to release.

Die anonyme Funktion, die als zweiter Parameter in die Funktion übergeben wird, ist ein Rückruf, der beim Abschluss des Vorgangs ausgeführt wird. Die Funktion wird mit einem einzigen Parameter, asyncResult, aufgerufen, der den Status des Aufrufs enthält.The anonymous function that is passed into the function as the second parameter is a callback that is executed when the operation is complete. The function is called with a single parameter, asyncResult, which contains the status of the call.

Lesen von Daten aus einer BindungRead data from a binding

Das folgende Beispiel verdeutlicht die Verwendung der getDataAsync-Methode, um Daten aus einer vorhandenen Bindung abzurufen.The following example shows how to use the getDataAsync method to get data from an existing binding.

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:myBinding is a variable that contains an existing text binding in the document. Alternatively, you could use the Office.select to access the binding by its ID, and start your call to the getDataAsync method, like this:

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

Die anonyme Funktion, die an die Funktion ü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.The anonymous function that is passed into the function is a callback that is executed when the operation is complete. The AsyncResult.value property contains the data within myBinding. The type of the value depends on the binding type. The binding in this example is a text binding. Therefore, the value will contain a string. For additional examples of working with matrix and table bindings, see the getDataAsync method topic.

Schreiben von Daten in eine BindungWrite data to a binding

Das folgende Beispiel veranschaulicht die Verwendung der setDataAsync-Methode, um Daten in einer vorhandenen Bindung festzulegen.The following example shows how to use the setDataAsync method to set data in an existing binding.

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

myBinding ist eine Variable, die eine vorhandene Textbindung in dem Dokument enthält.myBinding is a variable that contains an existing text binding in the document.

Im Beispiel ist der erste Parameter der für myBinding festzulegende Wert. Da es sich dabei um eine Textbindung handelt, ist der Wert vom Typ string. Unterschiedliche Bindungstypen akzeptieren unterschiedliche Datentypen.In the example, the first parameter is the value to set on myBinding. Because this is a text binding, the value is a string. Different binding types accept different types of data.

Die anonyme Funktion, die an die Funktion übergeben wird, ist ein Rückruf, der nach Abschluss des Vorgangs ausgeführt wird. Die Funktion wird mit einem einzigen Parameter aufgerufen, asyncResult, der den Status des Ergebnisses enthält.The anonymous function that is passed into the function is a callback that is executed when the operation is complete. The function is called with a single parameter, asyncResult, which contains the status of the result.

Hinweis

Ab dieser Version von Excel 2013 SP1 und der entsprechenden Version von Microsoft Excel im Web können Sie nun die Formatierung festlegen, wenn Sie Daten in gebundenen Tabellen verfassen und aktualisieren.Starting with the release of the Excel 2013 SP1 and the corresponding build of Excel Online, you can now set formatting when writing and updating data in bound tables.

Erkennen von Änderungen an Daten oder der Auswahl in einer BindungDetect changes to data or the selection in a binding

Das folgende Beispiel veranschaulicht das Anhängen eines Ereignishandlers an das DataChanged-Ereignis einer Bindung mit der ID „MyBinding“.The following example shows how to attach an event handler to the DataChanged event of a binding with an id of "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.The myBinding is a variable that contains an existing text binding in the document.

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 evaluates to the stringbindingDataChanged“.The first eventType parameter of the addHandlerAsync method specifies the name of the event to subscribe to. Office.EventType is an enumeration of available event type values. Office.EventType.BindingDataChanged evaluates to the string"bindingDataChanged"`.

Die dataChanged-Funktion, die als zweiter handler-Parameter in die Funktion übergeben wird, ist ein Ereignishandler, der ausgeführt wird, wenn sich die Daten in der Bindung ändern. 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.The dataChanged function that is passed into the function as the second handler parameter is an event handler that is executed when the data in the binding is changed. The function is called with a single parameter, eventArgs, which contains a reference to the binding. This binding can be used to retrieve the updated data.

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.Similarly, you can detect when a user changes selection in a binding by attaching an event handler to the SelectionChanged event of a binding. To do that, specify the eventType parameter of the addHandlerAsync method as Office.EventType.BindingSelectionChanged or "bindingSelectionChanged".

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.You can add multiple event handlers for a given event by calling the addHandlerAsync method again and passing in an additional event handler function for the handler parameter. This will work correctly as long as the name of each event handler function is unique.

Entfernen eines EreignishandlersRemove an event handler

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.To remove an event handler for an event, call the removeHandlerAsync method passing in the event type as the first eventType parameter, and the name of the event handler function to remove as the second handler parameter. For example, the following function will remove the dataChanged event handler function added in the previous section's example.

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

Wichtig

Wenn der optionale handler-Parameter beim Aufrufen der removeHandlerAsync-Methode weggelassen wird, werden alle Ereignishandler für das angegebene eventType-Objekt entfernt.If the optional handler parameter is omitted when the removeHandlerAsync method is called, all event handlers for the specified eventType will be removed.

Weitere ArtikelSee also