Lesen und Schreiben von Daten in der aktiven Auswahl in einem Dokument oder ArbeitsblattRead and write data to the active selection in a document or spreadsheet

Vom Document-Objekt werden Methoden verfügbar gemacht, mit denen Sie die Auswahl eines Benutzers in einem Dokument oder einer Arbeitsmappe lesen und in diese schreiben können. Zu diesem Zweck weist das Document-Objekt die Methoden getSelectedDataAsync und setSelectedDataAsync auf. In diesem Thema wird beschrieben, wie Sie Ereignishandler zum Erkennen von Änderungen an der Auswahl des Benutzers lesen, schreiben und erstellen.The Document object exposes methods that let you read and write to the user's current selection in a document or spreadsheet. To do that, the Document object provides the getSelectedDataAsync and setSelectedDataAsync methods. This topic also describes how to read, write, and create event handlers to detect changes to the user's selection.

Die Methode getSelectedDataAsync gilt nur für die aktuelle Auswahl des Benutzers. Wenn die Auswahl im Dokument gespeichert werden soll, damit dieselbe Auswahl über Sitzungen des Add-Ins hinweg zum Lesen und Schreiben verfügbar ist, müssen Sie mithilfe der Methode Bindings.addFromSelectionAsync eineBindung hinzufügen (oder mit einer der anderen „addFrom“-Methoden des Objekts Bindings eine Bindung erstellen). Weitere Informationen dazu, wie Sie eine Bindung an einen Dokumentbereich erstellen und dann eine Bindung lesen und schreiben, finden Sie unter Einrichten einer Bindung an Regionen in einem Dokument oder Arbeitsblatt.The getSelectedDataAsync method only works against the user's current selection. If you need to persist the selection in the document, so that the same selection is available to read and write across sessions of running your add-in, you must add a binding using the Bindings.addFromSelectionAsync method (or create a binding with one of the other "addFrom" methods of the Bindings object). For information about creating a binding to a region of a document, and then reading and writing to a binding, see Bind to regions in a document or spreadsheet.

Lesen ausgewählter DatenRead selected data

Im folgenden Beispiel wird gezeigt, wie Sie Daten aus einer Auswahl in einem Dokument mithilfe der getSelectedDataAsync-Methode abrufen.The following example shows how to get data from a selection in a document by using the getSelectedDataAsync method.

Office.context.document.getSelectedDataAsync(Office.CoercionType.Text, function (asyncResult) {
    if (asyncResult.status == Office.AsyncResultStatus.Failed) {
        write('Action failed. Error: ' + asyncResult.error.message);
    }
    else {
        write('Selected data: ' + asyncResult.value);
    }
});

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

In diesem Beispiel ist der erste coercionType-Parameter als Office.CoercionType.Text angegeben (Sie können diesen Parameter auch mithilfe der Literalzeichenfolge "text") angeben. Dies bedeutet, dass die value-Eigenschaft des AsyncResult-Objekts, das über den asyncResult-Parameter in der Rückruffunktion verfügbar ist, ein string-Objekt zurückgibt, das den im Dokument ausgewählten Text enthält. Durch Angabe anderer Koersionstypen ergeben sich unterschiedliche Werte. Office.CoercionType ist eine Enumeration verfügbarer Koersionstypwerte. Office.CoercionType.Text wird zur Zeichenfolge „text“ ausgewertet.In this example, the first coercionType parameter is specified as Office.CoercionType.Text (you can also specify this parameter by using the literal string "text"). This means that the value property of the AsyncResult object that is available from the asyncResult parameter in the callback function will return a string that contains the selected text in the document. Specifying different coercion types will result in different values. Office.CoercionType is an enumeration of available coercion type values. Office.CoercionType.Text evaluates to the string "text".

Tipp

Wann sollten Sie den Koersionstyp Matrix und wann den Koersionstyp Tabelle für den Datenzugriff verwenden? Wenn die ausgewählten Tabellendaten dynamisch mit hinzugefügten Zeilen und Spalten wachsen sollen und Sie mit Tabellenkopfzeilen arbeiten müssen, sollten Sie den Datentyp Tabelle verwenden (indem Sie den coercionType-Parameter der getSelectedDataAsync-Methode als "table" oder Office.CoercionType.Table angeben). Das Hinzufügen von Zeilen und Spalten innerhalb der Datenstruktur wird in Tabellen- und Matrixdaten unterstützt, das Anfügen von Zeilen und Spalten jedoch nur für Tabellendaten.Wenn keine Zeilen und Spalten hinzugefügt werden sollen und keine Kopfzeilenfunktionen für die Daten erforderlich sind, sollten Sie den Datentyp Matrix verwenden (indem Sie den coercionType-Parameter der getSelecteDataAsync-Methode als "matrix" oder Office.CoercionType.Matrix angeben), da dies eine einfachere Interaktion mit den Daten ermöglicht.When should you use the matrix versus table coercionType for data access? If you need your selected tabular data to grow dynamically when rows and columns are added, and you must work with table headers, you should use the table data type (by specifying the coercionType parameter of the getSelectedDataAsync method as "table" or Office.CoercionType.Table). Adding rows and columns within the data structure is supported in both table and matrix data, but appending rows and columns is supported only for table data. If you are you aren't planning on adding rows and columns, and your data doesn't require header functionality, then you should use the matrix data type (by specifying the coercionType parameter of getSelecteDataAsync method as "matrix" or Office.CoercionType.Matrix), which provides a simpler model of interacting with the data.

Die anonyme Funktion, die an die Funktion als zweiter callback-Parameter übergeben wird, wird nach Abschluss des getSelectedDataAsync-Vorgangs ausgeführt. Die Funktion wird mit einem einzelnen Parameter, asyncResult, aufgerufen, der das Ergebnis und den Status des Aufrufs enthält. Falls der Aufruf fehlschlägt, ermöglicht die error-Eigenschaft des AsyncResult-Objekts den Zugriff auf das Error-Objekt. Sie können den Wert der Eigenschaften Error.name und Error.message überprüfen, um festzustellen, weshalb der Vorgang fehlgeschlagen ist. Andernfalls wird der im Dokument ausgewählte Text angezeigt.The anonymous function that is passed into the function as the second callback parameter is executed when the getSelectedDataAsync operation is completed. The function is called with a single parameter, asyncResult, which contains the result and the status of the call. If the call fails, the error property of the AsyncResult object provides access to the Error object. You can check the value of the Error.name and Error.message properties to determine why the set operation failed. Otherwise, the selected text in the document is displayed.

Die AsyncResult.status-Eigenschaft wird in der if-Anweisung verwendet, um zu testen, ob der Aufruf erfolgreich war. Office.AsyncResultStatus ist eine Enumeration der verfügbaren AsyncResult.status-Eigenschaftswerte. Office.AsyncResultStatus.Failed wird zur Zeichenfolge „failed“ ausgewertet (und kann wiederum auch als diese Literalzeichenfolge angegeben werden).The AsyncResult.status property is used in the if statement to test whether the call succeeded. Office.AsyncResultStatus is an enumeration of available AsyncResult.status property values. Office.AsyncResultStatus.Failed evaluates to the string "failed" (and, again, can also be specified as that literal string).

Schreiben von Daten in die AuswahlWrite data to the selection

Im folgenden Beispiel wird gezeigt, wie Sie für die Auswahl festlegen, dass "Hello World!" angezeigt wird.The following example shows how to set the selection to show "Hello World!".

Office.context.document.setSelectedDataAsync("Hello World!", function (asyncResult) {
    if (asyncResult.status == Office.AsyncResultStatus.Failed) {
        write(asyncResult.error.message);
    }
});

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

Wenn Sie unterschiedliche Objekttypen für den Parameter data übergeben, erhalten Sie auch unterschiedliche Ergebnisse. Das Ergebnis ist abhängig von der aktuellen Auswahl im Dokument, von welcher Anwendung das Add-in gehostet wird sowie ob die übergebenen Daten in die aktuelle Auswahl umgewandelt werden können.Passing in different object types for the data parameter will have different results. The result depends on what is currently selected in the document, which application is hosting your add-in, and whether the data passed in can be coerced to the current selection.

Die anonyme Funktion, die an die setSelectedDataAsync-Methode als callback-Parameter übergeben wird, wird nach Abschluss des asynchronen Aufrufs ausgeführt. Wenn Sie Daten mithilfe der setSelectedDataAsync-Methode in die Auswahl schreiben, ermöglicht der asyncResult-Parameter des Rückrufs nur den Zugriff auf den Status des Aufrufs und auf das Error-Objekt, falls der Aufruf fehlschlägt.The anonymous function passed into the setSelectedDataAsync method as the callback parameter is executed when the asynchronous call is completed. When you write data to the selection by using the setSelectedDataAsync method, the asyncResult parameter of the callback provides access only to the status of the call, and to the Error object if the call fails.

Hinweis

Ab dieser Version von Excel 2013 SP1 und der entsprechenden Version von Excel im Web können Sie nun die Formatierung festlegen, wenn Sie eine Tabelle zur aktuellen Auswahl verfassen.Starting with the release of the Excel 2013 SP1 and the corresponding build of Excel Online, you can now set formatting when writing a table to the current selection.

Erkennen von Änderungen in der AuswahlDetect changes in the selection

Im folgenden Beispiel wird gezeigt, wie Sie Änderungen in der Auswahl mithilfe der Document.addHandlerAsync-Methode erkennen, um einen Ereignishandler für das SelectionChanged-Ereignis im Dokument hinzuzufügen.The following example shows how to detect changes in the selection by using the Document.addHandlerAsync method to add an event handler for the SelectionChanged event on the document.

Office.context.document.addHandlerAsync("documentSelectionChanged", myHandler, function(result){}
);

// Event handler function.
function myHandler(eventArgs){
write('Document Selection Changed');
}

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

Mit dem ersten eventType-Parameter wird der Name des Ereignisses angegeben, das abonniert wird. Das Übergeben der Zeichenfolge "documentSelectionChanged" für diesen Parameter entspricht dem Übergeben des Office.EventType.DocumentSelectionChanged-Ereignistyps der Office.EventType-Enumeration.The first eventType parameter specifies the name of the event to subscribe to. Passing the string "documentSelectionChanged" for this parameter is equivalent to passing the Office.EventType.DocumentSelectionChanged event type of the Office.EventType enumeration.

Die myHander()-Funktion, die an die Funktion als zweiter handler-Parameter übergeben wird, ist ein Ereignishandler, der ausgeführt wird, wenn die Auswahl im Dokument geändert wird. Die Funktion wird nach Abschluss des asynchronen Vorgangs mit einem einzelnen Parameter, eventArgs, aufgerufen, der einen Verweis auf ein DocumentSelectionChangedEventArgs-Objekt enthält. Die DocumentSelectionChangedEventArgs.document-Eigenschaft ermöglicht den Zugriff auf das Dokument, welches das Ereignis ausgelöst hat.The myHander() function that is passed into the function as the second handler parameter is an event handler that is executed when the selection is changed on the document. The function is called with a single parameter, eventArgs, which will contain a reference to a DocumentSelectionChangedEventArgs object when the asynchronous operation completes. You can use the DocumentSelectionChangedEventArgs.document property to access the document that raised the event.

Hinweis

Sie können einem bestimmten Ereignis mehrere Ereignishandler anhängen, 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.

Beenden der Erkennung von Änderungen in der AuswahlStop detecting changes in the selection

Im folgenden Beispiel wird gezeigt, wie Sie die Überwachung des Document.SelectionChanged-Ereignisses beenden, indem Sie die document.removeHandlerAsync-Methode aufrufen.The following example shows how to stop listening to the Document.SelectionChanged event by calling the document.removeHandlerAsync method.

Office.context.document.removeHandlerAsync("documentSelectionChanged", {handler:myHandler}, function(result){});

Mit dem myHandler-Funktionsnamen, der als zweiter handler-Parameter übergeben wird, wird der Ereignishandler angegeben, der aus dem SelectionChanged-Ereignis entfernt wird.The myHandler function name that is passed as the second handler parameter specifies the event handler that will be removed from the SelectionChanged event.

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.