Leer y escribir datos en la selección activa de un documento o una hoja de cálculo

El objeto Document expone métodos que permiten leer y escribir en la selección actual del usuario en documentos u hojas de cálculo. Para ello, el Document objeto proporciona los getSelectedDataAsync métodos y setSelectedDataAsync . En este tema, también se describe cómo leer, escribir y crear controladores de eventos para detectar los cambios realizados en la selección del usuario.

El getSelectedDataAsync método solo funciona con la selección actual del usuario. Si necesita guardar la selección en el documento, para que la misma selección esté disponible para leer y escribir en las distintas sesiones de ejecución del complemento, tiene que agregar un enlace con el método Bindings.addFromSelectionAsync (o crear un enlace con uno de los otros métodos "addFrom" del objeto Bindings). Para obtener información sobre la creación de un enlace a una región de un documento y sobre cómo leer y escribir en él, vea Enlazar a regiones de un documento u hoja de cálculo.

Lectura de los datos seleccionados

En el ejemplo siguiente se muestra cómo obtener datos de una selección en un documento con el método getSelectedDataAsync.

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

En este ejemplo, el primer parámetro, coercionType, se especifica como Office.CoercionType.Text (también puede especificar este parámetro mediante la cadena "text"literal ). Esto quiere decir que la propiedad value del objeto AsyncResult disponible del parámetro asyncResult de la función de devolución de llamada devolverá una cadena (string) que contendrá el texto seleccionado en el documento. Especificar tipos distintos de coerción dará como resultado valores diferentes. Office.CoercionType es una enumeración de los valores de tipos de coerción disponibles. Office.CoercionType.Text se evalúa como la cadena "text".

Sugerencia

¿Cuándo debería usar la matriz en vez de la tabla coercionType para el acceso a los datos? Si necesita que los datos tabulares seleccionados crezcan dinámicamente cuando se agregan filas y columnas y debe trabajar con encabezados de tabla, debe usar el tipo de datos de tabla (especificando el parámetro coercionType del getSelectedDataAsync método como "table" o Office.CoercionType.Table). La adición de filas y columnas en la estructura de datos se admite tanto en los datos de matriz como de tabla, pero la anexión de filas y columnas solo se admite para los datos de tabla. Si no planea agregar filas y columnas, y los datos no requieren funcionalidad de encabezado, debe usar el tipo de datos de matriz (especificando el parámetro coercionType del getSelectedDataAsync método como "matrix" o Office.CoercionType.Matrix), que proporciona un modelo más sencillo de interacción con los datos.

La función anónima que se pasa al método como segundo parámetro, devolución de llamada, se ejecuta cuando se completa la getSelectedDataAsync operación. Se llama a la función con un único parámetro (asyncResult) que contiene el resultado y el estado de la llamada. Si se produce un error en la llamada, la propiedad error del AsyncResult objeto proporciona acceso al objeto Error . Puede comprobar el valor de las propiedades Error.name y Error.message para determinar el motivo por el que la acción establecida falló. De no ser así, se mostrará el texto seleccionado en el documento.

La propiedad AsyncResult.status se usa en la instrucción if para comprobar si la llamada se realizó correctamente o no. Office.AsyncResultStatus es una enumeración de valores de propiedad disponibles AsyncResult.status . Office.AsyncResultStatus.Failed se evalúa como la cadena "failed" (y, de nuevo, también se puede especificar como esa cadena literal).

Escritura de datos en la selección

En el ejemplo siguiente se muestra cómo configurar la selección para que muestre "Hola a todos!".

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

Pasar diferentes tipos de objeto para el parámetro de datos tendrá resultados diferentes. El resultado depende de lo que esté seleccionado actualmente en el documento, de la aplicación cliente de Office que hospeda el complemento y de si los datos pasados se pueden convertir a la selección actual.

La función anónima pasada al método setSelectedDataAsync como parámetro callback se ejecuta cuando se completa la llamada asincrónica. Al escribir datos en la selección mediante el setSelectedDataAsync método , el parámetro asyncResult de la devolución de llamada proporciona acceso solo al estado de la llamada y al objeto Error si se produce un error en la llamada.

Detección de cambios en la selección

En el ejemplo siguiente se muestra cómo detectar cambios en la selección cuando se agrega un controlador de eventos con el método Document.addHandlerAsync para el evento SelectionChanged en el documento.

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

El primer parámetro, eventType, especifica el nombre del evento al que se va a suscribir. Pasar la cadena "documentSelectionChanged" de este parámetro equivale a pasar el Office.EventType.DocumentSelectionChanged tipo de evento de la enumeración Office.EventType .

La myHandler() función que se pasa al método como segundo parámetro, controlador, es un controlador de eventos que se ejecuta cuando se cambia la selección en el documento. Se llama a la función con un parámetro único, eventArgs, que incluye una referencia a un objeto DocumentSelectionChangedEventArgs cuando se completa la operación asincrónica. Puede usar la propiedad DocumentSelectionChangedEventArgs.document para obtener acceso al documento que generó el evento.

Nota:

Puede agregar varios controladores de eventos para un evento determinado llamando de nuevo al addHandlerAsync método y pasando una función de controlador de eventos adicional para el parámetro de controlador . Esto funcionará correctamente siempre que el nombre de cada función del controlador de eventos sea único.

Desactivación de la detección de cambios en la selección

En el ejemplo siguiente se muestra cómo dejar de escuchar el evento Document.SelectionChanged a través de una llamada al método document.removeHandlerAsync.

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

El myHandler nombre de la función que se pasa como segundo parámetro, controlador, especifica el controlador de eventos que se quitará del SelectionChanged evento.

Importante

Si se omite el parámetro de controlador opcional cuando se llama al removeHandlerAsync método, se quitarán todos los controladores de eventos para el eventType especificado.