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

Use un enlace cuando el complemento necesite acceso confiable a una región específica de un libro de Excel o un documento de Word. Un enlace asocia la región con un identificador único, por lo que el complemento puede volver a ella después de que el usuario cambie su selección o vuelva a abrir el documento.

Con un enlace, el complemento puede:

• Obtener acceso a estructuras de datos comunes, como tablas, rangos o texto.
• Lea y escriba datos sin necesidad de que el usuario seleccione primero la región.
• Supervise los datos y los cambios de selección dentro de la región enlazada.
• Mantenga la relación entre sesiones, ya que el enlace se guarda con el documento.

Elegir el tipo de enlace adecuado

Office admite tres tipos de enlace. Elija un tipo en función de la región y los datos que el complemento necesita leer o escribir.

Especifique el tipo con el bindingType parámetro al crear un enlace mediante addFromSelectionAsync, addFromPromptAsync o addFromNamedItemAsync.

Enlace de texto

Un enlace de texto representa una región del documento como texto.

En Word, funcionan la mayoría de las selecciones contiguas. En Excel, solo las selecciones de una sola celda pueden usar el enlace de texto. Excel solo admite texto sin formato, mientras que Word admite tres formatos: texto sin formato, HTML y Open XML for Office.

Enlace de matriz

Un enlace de matriz representa una región fija de datos tabulares sin encabezados.

Leer o escribir datos de matriz como bidimensionales Array (una matriz de matrices en JavaScript). Por ejemplo, dos filas de string valores en dos columnas tienen el aspecto de [['a', 'b'], ['c', 'd']], y una sola columna de tres filas tiene el aspecto de [['a'], ['b'], ['c']].

En Excel, cualquier selección contigua de celdas funciona para el enlace de matrices. En Word, solo las tablas admiten enlaces de matriz.

Enlace de tabla

Un enlace de tabla representa una tabla con encabezados.

Los datos de un enlace de tabla se leen o escriben como un objeto TableData . El TableData objeto expone datos a través de las headers propiedades and rows .

Se puede usar como base cualquier tabla de Excel o de Word para establecer un enlace de tabla. Después de establecer un enlace de tabla, las nuevas filas o columnas que los usuarios agregan a la tabla se incluyen automáticamente en el enlace.

Después de crear un enlace con uno de los tres métodos "addFrom", puede trabajar con los datos y las propiedades del enlace mediante el objeto correspondiente: MatrixBinding, TableBinding o TextBinding. Los tres objetos heredan los métodos getDataAsync y setDataAsync del Binding objeto para interactuar con los datos enlazados.

Crear un enlace a partir de la selección actual

En el ejemplo siguiente se agrega un enlace de texto llamado myBinding a la selección actual 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 es texto, por lo que se crea un TextBinding para la selección. Los diferentes tipos de enlace exponen datos y operaciones diferentes. Office.BindingType es una enumeración de los tipos de enlace disponibles.

El segundo parámetro opcional especifica el identificador del nuevo enlace. Si no especifica un identificador, se generará uno automáticamente.

La función anónima pasada como parámetro de devolución de llamada final se ejecuta cuando se completa la creación del enlace. La función recibe un único parámetro, asyncResult, que proporciona acceso a un objeto AsyncResult con el estado de la llamada. La AsyncResult.value propiedad 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.

Crear un enlace a partir de una indicación

La función siguiente agrega un enlace de texto llamado myBinding mediante el método addFromPromptAsync . Este método permite a los usuarios especificar el rango para el enlace mediante el mensaje 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 es texto, por lo que se crea un TextBinding para la selección del usuario en la indicación.

El segundo parámetro contiene el identificador del nuevo enlace. Si no especifica un identificador, se generará uno automáticamente.

La función anónima pasada 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 enlace recién creado.

En la captura de pantalla siguiente se muestra la solicitud de selección de rango integrada en Excel.

Adición de un enlace a un elemento con nombre

La función siguiente agrega un enlace al elemento con nombre existente myRange como un enlace de "matriz" 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 addFromNamedItemAsync hace referencia a un rango con nombre existente, un rango especificado con un estilo de referencia A1 ("A1:A3") o una tabla. De forma predeterminada, Excel asigna los nombres "Tabla1" a la primera tabla, "Tabla2" a la segunda y así sucesivamente. Para asignar un nombre significativo a una tabla en la interfaz de usuario de Excel, use la propiedad Nombre de tabla en las Herramientas de tabla | Pestaña Diseño .

La siguiente función crea un enlace en Excel a las tres primeras celdas de la columna A ("A1:A3"), asigna el identificador "MyCities"y, después, escribe tres nombres de ciudades 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 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 de texto enriquecido desde el grupo Controles de la pestaña Programador, use el comando Propiedades del grupo Controles para mostrar el cuadro de diálogo Propiedades del control de contenido. Después, establezca la Title propiedad del control de contenido en el nombre al que quiere hacer referencia desde el código.

La siguiente función crea un enlace de texto en Word a un control de contenido de texto enriquecido denominado "FirstName", asigna el id"firstName". y, a continuación, 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 obtienen todos los enlaces de un documento mediante el método 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;
}

La función anónima que se pasa cuando el callback parámetro se ejecuta cuando se completa la operación. La función se llama con un solo 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.

Obtener un enlace por identificador con getByIdAsync

En el ejemplo siguiente se usa el método getByIdAsync para obtener un enlace en un documento mediante la especificación de su identificador. En este ejemplo se supone que un enlace con nombre 'myBinding' se agregó al documento mediante uno de los métodos descritos anteriormente en este artículo.

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 este ejemplo, el primer id parámetro es el identificador del enlace que se va a recuperar.

La función anónima pasada como segundo parámetro de devolución de llamada se ejecuta cuando se completa la operación. La función se llama con un solo parámetro, asyncResult, que contiene el estado de la llamada y el enlace con el ID "myBinding".

Obtener un enlace por identificador mediante Office.select

En el ejemplo siguiente se usa la función Office.select para obtener una promesa de objeto de enlace en un documento especificando su identificador en una cadena de selector. A continuación, se llama al método getDataAsync para obtener datos del enlace especificado. En este ejemplo se supone que un enlace con nombre 'myBinding' se agregó al documento mediante uno de los métodos descritos anteriormente en este artículo.

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

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

Liberar un enlace por el identificador

En el ejemplo siguiente se usa el método releaseByIdAsync para liberar un enlace en un documento mediante la especificación de 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 este ejemplo, el primer id parámetro es el identificador del enlace para liberar.

La función anónima pasada como segundo parámetro es una devolución de llamada que se ejecuta cuando se completa la operación. La función se llama con un solo parámetro, asyncResult, que contiene el estado de la llamada.

Lectura de datos de un enlace

En el ejemplo siguiente se usa 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 Office.select para acceder al enlace por su identificador e iniciar la llamada al método getDataAsync , como sigue:

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

La función anónima pasada 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 que el valor contendrá una cadena. Para obtener ejemplos adicionales de trabajar con enlaces de matriz y tabla, consulte el tema del método getDataAsync.

Escribir datos en un enlace

En el ejemplo siguiente se usa el método setDataAsync para establecer los 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 este 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 pasada al método es una devolución de llamada que se ejecuta cuando se completa la operación. La función se llama con un solo parámetro, asyncResult, que contiene el estado del resultado.

Detectar cambios en los datos o la selección en un enlace

La función siguiente adjunta un controlador de eventos al evento DataChanged de un enlace con un identificador de "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 de 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 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, especifica el eventType parámetro de addHandlerAsync como Office.EventType.BindingSelectionChanged o "bindingSelectionChanged".

Puedes agregar varios controladores de eventos para un evento determinado llamando de nuevo a addHandlerAsync y pasando una función de controlador de eventos adicional para el handler parámetro. El nombre de cada función de controlador de eventos debe ser único.

Eliminación de un controlador de eventos

Para quitar un controlador de eventos de un evento, llame a removeHandlerAsync pasando el tipo de evento como el primer parámetro eventType y el nombre de la función del controlador de eventos que se va a quitar como el segundo parámetro de controlador . Por ejemplo, la función siguiente quita la función de controlador de dataChanged eventos agregada en el ejemplo de la sección anterior.

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

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