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

Los enlaces permiten que el complemento acceda de forma coherente a regiones específicas de un documento o hoja de cálculo. Piense en un enlace como un marcador que recuerde una ubicación específica, incluso si los usuarios cambian su selección o navegan por otro lugar del documento. En concreto, estos son los enlaces que ofrecen el complemento.

• Acceda a estructuras de datos comunes en las aplicaciones de Office admitidas, como tablas, intervalos o texto.
• Leer y escribir datos sin necesidad de que los usuarios realicen primero una selección.
• Cree relaciones persistentes entre el complemento y los datos del documento. Los enlaces se guardan con el documento y funcionan entre sesiones.

Para crear un enlace, llame a uno de estos métodos de objeto Bindings para asociar una región del documento con un identificador único: addFromPromptAsync, addFromSelectionAsync o addFromNamedItemAsync. Una vez que haya establecido el enlace, use su identificador para leer o escribir en esa región en cualquier momento.

También puede suscribirse a eventos de cambio de datos y selección para regiones enlazadas específicas. Esto significa que el complemento solo recibe una notificación sobre los cambios en el área enlazada, no sobre todo el documento.

Elija el tipo de enlace correcto.

Office admite tres tipos diferentes de enlaces. El tipo se especifica con el parámetro bindingType al crear un enlace mediante addFromSelectionAsync, addFromPromptAsync o addFromNamedItemAsync.

Enlace de texto

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

En Word, la mayoría de las selecciones contiguas funcionan. En Excel, solo las selecciones de celdas únicas 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 para Office.

Enlace de matriz

Enlace de matriz : se enlaza a una región fija que contiene datos tabulares sin encabezados.

Los datos de un enlace de matriz se leen o escriben como una matriz bidimensional (una matriz de matrices en JavaScript). Por ejemplo, dos filas de valores de cadena en dos columnas serían similares [['a', 'b'], ['c', 'd']]a y una sola columna de tres filas sería [['a'], ['b'], ['c']].

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

Enlace de tabla

Enlace de tabla : enlaza a una región de documento que contiene 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 y 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 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 datos enlazados.

Creación de 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 distintos tipos de enlace exponen diferentes datos y operaciones. Office.BindingType es una enumeración de tipos de enlace disponibles.

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

La función anónima pasada como el 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.

Creación de un enlace a partir de un símbolo del sistema

La siguiente función agrega un enlace de texto llamado myBinding mediante el método addFromPromptAsync . Este método permite a los usuarios especificar el intervalo para el enlace mediante el símbolo del sistema de selección de intervalos 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 el símbolo del sistema.

El segundo parámetro contiene el identificador del nuevo enlace. Si no especifica un identificador, se genera 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 el símbolo del sistema de selección de rango integrado en Excel.

Adición de un enlace a un elemento con nombre

La siguiente función agrega 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 de addFromNamedItemAsync hace referencia a un rango con nombre existente, un rango especificado con el estilo de referencia A1 ("A1:A3") o una tabla. De forma predeterminada, Excel asigna los nombres "Table1" para la primera tabla, "Table2" para la segunda tabla, etc. Para asignar un nombre significativo a una tabla en la interfaz de usuario de Excel, use la propiedad Nombre de tabla en herramientas de tabla | Pestaña Diseño .

La función siguiente crea un enlace en Excel a las tres primeras celdas de la columna A ("A1:A3"), asigna el identificador "MyCities"y, a continuación, escribe 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; 
}

Por 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 Desarrollador, 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.

La función siguiente crea un enlace de texto en Word a un control de contenido de texto enriquecido denominado "FirstName", asigna el identificador"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 se ejecuta el callback parámetro 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 identificador mediante getByIdAsync

En el ejemplo siguiente se usa el método getByIdAsync para obtener un enlace en un documento especificando su identificador. En este ejemplo se supone que se agregó un enlace denominado 'myBinding' 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. 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 Office.select

En el ejemplo siguiente se usa la función Office.select para obtener una promesa de objeto Binding en un documento especificando su identificador en una cadena de selector. A continuación, llama al método getDataAsync para obtener datos del enlace especificado. En este ejemplo se supone que se agregó un enlace denominado 'myBinding' 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 expone solo 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 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 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 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 este ejemplo, el primer id parámetro es el identificador del enlace que se va a 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. 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 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, podría usar Office.select para acceder al enlace por su identificador e iniciar la llamada al método getDataAsync , de la siguiente 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 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 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 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 la selección en un enlace

La siguiente función asocia 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 pasada 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 eventType parámetro addHandlerAsync como Office.EventType.BindingSelectionChanged o "bindingSelectionChanged".

Puede 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 para un evento, llame a removeHandlerAsync pasando el tipo de evento como primer parámetro eventType y el nombre de la función de controlador de eventos que se va a quitar como segundo parámetro de controlador . Por ejemplo, la siguiente función quita la función de dataChanged controlador de 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