Enlazar a regiones de un documento u hoja de cálculo

El acceso a datos basado en enlaces permite a los complementos de panel de tareas y de contenido tener acceso de forma coherente a una determinada región de un documento o una hoja de cálculo a través de un identificador. Primero, el complemento necesita establecer el enlace con una llamada a uno de los métodos que asocian una parte del documento con un identificador único: addFromPromptAsync, addFromSelectionAsync o addFromNamedItemAsync. Después de establecer el enlace, el complemento puede usar el identificador para tener acceso a los datos de la región asociada del documento o la hoja de cálculo. La creación de enlaces proporciona el siguiente valor al complemento.

• Permite el acceso a estructuras de datos comunes de aplicaciones de Office compatibles como, por ejemplo, tablas, rangos o texto (secuencia de caracteres contiguos).
• Permite las operaciones de lectura/escritura sin que el usuario tenga que hacer ninguna selección.
• Establece una relación entre el complemento y los datos del documento. Los enlaces se conservan en el documento y es posible tener acceso a estos más adelante.

Al establecer un enlace, también puede subscribirse a eventos de cambio de datos y de selección designados en esa región en concreto del documento u hoja de cálculo. Es decir, que al complemento solo se le notifican los cambios que ocurren dentro de la región delimitada, y no los cambios generales que se den en todo el documento u hoja de cálculo.

El objeto Bindings expone un método getAllAsync que da acceso al conjunto de todos los enlaces establecidos en el documento u hoja de cálculo. Se puede acceder a un enlace individual mediante su identificador mediante enlaces. Método getByIdAsync o función Office.select . Puede establecer enlaces nuevos, así como quitar los existentes, mediante uno de los métodos siguientes del objeto Bindings: addFromSelectionAsync, addFromPromptAsync, addFromNamedItemAsync o releaseByIdAsync.

Tipos de enlaces

Hay tres tipos diferentes de enlaces que se especifican con el parámetro bindingType al crear un enlace con los métodos addFromSelectionAsync, addFromPromptAsync o addFromNamedItemAsync .

1. Enlace de texto : enlaza a una región del documento que se puede representar como texto.

   En Word, la mayoría de las selecciones contiguas son válidas, mientras que en Excel solo se puede seleccionar una celda como destino del enlace de texto. En Excel, solo se admite el texto sin formato. En Word pueden usarse tres formatos: texto sin formato, HTML y Open XML para Office.

2. Enlace de matriz : enlaza a una región fija de un documento que contiene datos tabulares sin encabezados. Los datos de un enlace de matriz se escriben o leen como una matriz bidimensional, que en JavaScript se implementa como una matriz de matrices. Por ejemplo, dos filas de valores de cadena en dos columnas se pueden escribir o leer como [['a', 'b'], ['c', 'd']]y una sola columna de tres filas se puede escribir o leer como [['a'], ['b'], ['c']].

   En Excel, se puede usar cualquier selección contigua de celdas para establecer un enlace de matriz. En Word, solo las tablas admiten enlaces de matriz.

3. Enlace de tabla : enlaza a una región de un documento que contiene una tabla con encabezados. Los datos de un enlace de tabla se escriben o leen como un objeto TableData . El TableData objeto expone los datos a través de las headers propiedades y rows .

   Se puede usar como base cualquier tabla de Excel o de Word para establecer un enlace de tabla. Una vez se haya establecido un enlace de tabla, cada fila o columna nueva que se agregue a la tabla se incluirá automáticamente al enlace.

Una vez creado un enlace mediante uno de los tres métodos "addFrom" del Bindings objeto, puede trabajar con los datos y propiedades del enlace mediante los métodos del objeto correspondiente: MatrixBinding, TableBinding o TextBinding. Estos tres objetos heredan los métodos getDataAsync y setDataAsync del objeto Binding que le permiten interactuar con los datos enlazados.

Nota:

¿Cuándo debe usar enlaces de matriz en lugar de enlaces de tabla? Cuando los datos tabulares con los que trabaja contienen una fila de total, debe usar un enlace de matriz si el script del complemento necesita acceder a los valores de la fila de total o detectar que la selección del usuario está en la fila de total. Si establece un enlace de tabla para datos tabulares que contengan una fila de total, la propiedad TableBinding.rowCount y las propiedades rowCount y startRow del objeto BindingSelectionChangedEventArgs en controladores de eventos no reflejarán la fila de total en sus valores. Para evitar esta limitación, debe establecer un enlace de matriz para trabajar con la fila de total.

Adición de un enlace a la selección actual del usuario

En el ejemplo siguiente se muestra cómo agregar un enlace de texto llamado myBinding a la selección actual de un documento mediante el método addFromSelectionAsync .

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

En este ejemplo, el tipo de enlace especificado es texto. Esto significa que se creará un TextBinding para la selección. Los distintos tipos de enlace exponen diferentes datos y operaciones. Office.BindingType es una enumeración de valores de tipo de enlace disponibles.

El segundo parámetro opcional es un objeto que indica el identificador del enlace que se va a crear. Si no se especifica ningún identificador, se generará uno automáticamente.

La función anónima que se pasa al método como parámetro de devolución de llamada final se ejecuta cuando se completa la creación del enlace. Se llama a la función con un solo parámetro, asyncResult, que proporciona acceso a un objeto AsyncResult que proporciona el estado de la llamada. La propiedad AsyncResult.value contiene una referencia a un objeto Binding del tipo especificado para el enlace recién creado. Puede usar este objeto Binding para obtener y establecer datos.

Agregar un enlace desde un aviso

En el ejemplo siguiente se muestra cómo agregar un enlace de texto llamado myBinding mediante el método addFromPromptAsync . Este método permite al usuario especificar el rango para el enlace usando el aviso de selección de rango integrado de la aplicación.

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

En este ejemplo, el tipo de enlace especificado es texto. Esto significa que se creará un elemento TextBinding para la selección que el usuario especifique en la petición.

El segundo parámetro es un objeto que contiene el identificador del enlace que se va a crear. Si no se especifica ningún identificador, se generará uno automáticamente.

La función anónima que se pasa al método como tercer parámetro de devolución de llamada se ejecuta cuando se completa la creación del enlace. Cuando se ejecuta la función de devolución de llamada, el objeto AsyncResult contiene el estado de la llamada y el nuevo enlace creado.

La Figura 1 muestra la petición de selección de rango integrada en Excel.

Figura 1. UI de Seleccionar datos en Excel

Adición de un enlace a un elemento con nombre

En el ejemplo siguiente se muestra cómo agregar un enlace al elemento con nombre existente myRange como enlace "matrix" mediante el método addFromNamedItemAsync y asigna el enlace id como "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; 
}

Para Excel, el itemName parámetro del método addFromNamedItemAsync puede hacer referencia a un rango con nombre existente, un rango especificado con el A1 estilo ("A1:A3")de referencia o una tabla. De forma predeterminada, al agregar una tabla en Excel se asigna el nombre "Tabla1" para la primera tabla que agregue, "Tabla2" para la segunda y así sucesivamente. Para asignar un nombre significativo para una tabla en la interfaz de usuario de Excel, use la Table Name propiedad en herramientas de tabla | Pestaña Diseño de la cinta de opciones.

Nota:

En Excel, al especificar una tabla como un elemento con nombre, debe calificar por completo el nombre para incluir el nombre de la hoja de cálculo en el nombre de la tabla en este formato: "Sheet1!Table1"

En el ejemplo siguiente se crea un enlace en Excel a las tres primeras celdas de la columna A ( "A1:A3"), se asigna el identificador "MyCities"y, a continuación, se escriben tres nombres de ciudad en ese enlace.

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

Para Word, el itemName parámetro del método addFromNamedItemAsync hace referencia a la Title propiedad de un Rich Text control de contenido. (No puede enlazar a controles de contenido que no sean el control de contenido Rich Text).

De forma predeterminada, un control de contenido no tiene ningún Title*valor asignado. Para asignar un nombre significativo en la interfaz de usuario de Word, después de insertar un control de contenido Texto enriquecido desde el grupo Controles de la pestaña Desarrollador de la cinta, use el comando Propiedades del grupo Controles para mostrar el cuadro de diálogo Propiedades del control de contenido. A continuación, establezca la Title propiedad del control de contenido en el nombre al que desea hacer referencia desde el código.

En el ejemplo siguiente se crea un enlace de texto en Word a un control de contenido de texto enriquecido denominado "FirstName", se asigna el identificador"firstName" y, a continuación, se muestra esa información.

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

Obtención de todos los enlaces

En el ejemplo siguiente se muestra cómo obtener todos los enlaces de un documento con el método Bindings.getAllAsync.

Office.context.document.bindings.getAllAsync(function (asyncResult) {
    let bindingString = '';
    for (let 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; 
}

Función anónima que se pasa al método como callback parámetro se ejecuta cuando se completa la operación. Se llama a la función con un único parámetro, asyncResult, que contiene una matriz de los enlaces del documento. La matriz se itera para construir una cadena que contenga los identificadores de los enlaces. Después, se muestra la cadena en un cuadro de mensaje.

Obtención de un enlace por el identificador con el método getByIdAsync del objeto Bindings

En el ejemplo siguiente se muestra cómo usar el método getByIdAsync para obtener un enlace de un documento al especificar su identificador. En este ejemplo se supone que se ha agregado al documento un enlace denominado 'myBinding' mediante uno de los métodos descritos anteriormente en este tema.

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

En el ejemplo, el primer id parámetro es el identificador del enlace que se va a recuperar.

La función anónima que se pasa al método como segundo parámetro de devolución de llamada se ejecuta cuando se completa la operación. Se llama a la función con un único parámetro, asyncResult, que contiene el estado de la llamada y el enlace con el identificador "myBinding".

Obtención de un enlace por identificador mediante la función select del objeto de Office

En el ejemplo siguiente se muestra cómo usar la función Office.select para obtener una promesa de objeto Binding en un documento especificando su identificador en una cadena de selector. Después, llama al método Binding.getDataAsync para obtener datos del enlace especificado. En este ejemplo se supone que se ha agregado al documento un enlace denominado 'myBinding' mediante uno de los métodos descritos anteriormente en este tema.

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

Nota:

Si la select promesa de función devuelve correctamente un objeto Binding , ese objeto expone solo los cuatro métodos siguientes del objeto: getDataAsync, setDataAsync, addHandlerAsync y removeHandlerAsync. Si la promesa no puede devolver un objeto Binding, se puede usar la onError devolución de llamada para acceder a un objeto asyncResult.error para obtener más información. Si necesita llamar a un miembro del objeto Binding distinto de los cuatro métodos expuestos por la promesa de objeto Binding devuelta por la select función, use el método getByIdAsync mediante la propiedad Document.bindings y Bindings.Método getByIdAsync para recuperar el objeto Binding .

Liberar un enlace por el identificador

En el ejemplo siguiente se muestra cómo usar el método releaseByIdAsync para liberar un enlace de un documento especificando su identificador.

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

En el ejemplo, el primer parámetro id es el identificador del enlace que se quiere publicar.

La función anónima que se pasa al método como segundo parámetro es una devolución de llamada que se ejecuta cuando se completa la operación. Se llama a la función con un único parámetro, asyncResult, que contiene el estado de la llamada.

Lectura de datos de un enlace

En el ejemplo siguiente se muestra cómo usar el método getDataAsync para obtener datos de un enlace existente.

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 es una variable que contiene un enlace de texto existente en el documento. Como alternativa, puede usar el método Office.select para tener acceso al enlace por su identificador e iniciar la llamada al método getDataAsync de esta manera:

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

La función anónima que se pasa al método es una devolución de llamada que se ejecuta cuando se completa la operación. La propiedad AsyncResult.value contiene los datos de myBinding. El tipo del valor depende del tipo de enlace. El enlace de este ejemplo es un enlace de texto. Por lo tanto, el valor contendrá una cadena. Para obtener ejemplos adicionales de trabajar con enlaces de matriz y tabla, consulte el tema del método getDataAsync.

Escritura de los datos en un enlace

En el ejemplo siguiente se muestra cómo usar el método setDataAsync para establecer datos en un enlace existente.

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

myBinding es una variable que contiene un enlace de texto existente en el documento.

En el ejemplo, el primer parámetro es el valor que se va a establecer en myBinding. Como se trata de un enlace de texto, el valor es una string. Los tipos de enlace diferentes aceptan tipos de datos diferentes.

La función anónima que se pasa al método es una devolución de llamada que se ejecuta cuando se completa la operación. Se llama a la función con un único parámetro, asyncResult, que contiene el estado del resultado.

Detección de cambios en los datos o en la selección de un enlace

En el ejemplo siguiente se muestra cómo conectar un controlador de eventos al evento DataChanged de un enlace con el id. "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;
}

El myBinding es una variable que contiene un enlace de texto existente en el documento.

El primer parámetro eventType del método addHandlerAsync especifica el nombre del evento al que se va a suscribir. Office.EventType es una enumeración de los valores de tipo de evento disponibles. Office.EventType.BindingDataChanged se evalúa como la cadena "bindingDataChanged".

La dataChanged función que se pasa al método como segundo parámetro de controlador es un controlador de eventos que se ejecuta cuando se cambian los datos del enlace. La función se llama con un solo parámetro, eventArgs, que contiene una referencia al enlace. Este enlace puede usarse para recuperar los datos actualizados.

De forma similar, puede detectar cuándo cambia la selección un usuario en un enlace al adjuntar un controlador de eventos para el evento SelectionChanged de un enlace. Para ello, especifique el parámetro eventType del método addHandlerAsync como Office.EventType.BindingSelectionChanged o "bindingSelectionChanged".

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

Eliminación de un controlador de eventos

Para quitar un controlador de eventos de un evento, llame al método removeHandlerAsync pasando el tipo de evento como el primer parámetro eventType y el nombre de la función del controlador de eventos que quiere quitar como segundo parámetro handler. Por ejemplo, la función siguiente quitará la función del controlador de eventos dataChanged que se ha agregado en el ejemplo de la sección anterior.

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

Importante

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

Vea también

• Información sobre la API de JavaScript para Office
• Programación asincrónica en los complementos de Office
• Leer y escribir datos en la selección activa de un documento u hoja de cálculo