Lesen und Schreiben von Daten in der aktiven Auswahl in einem Dokument oder Arbeitsblatt

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. Dazu stellt das -Objekt die Document -Methode und setSelectedDataAsync die getSelectedDataAsync -Methode bereit. In diesem Thema wird beschrieben, wie Sie Ereignishandler zum Erkennen von Änderungen an der Auswahl des Benutzers lesen, schreiben und erstellen.

Die getSelectedDataAsync -Methode funktioniert 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.

Lesen ausgewählter Daten

Im folgenden Beispiel wird gezeigt, wie Sie Daten aus einer Auswahl in einem Dokument mithilfe der getSelectedDataAsync-Methode abrufen.

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 wird der erste Parameter , coercionType, 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.

Tipp

Wann sollten Sie die Matrix-Koersion der Tabellenkoersion für den Datenzugriff vorziehen? Wenn Die ausgewählten tabellarischen Daten dynamisch wachsen sollen, wenn Zeilen und Spalten hinzugefügt werden, und Sie mit Tabellenüberschriften arbeiten müssen, sollten Sie den Tabellendatentyp verwenden (indem Sie den coercionType-Parameter der getSelectedDataAsync Methode als "table" oder Office.CoercionType.Tableangeben). Das Hinzufügen von Zeilen und Spalten innerhalb der Datenstruktur wird sowohl für Tabellen- als auch Matrixdaten unterstützt, das Anfügen von Zeilen und Spalten wird jedoch nur für Tabellendaten unterstützt. Wenn Sie nicht planen, Zeilen und Spalten hinzuzufügen, und Ihre Daten keine Headerfunktionen erfordern, sollten Sie den Matrixdatentyp verwenden (indem Sie den coercionType-Parameter der getSelectedDataAsync Methode als "matrix" oder Office.CoercionType.Matrixangeben), der ein einfacheres Modell für die Interaktion mit den Daten bietet.

Die anonyme Funktion, die als zweiter Parameter, callback, an die Methode übergeben wird, wird ausgeführt, wenn der getSelectedDataAsync Vorgang abgeschlossen ist. Die Funktion wird mit einem einzelnen Parameter, asyncResult, aufgerufen, der das Ergebnis und den Status des Aufrufs enthält. Wenn der Aufruf fehlschlägt, bietet die error-Eigenschaft des AsyncResult -Objekts 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.

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 ergibt die Zeichenfolge "failed" (und kann auch als diese Literalzeichenfolge angegeben werden).

Schreiben von Daten in die Auswahl

Im folgenden Beispiel wird gezeigt, wie Sie für die Auswahl festlegen, dass "Hello World!" angezeigt wird.

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;
}

Die Übergabe verschiedener Objekttypen für den data-Parameter führt zu unterschiedlichen Ergebnissen. Das Ergebnis hängt davon ab, was derzeit im Dokument ausgewählt ist, welche Office-Clientanwendung Ihr Add-In hostet und ob die übergebenen Daten an die aktuelle Auswahl weitergeleitet werden können.

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, bietet der asyncResult-Parameter des Rückrufs nur Zugriff auf die status des Aufrufs und auf das Error-Objekt, wenn der Aufruf fehlschlägt.

Erkennen von Änderungen in der Auswahl

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.

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;
}

Der erste Parameter, eventType, gibt den Namen des zu abonnierenden Ereignisses an. Das Übergeben der Zeichenfolge "documentSelectionChanged" für diesen Parameter entspricht der Übergabe des Office.EventType.DocumentSelectionChanged Ereignistyps der Office.EventType-Enumeration .

Die myHandler() Funktion, die als zweiter Parameter, Handler, an die -Methode ü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.

Hinweis

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

Beenden der Erkennung von Änderungen in der Auswahl

Im folgenden Beispiel wird gezeigt, wie Sie die Überwachung des Document.SelectionChanged-Ereignisses beenden, indem Sie die document.removeHandlerAsync-Methode aufrufen.

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

Der myHandler Funktionsname, der als zweiter Parameter, Handler, übergeben wird, gibt den Ereignishandler an, der aus dem SelectionChanged Ereignis entfernt wird.

Wichtig

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