Asynchrone Programmierung in Office-Add-InsAsynchronous programming in Office Add-ins

Wichtig

Dieser Artikel bezieht sich auf die gängigen APIs, das Office-JavaScript-API-Modell, das von Office 2013 und höher unterstützt wird.This article applies to the Common APIs, the Office JavaScript API model that's supported by Office 2013 and later. Diese APIs umfassen Features wie UI, Dialogfelder und Clienteinstellungen, die in mehreren Typen von Office-Anwendungen gemeinsam sind.These APIs include features such as UI, dialogs, and client settings that are common across multiple types of Office applications. Outlook-Add-Ins verwenden ausschließlich allgemeine APIs, insbesondere die Untergruppe der APIs, die über das Mailbox -Objekt verfügbar gemacht werden.Outlook add-ins exclusively use Common APIs, especially the subset of APIs exposed through the Mailbox object.

Sie sollten nur allgemeine APIs für Szenarien verwenden, die nicht von hostspezifischen APIsunterstützt werden.You should only use Common APIs for scenarios that aren't supported by host-specific APIs. Informationen zum Verwenden allgemeiner APIs anstelle von hostspezifischen APIs finden Sie unter Understanding the Office JavaScript API.To learn when to use Common APIs instead of host-specific APIs, see Understanding the Office JavaScript API.

Warum wird für die Office-Add-Ins-API asynchrone Programmierung verwendet?Why does the Office Add-ins API use asynchronous programming? Bei JavaScript handelt es sich um eine Singlethread-Sprache, Das heißt, wenn von einem Skript ein lange dauernder synchroner Prozess aufgerufen wird, wird die Ausführung aller nachfolgenden Prozesse blockiert, bis dieser Prozess abgeschlossen wurde.Because JavaScript is a single-threaded language, if script invokes a long-running synchronous process, all subsequent script execution will be blocked until that process completes. Da bestimmte Vorgänge für Office-Webclients (aber auch für Rich-Clients) die Ausführung blockieren können, wenn Sie synchron ausgeführt werden, sind die meisten Office-JavaScript-APIs für die asynchrone Ausführung ausgelegt.Because certain operations against Office web clients (but rich clients as well) could block execution if they are run synchronously, most of the Office JavaScript APIs are designed to execute asynchronously. Dadurch wird sichergestellt, dass Office-Add-Ins reagieren und schnell sind.This makes sure that Office Add-ins are responsive and fast. Darüber hinaus müssen Sie häufig Rückruffunktionen schreiben, wenn Sie diese asynchronen Methoden verwenden.It also frequently requires you to write callback functions when working with these asynchronous methods.

Die Namen aller asynchronen Methoden in der API enden mit "Async", wie beispielsweise Document.getSelectedDataAsyncdie Binding.getDataAsync, oder Item.loadCustomPropertiesAsync Methoden.The names of all asynchronous methods in the API end with "Async", such as the Document.getSelectedDataAsync, Binding.getDataAsync, or Item.loadCustomPropertiesAsync methods. Wenn eine "Async"-Methode aufgerufen wird, wird sie sofort ausgeführt, und eine nachfolgende Skriptausführung kann fortgesetzt werden.When an "Async" method is called, it executes immediately and any subsequent script execution can continue. Die optionale Rückruffunktion, die Sie an eine „Async“-Methode übergeben, wird ausgeführt, sobald die Daten oder der angeforderte Vorgang bereit sind.The optional callback function you pass to an "Async" method executes as soon as the data or requested operation is ready. Dies ist in der Regel sofort der Fall, es kann jedoch eine geringe Verzögerung bei der Rückgabe auftreten.This generally occurs promptly, but there can be a slight delay before it returns.

Das folgende Diagramm zeigt den Ausführungsfluss für einen Aufruf einer „Async"-Methode, die die Daten liest, die der Benutzer in einem im serverbasierten Word Online oder Excel geöffneten Dokument ausgewählt hat. Wenn der „Async"-Aufruf erfolgt, ist der JavaScript-Ausführungsthread frei für die weitere clientseitige Verarbeitung. (Auch wenn dies nicht im Diagramm dargestellt ist.) Bei der Rückgabe der „Async"-Methode übernimmt die Rückruffunktion die Ausführung im Thread, und das Add-in kann auf die Daten zugreifen, sie verarbeiten und das Ergebnis anzeigen. Das gleiche asynchrone Ausführungsmuster gilt für die Verwendung der Hostanwendungen des Office-Rich-Clients, wie Word 2013 oder Excel 2013.The following diagram shows the flow of execution for a call to an "Async" method that reads the data the user selected in a document open in the server-based Word or Excel. At the point when the "Async" call is made, the JavaScript execution thread is free to perform any additional client-side processing (although none are shown in the diagram). When the "Async" method returns, the callback resumes execution on the thread, and the add-in can the access data, do something with it, and display the result. The same asynchronous execution pattern holds when working with the Office rich client host applications, such as Word 2013 or Excel 2013.

Abbildung 1. Ausführungsfluss bei der asynchronen ProgrammierungFigure 1. Asynchronous programming execution flow

Asynchroner Ausführungsablauf des Programmierungsthread

Die Unterstützung für diesen asynchronen Entwurf in Rich- und Webclients ist Teil des Entwurfsziels „einmal schreiben – plattformübergreifend ausführen" des Entwicklungsmodells für Office-Add-Ins. Beispielsweise können Sie ein Inhalts- oder Aufgabenbereich-Add-In mit einer einzigen Codebasis erstellen, die sowohl in Excel 2013 als auch in Microsoft Excel im Web ausgeführt wird.Support for this asynchronous design in both rich and web clients is part of the "write once-run cross-platform" design goals of the Office Add-ins development model. For example, you can create a content or task pane add-in with a single code base that will run in both Excel 2013 and Excel on the web.

Schreiben der Rückruffunktion für eine "Async"-MethodeWriting the callback function for an "Async" method

Die Rückruffunktion, die Sie als Rückruf Argument an eine "Async"-Methode übergeben, muss einen einzelnen Parameter deklarieren, den die Add-in-Laufzeit verwendet, um Zugriff auf ein asyncResult -Objekt bereitzustellen, wenn die Callback-Funktion ausgeführt wird.The callback function you pass as the callback argument to an "Async" method must declare a single parameter that the add-in runtime will use to provide access to an AsyncResult object when the callback function executes. Folgendes schreiben:You can write:

  • Eine anonyme Funktion, die direkt in Einklang mit dem Aufruf der "Async"-Methode als Callback -Parameter der "Async"-Methode geschrieben und übergeben werden muss.An anonymous function that must be written and passed directly in line with the call to the "Async" method as the callback parameter of the "Async" method.

  • Eine benannte Funktion, die den Namen dieser Funktion als Rückruf Parameter einer "Async"-Methode übergibt.A named function, passing the name of that function as the callback parameter of an "Async" method.

Eine anonyme Funktion ist nützlich, wenn Sie den Code nur einmalig verwenden. Da die Funktion keinen Namen hat, können Sie nicht an anderer Stelle des Codes darauf verweisen. Eine benannte Funktion ist nützlich, wenn Sie die Rückruffunktion für mehrere "Async"-Methoden verwenden möchten.An anonymous function is useful if you are only going to use its code once - because it has no name, you can't reference it in another part of your code. A named function is useful if you want to reuse the callback function for more than one "Async" method.

Schreiben einer anonymen RückruffunktionWriting an anonymous callback function

Die folgende anonyme Rückruffunktion deklariert einen einzelnen Parameter namens result , der beim Zurückgeben des Rückrufs Daten aus der asyncResult. Value -Eigenschaft abruft.The following anonymous callback function declares a single parameter named result that retrieves data from the AsyncResult.value property when the callback returns.

function (result) {
        write('Selected data: ' + result.value);
}

Das folgende Beispiel zeigt, wie diese anonyme Rückruffunktion im Kontext eines vollständigen "Async"-Methodenaufrufs an die Document.getSelectedDataAsync Methode übergeben wird.The following example shows how to pass this anonymous callback function in line in the context of a full "Async" method call to the Document.getSelectedDataAsync method.

  • Das erste coercionType -Argument Office.CoercionType.Textgibt an, dass die ausgewählten Daten als Textzeichenfolge zurückgegeben werden sollen.The first coercionType argument, Office.CoercionType.Text, specifies to return the selected data as a string of text.

  • Das zweite Rückruf Argument ist die anonyme Funktion, die Inline an die Methode übergeben wird.The second callback argument is the anonymous function passed in-line to the method. Wenn die Funktion ausgeführt wird, wird der Parameter Result verwendet, um value auf die Eigenschaft AsyncResult des Objekts zuzugreifen, um die vom Benutzer im Dokument ausgewählten Daten anzuzeigen.When the function executes, it uses the result parameter to access the value property of the AsyncResult object to display the data selected by the user in the document.

Office.context.document.getSelectedDataAsync(Office.CoercionType.Text, 
    function (result) {
        write('Selected data: ' + result.value);
    }
});

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

Sie können auch den-Parameter der Callback-Funktion verwenden, um auf andere Eigenschaften AsyncResult des Objekts zuzugreifen.You can also use the parameter of your callback function to access other properties of the AsyncResult object. Verwenden Sie die AsyncResult.status-Eigenschaft, um zu bestimmen, ob der Aufruf erfolgreich ausgeführt wurde oder ob ein Fehler aufgetreten ist.Use the AsyncResult.status property to determine if the call succeeded or failed. Im Falle eines Fehlers können Sie mithilfe der AsyncResult.error-Eigenschaft auf ein Error-Objekt mit Fehlerinformationen zugreifen.If your call fails you can use the AsyncResult.error property to access an Error object for error information.

Weitere Informationen zur Verwendung der getSelectedDataAsync -Methode finden Sie unter Lesen und Schreiben von Daten für die aktive Auswahl in einem Dokument oder Arbeitsblatt.For more information about using the getSelectedDataAsync method, see Read and write data to the active selection in a document or spreadsheet.

Schreiben einer benannten RückruffunktionWriting a named callback function

Alternativ können Sie eine benannte Funktion schreiben und ihren Namen an den Callback -Parameter einer "Async"-Methode übergeben.Alternatively, you can write a named function and pass its name to the callback parameter of an "Async" method. Das vorherige Beispiel kann folgendermaßen umgeschrieben werden, sodass eine Funktion namens writeDataCallback als callback-Parameter übergeben wird:For example, the previous example can be rewritten to pass a function named writeDataCallback as the callback parameter like this.

Office.context.document.getSelectedDataAsync(Office.CoercionType.Text, 
    writeDataCallback);

// Callback to write the selected data to the add-in UI.
function writeDataCallback(result) {
    write('Selected data: ' + result.value);
}

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

Unterschiede in der Rückgabe an die "AsyncResult.value"-EigenschaftDifferences in what's returned to the AsyncResult.value property

Die asyncContext- statusund error -Eigenschaften des AsyncResult Objekts geben dieselben Arten von Informationen an die Rückruffunktion zurück, die an alle "Async"-Methoden übergeben wird.The asyncContext, status, and error properties of the AsyncResult object return the same kinds of information to the callback function passed to all "Async" methods. Was jedoch an die AsyncResult.value Eigenschaft zurückgegeben wird, variiert in Abhängigkeit von der Funktionalität der "Async"-Methode.However, what's returned to the AsyncResult.value property varies depending on the functionality of the "Async" method.

Beispielsweise werden die addHandlerAsync Methoden (der Objekte Binding, CustomXMLPart, Document, RoamingSettingsund Settings ) verwendet, um den von diesen Objekten dargestellten Elementen Ereignis Handlerfunktionen hinzuzufügen.For example, the addHandlerAsync methods (of the Binding, CustomXmlPart, Document, RoamingSettings, and Settings objects) are used to add event handler functions to the items represented by these objects. Sie können auf die AsyncResult.value Eigenschaft von der Rückruffunktion zugreifen, die Sie an eine addHandlerAsync der Methoden übergeben, aber da beim Hinzufügen eines Ereignishandlers auf keine Daten oder Objekte zugegriffen value wird, gibt die Eigenschaft immer undefined zurück, wenn Sie versuchen, darauf zuzugreifen.You can access the AsyncResult.value property from the callback function you pass to any of the addHandlerAsync methods, but since no data or object is being accessed when you add an event handler, the value property always returns undefined if you attempt to access it.

Wenn Sie dagegen die Document.getSelectedDataAsync -Methode aufrufen, werden die Daten zurückgegeben, die der Benutzer im Dokument für die AsyncResult.value Eigenschaft im Rückruf ausgewählt hat.On the other hand, if you call the Document.getSelectedDataAsync method, it returns the data the user selected in the document to the AsyncResult.value property in the callback. Wenn Sie die Bindings. getAllAsync -Methode aufrufen, wird ein Array aller Binding Objekte im Dokument zurückgegeben.Or, if you call the Bindings.getAllAsync method, it returns an array of all of the Binding objects in the document. Wenn Sie die Bindings. getByIdAsync -Methode aufrufen, wird ein einzelnes Binding Objekt zurückgegeben.And, if you call the Bindings.getByIdAsync method, it returns a single Binding object.

Eine Beschreibung dessen, was an die AsyncResult.value Eigenschaft für eine Async Methode zurückgegeben wird, finden Sie im Abschnitt "Rückruf Wert" des Referenzthemas dieser Methode.For a description of what's returned to the AsyncResult.value property for an Async method, see the "Callback value" section of that method's reference topic. Eine Zusammenfassung aller Objekte, die Methoden bereitstellen Async , finden Sie in der Tabelle am unteren Rand des asyncResult -Objekt Themas.For a summary of all of the objects that provide Async methods, see the table at the bottom of the AsyncResult object topic.

Asynchrone ProgrammiermusterAsynchronous programming patterns

Die Office-JavaScript-API unterstützt zwei Arten von asynchronen Programmier Mustern:The Office JavaScript API supports two kinds of asynchronous programming patterns:

  • Verwenden geschachtelter RückrufeUsing nested callbacks

  • Verwenden des ZusagemustersUsing the promises pattern

Bei der asynchronen Programmierung mit Rückruffunktionen muss häufig das zurückgegebene Ergebnis eines Rückrufs in zwei oder mehr Rückrufe geschachtelt werden. In diesem Fall können Sie geschachtelte Rückrufe aus allen "Async"-Methoden der API verwenden.Asynchronous programming with callback functions frequently requires you to nest the returned result of one callback within two or more callbacks. If you need to do so, you can use nested callbacks from all "Async" methods of the API.

Die Verwendung von geschachtelten Rückrufen ist ein Programmiermuster, das den meisten JavaScript-Entwicklern vertraut ist, aber Code mit tief geschachtelten Rückrufen kann schwer lesbar und verständlich sein.Using nested callbacks is a programming pattern familiar to most JavaScript developers, but code with deeply nested callbacks can be difficult to read and understand. Als Alternative zu geschachtelten Rückrufen unterstützt die Office-JavaScript-API auch eine Implementierung des versprech Musters.As an alternative to nested callbacks, the Office JavaScript API also supports an implementation of the promises pattern. In der aktuellen Version der Office-JavaScript-API funktioniert das Promises-Muster jedoch nur mit Code für Bindungen in Excel-Kalkulationstabellen und Word-Dokumenten.However, in the current version of the Office JavaScript API, the promises pattern only works with code for bindings in Excel spreadsheets and Word documents.

### Asynchrone Programmierung mithilfe geschachtelter RückruffunktionenAsynchronous programming using nested callback functions

Häufig müssen Sie für eine Aufgabe mehrere asynchrone Vorgänge ausführen. Zu diesem Zweck können Sie einen "Async"-Aufruf in einen anderen "Async"-Aufruf schachteln.Frequently, you need to perform two or more asynchronous operations to complete a task. To accomplish that, you can nest one "Async" call inside another.

Im folgenden Codebeispiel werden zwei asynchrone Aufrufe geschachtelt.The following code example nests two asynchronous calls.

  • Zunächst wird die Bindings.getByIdAsync-Methode aufgerufen, um auf die Bindung „MyBinding“ im Dokument zuzugreifen.First, the Bindings.getByIdAsync method is called to access a binding in the document named "MyBinding". Das AsyncResult an den result Parameter dieses Rückrufs zurückgegebene Objekt ermöglicht den Zugriff auf das angegebene AsyncResult.value Binding-Objekt von der Eigenschaft.The AsyncResult object returned to the result parameter of that callback provides access to the specified binding object from the AsyncResult.value property.

  • Anschließend wird das Binding-Objekt, auf das result vom ersten Parameter zugegriffen wird, verwendet, um die Binding. getDataAsync -Methode aufzurufen.Then, the binding object accessed from the first result parameter is used to call the Binding.getDataAsync method.

  • Schließlich wird der result2 Parameter des Rückrufs, der an Binding.getDataAsync die Methode übergeben wird, verwendet, um die Daten in der Bindung anzuzeigen.Finally, the result2 parameter of the callback passed to the Binding.getDataAsync method is used to display the data in the binding.

function readData() {
    Office.context.document.bindings.getByIdAsync("MyBinding", function (result) {
        result.value.getDataAsync({ coercionType: 'text' }, function (result2) {
            write(result2.value);
        });
    });
}

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

Dieses grundlegende geschachtelte Rückruf Muster kann für alle asynchronen Methoden in der Office-JavaScript-API verwendet werden.This basic nested callback pattern can be used for all asynchronous methods in the Office JavaScript API.

In den folgenden Abschnitten wird gezeigt, wie anonyme oder benannte Funktionen für geschachtelte Rückrufe in asynchronen Methoden verwendet werden.The following sections show how to use either anonymous or named functions for nested callbacks in asynchronous methods.

Verwenden anonymer Funktionen für geschachtelte RückrufeUsing anonymous functions for nested callbacks

Im folgenden Beispiel werden zwei anonyme Funktionen Inline deklariert und an die getByIdAsync Methoden and getDataAsync als geschachtelte Rückrufe übergeben.In the following example, two anonymous functions are declared inline and passed into the getByIdAsync and getDataAsync methods as nested callbacks. Da diese Funktionen einfach und inline sind, ist die Implementierungsabsicht sofort ersichtlich.Because the functions are simple and inline, the intent of the implementation is immediately clear.

Office.context.document.bindings.getByIdAsync('myBinding', function (bindingResult) {
    bindingResult.value.getDataAsync(function (getResult) {
        if (getResult.status == Office.AsyncResultStatus.Failed) {
            write('Action failed. Error: ' + asyncResult.error.message);
        } else {
            write('Data has been read successfully.');
        }
    });
});

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

Verwenden benannter Funktionen für geschachtelte RückrufeUsing named functions for nested callbacks

In komplexen Implementierungen kann die Verwendung benannter Funktionen hilfreich sein, um die Lesbarkeit, Wartbarkeit und Wiederverwendbarkeit des Codes zu verbessern.In complex implementations, it may be helpful to use named functions to make your code easier to read, maintain, and reuse. Im folgenden Beispiel wurden die beiden anonymen Funktionen aus dem Beispiel im vorherigen Abschnitt als Funktionen namens deleteAllData und showResultumgeschrieben.In the following example, the two anonymous functions from the example in the previous section have been rewritten as functions named deleteAllData and showResult. Diese benannten Funktionen werden dann als Rückrufe getByIdAsync nach deleteAllDataValuesAsync Namen an die Methoden and übergeben.These named functions are then passed into the getByIdAsync and deleteAllDataValuesAsync methods as callbacks by name.

Office.context.document.bindings.getByIdAsync('myBinding', deleteAllData);

function deleteAllData(asyncResult) {
    asyncResult.value.deleteAllDataValuesAsync(showResult);
}

function showResult(asyncResult) {
    if (asyncResult.status == Office.AsyncResultStatus.Failed) {
        write('Action failed. Error: ' + asyncResult.error.message);
    } else {
        write('Data has been deleted successfully.');
    }
}

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

Asynchrone Programmierung mithilfe des Zusagemusters zum Zugriff auf Daten in BindungenAsynchronous programming using the promises pattern to access data in bindings

Anstatt eine Rückruffunktion zu übergeben und zu warten, dass die Funktion zurückgegeben wird, bevor die Ausführung fortgesetzt wird, gibt das Zusageprogrammierungsmuster sofort ein Zusageobjekt zurück, das das erwartete Ergebnis darstellt. Allerdings wird im Gegensatz zum wirklich synchronen Programmieren die Erfüllung der Zusage im Hintergrund tatsächlich verzögert, bis das Runtime Environment des Office-Add-Ins die Anforderung abschließen kann. Es wird ein onError-Handler für den Fall bereitgestellt, dass die Anforderung nicht erfüllt werden kann.Instead of passing a callback function and waiting for the function to return before execution continues, the promises programming pattern immediately returns a promise object that represents its intended result. However, unlike true synchronous programming, under the covers the fulfillment of the promised result is actually deferred until the Office Add-ins runtime environment can complete the request. An onError handler is provided to cover situations when the request can't be fulfilled.

Die Office-JavaScript-API stellt die Office. Select -Methode bereit, um das versprech Muster für das Arbeiten mit vorhandenen Binding-Objekten zu unterstützen.The Office JavaScript API provides the Office.select method to support the promises pattern for working with existing binding objects. Office.select Das an die Methode zurückgegebene Promise-Objekt unterstützt nur die vier Methoden, auf die Sie direkt über das Binding -Objekt zugreifen können: getDataAsync, setDataAsync, addHandlerAsyncund removeHandlerAsync.The promise object returned to the Office.select method supports only the four methods that you can access directly from the Binding object: getDataAsync, setDataAsync, addHandlerAsync, and removeHandlerAsync.

Das Zusagemuster für die Verwendung von Bindungen hat folgendes Format:The promises pattern for working with bindings takes this form:

Office. Select (selectoration, OnError). BindingObjectAsyncMethodOffice.select(selectorExpression, onError).BindingObjectAsyncMethod

Der selectoration -Parameter nimmt das "bindings#bindingId"Formular an, wobei " BindingExpression " der idName () einer Bindung ist, die Sie zuvor im Dokument oder Arbeitsblatt erstellt haben (mit einer der "addfrom" Bindings -Methoden addFromNamedItemAsyncder addFromPromptAsyncAuflistung: addFromSelectionAsync, oder).The selectorExpression parameter takes the form "bindings#bindingId", where bindingId is the name ( id) of a binding that you created previously in the document or spreadsheet (using one of the "addFrom" methods of the Bindings collection: addFromNamedItemAsync, addFromPromptAsync, or addFromSelectionAsync). Der Selector-Ausdruck bindings#cities gibt beispielsweise an, dass Sie mit der ID "Cities" auf die Bindung zugreifen möchten.For example, the selector expression bindings#cities specifies that you want to access the binding with an id of 'cities'.

Der OnError -Parameter ist eine Fehlerbehandlungsfunktion, die einen einzelnen Parameter vom AsyncResult Typ annimmt, der für den Error Zugriff auf ein Objekt select verwendet werden kann, wenn die Methode nicht auf die angegebene Bindung zugreift.The onError parameter is an error handling function which takes a single parameter of type AsyncResult that can be used to access an Error object, if the select method fails to access the specified binding. Das folgende Beispiel zeigt eine einfache Error Handler-Funktion, die an den OnError -Parameter übergeben werden kann.The following example shows a basic error handler function that can be passed to the onError parameter.

function onError(result){
    var err = result.error;
    write(err.name + ": " + err.message);
}
// Function that writes to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += message; 
}

Ersetzen Sie den BindingObjectAsyncMethod -Platzhalter durch einen Aufruf einer der Binding vier vom Promise-Objekt unterstützten getDataAsyncObjekt setDataAsyncMethoden addHandlerAsync:, removeHandlerAsync,, oder.Replace the BindingObjectAsyncMethod placeholder with a call to any of the four Binding object methods supported by the promise object: getDataAsync, setDataAsync, addHandlerAsync, or removeHandlerAsync. Aufrufe dieser Methoden unterstützen keine weiteren Zusagen.Calls to these methods don't support additional promises. Sie müssen sie mit dem Muster geschachtelter Rückruffunktionen aufrufen.You must call them using the nested callback function pattern.

Nachdem ein Binding Objekt Versprechen erfüllt wurde, kann es im verketteten Methodenaufruf wieder verwendet werden, als wäre es eine Bindung (die Add-in-Laufzeit versucht nicht asynchron, die Zusage zu erfüllen).After a Binding object promise is fulfilled, it can be reused in the chained method call as if it were a binding (the add-in runtime won't asynchronously retry fulfilling the promise). Wenn das Binding Objekt Versprechen nicht erfüllt werden kann, versucht die Add-in-Laufzeit erneut, auf das Binding-Objekt zuzugreifen, wenn das nächste Mal eine seiner asynchronen Methoden aufgerufen wird.If the Binding object promise can't be fulfilled, the add-in runtime will try again to access the binding object the next time one of its asynchronous methods is invoked.

Im folgenden Codebeispiel wird die select -Methode verwendet, um eine Bindung id mitcities"" aus Bindings der Auflistung abzurufen, und anschließend wird die addHandlerAsync -Methode aufgerufen, um einen Ereignishandler für das DataChanged-Ereignis der Bindung hinzuzufügen.The following code example uses the select method to retrieve a binding with the id "cities" from the Bindings collection, and then calls the addHandlerAsync method to add an event handler for the dataChanged event of the binding.

function addBindingDataChangedEventHandler() {
    Office.select("bindings#cities", function onError(){/* error handling code */}).addHandlerAsync(Office.EventType.BindingDataChanged,
    function (eventArgs) {
        doSomethingWithBinding(eventArgs.binding);
    });
}

Wichtig

Das Binding von der Office.select Methode zurückgegebene Objekt Versprechen ermöglicht den Zugriff auf nur die Binding vier Methoden des Objekts.The Binding object promise returned by the Office.select method provides access to only the four methods of the Binding object. Wenn Sie auf eines der anderen Elemente Binding des Objekts zugreifen müssen, müssen Sie stattdessen die Document.bindings -Eigenschaft und Bindings.getByIdAsync /oder Bindings.getAllAsync -Methoden verwenden, um Binding das Objekt abzurufen.If you need to access any of the other members of the Binding object, instead you must use the Document.bindings property and Bindings.getByIdAsync or Bindings.getAllAsync methods to retrieve the Binding object. Wenn Sie Binding beispielsweise auf eine der Eigenschaften des Objekts (die document, idoder type Eigenschaften) zugreifen müssen oder auf die Eigenschaften des MatrixBinding -oder des beginbinding -Objekts zugreifen müssen, müssen Sie die getByIdAsync or getAllAsync -Methoden verwenden, um ein Binding Objekt abzurufen.For example, if you need to access any of the Binding object's properties (the document, id, or type properties), or need to access the properties of the MatrixBinding or TableBinding objects, you must use the getByIdAsync or getAllAsync methods to retrieve a Binding object.

Übergeben optionaler Parameter an asynchrone MethodenPassing optional parameters to asynchronous methods

Für die allgemeine Syntax aller "Async"-Methoden gilt folgendes Muster:The common syntax for all "Async" methods follows this pattern:

AsyncMethod (RequiredParameters, [OptionalParameters],CallbackFunction);AsyncMethod ( RequiredParameters , [ OptionalParameters ], CallbackFunction );

Alle asynchronen Methoden unterstützen optionale Parameter, die als JSON-Objekt (JavaScript Object Notation) übergeben werden, das einen oder mehrere optionale Parameter enthält. Das JSON-Objekt, das die optionalen Parameter enthält, ist eine nicht sortierte Auflistung von Schlüssel/Wert-Paaren, wobei der Schlüssel und der Wert durch das Zeichen ":" voneinander getrennt werden. Jedes Paar im Objekt wird durch ein Komma getrennt, und alle Paare werden in geschweifte Klammern gesetzt. Der Schlüssel ist der Parametername, und der Wert ist der Wert, der für diesen Parameter übergeben werden soll.All asynchronous methods support optional parameters, which are passed in as a JavaScript Object Notation (JSON) object that contains one or more optional parameters. The JSON object containing the optional parameters is an unordered collection of key-value pairs with the ":" character separating the key and the value. Each pair in the object is comma-separated, and the entire set of pairs is enclosed in braces. The key is the parameter name, and value is the value to pass for that parameter.

Sie können das JSON-Objekt, das optionale Parameter enthält, Inline erstellen, oder options indem Sie ein Objekt erstellen und dieses als options Parameter übergeben.You can create the JSON object that contains optional parameters inline, or by creating an options object and passing that in as the options parameter.

Inlineübergabe optionaler ParameterPassing optional parameters inline

Die Syntax, um die Document.setSelectedDataAsync-Methode mit optionalen Parametern inline aufzurufen, lautet z. B. wie folgt:For example, the syntax for calling the Document.setSelectedDataAsync method with optional parameters inline looks like this:

 Office.context.document.setSelectedDataAsync(data, {coercionType: 'coercionType', asyncContext: 'asyncContext'},callback);

In dieser Form der aufrufenden Syntax werden die beiden optionalen Parameter coercionType und _AsyncContext_als JSON-Objekt definiert, das Inline in geschweifte Klammern eingeschlossen ist.In this form of the calling syntax, the two optional parameters, coercionType and asyncContext, are defined as a JSON object inline enclosed in braces.

Im folgenden Beispiel wird gezeigt, wie Sie die Document.setSelectedDataAsync -Methode aufrufen, indem Sie optionale Parameter Inline angeben.The following example shows how to call to the Document.setSelectedDataAsync method by specifying optional parameters inline.

Office.context.document.setSelectedDataAsync(
    "<html><body>hello world</body></html>",
    {coercionType: "html", asyncContext: 42},
    function(asyncResult) {
        write(asyncResult.status + " " + asyncResult.asyncContext);
    }
)

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

Hinweis

Sie können optionale Parameter im JSON-Objekt in einer beliebigen Reihenfolge angeben, solange ihre Namen richtig angegeben sind.You can specify optional parameters in any order in the JSON object as long as their names are specified correctly.

Übergeben optionaler Parameter in einem "options"-ObjektPassing optional parameters in an options object

Alternativ können Sie ein Objekt mit dem Namen options erstellen, das die optionalen Parameter separat vom Methodenaufruf angibt, und dann das options Objekt als options Argument übergeben.Alternatively, you can create an object named options that specifies the optional parameters separately from the method call, and then pass the options object as the options argument.

Das folgende Beispiel zeigt eine Möglichkeit, das options Objekt zu erstellen, parameter1wobei value1, usw., Platzhalter für die tatsächlichen Parameternamen und-Werte sind.The following example shows one way of creating the options object, where parameter1, value1, and so on, are placeholders for the actual parameter names and values.

var options = {
    parameter1: value1,
    parameter2: value2,
    ...
    parameterN: valueN
};

Dieses sieht wie im folgenden Beispiel aus, wenn es zum Angeben der Parameter ValueFormat und FilterType verwendet wird:Which looks like the following example when used to specify the ValueFormat and FilterType parameters.

var options = {
    valueFormat: "unformatted",
    filterType: "all"
};

Hier ist eine weitere Möglichkeit, das options Objekt zu erstellen.Here's another way of creating the options object.

var options = {};
options[parameter1] = value1;
options[parameter2] = value2;
...
options[parameterN] = valueN;

Das sieht wie im folgenden Beispiel aus, wenn es zum ValueFormat angeben FilterType der Parameter und verwendet wird:Which looks like the following example when used to specify the ValueFormat and FilterType parameters:

var options = {};
options["ValueFormat"] = "unformatted";
options["FilterType"] = "all";

Hinweis

Wenn Sie eine der beiden Methoden zum options Erstellen des Objekts verwenden, können Sie optionale Parameter in beliebiger Reihenfolge angeben, solange ihre Namen richtig angegeben sind.When using either method of creating the options object, you can specify optional parameters in any order as long as their names are specified correctly.

Im folgenden Beispiel wird gezeigt, wie Sie die Document.setSelectedDataAsync -Methode aufrufen, indem Sie optionale options Parameter in einem-Objekt angeben.The following example shows how to call to the Document.setSelectedDataAsync method by specifying optional parameters in an options object.

var options = {
   coercionType: "html",
   asyncContext: 42
};

document.setSelectedDataAsync(
    "<html><body>hello world</body></html>",
    options,
    function(asyncResult) {
        write(asyncResult.status + " " + asyncResult.asyncContext);
    }
)

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

In beiden optionalen Parameter-Beispielen wird der Callback -Parameter als letzter-Parameter angegeben (nach den optionalen inline-Parametern oder nach dem Argument-Argument des options -Objekts).In both optional parameter examples, the callback parameter is specified as the last parameter (following the inline optional parameters, or following the options argument object). Alternativ können Sie den callback-Parameter innerhalb des Inline-JSON-Objekts oder aber im options-Objekt angeben.Alternatively, you can specify the callback parameter inside either the inline JSON object, or in the options object. Sie können den callback-Parameter jedoch nur an einer Stelle übergeben, nämlich entweder im options-Objekt (inline oder extern erstellt) oder als letzten Parameter.However, you can pass the callback parameter in only one location: either in the options object (inline or created externally), or as the last parameter, but not both.

Siehe auchSee also