Associar a regiões em um documento ou em uma planilha

O acesso a dados baseados em enlaces permite que os suplementos do painel de tarefas e conteúdo acedam de forma consistente a uma determinada região de um documento ou folha de cálculo através de um identificador. Primeiro, o suplemento precisa estabelecer a associação chamando um dos métodos que vinculam uma parte do documento a um identificador exclusivo: addFromPromptAsync, addFromSelectionAsync ou addFromNamedItemAsync. Depois que a associação é estabelecida, o suplemento pode usar o identificador fornecido para acessar os dados contidos na região vinculada do documento ou da planilha. A criação de enlaces fornece o seguinte valor ao seu suplemento.

• Permite o acesso a estruturas comuns de dados em aplicativos compatíveis do Office, como: tabelas, intervalos ou texto (uma execução contígua de caracteres).
• Habilita operações de leitura/gravação sem exigir que o usuário realize uma seleção.
• Estabelece uma relação entre o suplemento e os dados presentes no documento. As associações estão presentes no documento e podem ser acessadas em um momento posterior.

A criação de uma associação também permite que você se inscreva em eventos de alteração de seleção e de dados que apresentem um escopo definido para essa região específica do documento ou da planilha. Isso significa que o suplemento só é notificado sobre alterações que ocorrem dentro da região associada, e não sobre alterações gerais que ocorrem em todo o documento ou planilha.

O objeto Bindings expõe um método getAllAsync que dá acesso ao conjunto de todos os enlaces estabelecidos no documento ou folha de cálculo. Um enlace individual pode ser acedido pelo respetivo ID através dos Enlaces. getByIdAsync method or Office.select function. Pode estabelecer novos enlaces, bem como remover os existentes através de um dos seguintes métodos do objeto Bindings : addFromSelectionAsync, addFromPromptAsync, addFromNamedItemAsync ou releaseByIdAsync.

Tipos de associação

Existem três tipos diferentes de enlaces que especifica com o parâmetro bindingType quando cria um enlace com os métodos addFromSelectionAsync, addFromPromptAsync ou addFromNamedItemAsync .

1. Enlace de Texto – vincula-se a uma região do documento que pode ser representada como texto.

   No Word, a maioria das seleções contíguas são válidas, enquanto no Excel apenas as seleções de células únicas podem ser usadas para uma associação de texto. No Excel, só há suporte para texto sem formatação. No Word, há suporte para três formatos: texto sem formatação, HTML e Open XML do Office.

2. Enlace de Matriz – vincula a uma região fixa de um documento que contém dados tabulares sem cabeçalhos. Os dados num enlace de matriz são escritos ou lidos como uma Matriz bidimensional, que em JavaScript é implementada como uma matriz de matrizes. Por exemplo, duas linhas de valores string em duas colunas podem ser gravadas ou lidas como [['a', 'b'], ['c', 'd']], e uma única coluna de três linhas pode ser gravada ou lida como [['a'], ['b'], ['c']].

   No Excel, qualquer seleção contígua de células pode ser usada para estabelecer uma associação de matriz. No Word, apenas as tabelas dão suporte à associação de matriz.

3. Enlace de Tabela – vincula a uma região de um documento que contém uma tabela com cabeçalhos. Os dados num enlace de tabela são escritos ou lidos como um objeto TableData . O TableData objeto expõe os dados através das headers propriedades e rows .

   Qualquer tabela do Excel ou Word pode ser a base para uma associação de tabela. Após estabelecer uma associação de tabelas, as linhas ou colunas novas que um usuário adicionar à tabela são automaticamente incluídas na associação.

Depois de um enlace ser criado através de um dos três métodos "addFrom" do Bindings objeto, pode trabalhar com os dados e propriedades do enlace ao utilizar os métodos do objeto correspondente: MatrixBinding, TableBinding ou TextBinding. Esses três objetos herdam os métodos getDataAsync e setDataAsync do objeto Binding, o que permite interagir com os dados associados.

Adicionar uma associação à seleção atual do usuário

O exemplo seguinte mostra como adicionar um enlace de texto chamado myBinding à seleção atual num documento com o 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; 
}

Neste exemplo, o tipo de vinculação especificado é texto. Isso significa que um TextBinding será criado para a seleção. Diferentes tipos de vinculação expõem diferentes dados e operações. Office.BindingType é uma enumeração de valores de tipos de vinculações disponíveis.

O segundo parâmetro opcional é um objeto que especifica a ID da nova vinculação que está sendo criada. Se uma ID não for especificada, uma será gerada automaticamente.

A função anónima que é transmitida ao método como o parâmetro de chamada de retorno final é executada quando a criação do enlace é concluída. A função é chamada com um único parâmetro, asyncResult, que fornece acesso a um objeto AsyncResult que fornece o status da chamada. A propriedade AsyncResult.value contém uma referência a um objeto Binding do tipo especificado para a associação recém-criada. Você pode usar esse objeto Binding para obter e definir os dados.

Adicionar uma associação a partir de um prompt

O exemplo seguinte mostra como adicionar um enlace de texto chamado myBinding com o método addFromPromptAsync . Este método permite ao usuário especificar o intervalo da vinculação usando a solicitação de seleção de intervalo interna do aplicativo.

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

Neste exemplo, o tipo de vinculação especificado é texto. Isso significa que um TextBinding será criado para a seleção que o usuário especificar no prompt.

O segundo parâmetro é um objeto que contém a ID da nova vinculação que está sendo criada. Se uma ID não for especificada, uma será gerada automaticamente.

A função anónima passou para o método como o terceiro parâmetro de chamada de retorno é executado quando a criação do enlace é concluída. Quando a função de retorno de chamada é executada, o objeto AsyncResult contém o status da chamada e a vinculação recém-criada.

A Figura 1 mostra o prompt de seleção do intervalo interno no Excel.

Figura 1. Excel Select Data UI

Adicionar uma associação a um item nomeado

O exemplo seguinte mostra como adicionar um enlace ao item nomeado existente myRange como um enlace de "matriz" com o método addFromNamedItemAsync e atribui o 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 o Excel, o itemName parâmetro do método addFromNamedItemAsync pode referir-se a um intervalo com nome existente, um intervalo especificado com o A1 estilo ("A1:A3")de referência ou uma tabela. Por padrão, a adição de uma tabela no Excel atribui o nome "Tabela1" à primeira tabela que você adicionar, "Tabela2" para a segunda tabela adicionada e assim por diante. Para atribuir um nome significativo a uma tabela na IU do Excel, utilize a Table Name propriedade nas Ferramentas de Tabela | Separador Estrutura do friso.

O exemplo seguinte cria um enlace no Excel para as primeiras três células na coluna A ( "A1:A3"), atribui o ID "MyCities"e, em seguida, escreve três nomes de cidade nesse 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 o Word, o itemName parâmetro do método addFromNamedItemAsync refere-se à Title propriedade de um Rich Text controlo de conteúdo. Não é possível associar a controles de conteúdo diferentes de controles de conteúdo Rich Text.

Por predefinição, um controlo de conteúdo não tem nenhum Title*valor atribuído. Para atribuir um nome significativo na interface do usuário do Word, depois de inserir um controle de conteúdo Rich Text do grupo Controles na guia Desenvolvedor da faixa de opções, use o comando Propriedades no grupo Controles para exibir a caixa de diálogo Propriedades de Controle de Conteúdo. Em seguida, defina a Title propriedade do controlo de conteúdo para o nome que pretende referenciar a partir do seu código.

O exemplo seguinte cria um enlace de texto no Word para um controlo de conteúdo de texto formatado com o nome "FirstName", atribui o ID"firstName" e, em seguida, apresenta essas informações.

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

Obter todas as associações

O exemplo a seguir mostra como obter todas as associações em um documento usando o 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; 
}

A função anónima que é transmitida para o método à medida que o callback parâmetro é executado quando a operação é concluída. A função é chamada com um único parâmetro, asyncResult, que contém uma matriz dos enlaces no documento. A matriz é repetida para criar uma cadeia de caracteres contendo as IDs das vinculações. A cadeia de caracteres é, então, exibida em uma caixa de mensagem.

Obter uma associação por ID usando o método getByIdAsync do objeto Bindings

O exemplo a seguir mostra como usar o método getByIdAsync para obter uma associação em um documento ao especificar sua ID. Este exemplo supõe que uma associação nomeada 'myBinding' foi adicionada ao documento usando um dos métodos descritos anteriormente neste tópico.

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

No exemplo, o primeiro id parâmetro é o ID do enlace a obter.

A função anónima que é transmitida para o método como o segundo parâmetro de chamada de retorno é executada quando a operação é concluída. A função é chamada com um único parâmetro, asyncResult, que contém o status da chamada e as vinculações com a ID "myBinding".

Obter um enlace por ID com a função select do objeto do Office

O exemplo seguinte mostra como utilizar a função Office.select para obter uma promessa de objeto enlace num documento ao especificar o respetivo ID numa cadeia de seletor. Em seguida, chama o método Binding.getDataAsync para obter dados da associação especificada. Este exemplo supõe que uma associação nomeada 'myBinding' foi adicionada ao documento usando um dos métodos descritos anteriormente neste tópico.

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

Liberar uma associação pela ID

O exemplo a seguir mostra como usar o método releaseByIdAsync para liberar uma associação em um documento, especificando sua ID.

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

No exemplo, o primeiro parâmetro id é a ID da associação a liberar.

A função anónima que é transmitida para o método como segundo parâmetro é uma chamada de retorno que é executada quando a operação é concluída. A função é chamada com um único parâmetro, asyncResult, que contém o estado da chamada.

Ler os dados de uma associação

O exemplo a seguir mostra como usar o método getDataAsync para obter dados de uma associação 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 é uma variável que contém uma associação de texto existente no documento. Como alternativa, é possível usar Office.select para acessar a associação pela ID, e iniciar sua chamada para o método getDataAsync, assim:

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

A função anónima que é transmitida para o método é uma chamada de retorno que é executada quando a operação é concluída. A propriedade AsyncResult.value contém os dados em myBinding. O tipo do valor depende do tipo de associação. A vinculação neste exemplo é uma vinculação de texto. Portanto, o valor conterá uma cadeia de caracteres. Para obter mais exemplos de como trabalhar com associações de tabela e matriz, confira o tópico do método getDataAsync.

Gravar dados em uma associação

O exemplo a seguir mostra como usar o método setDataAsync para definir os dados em uma associação existente.

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

myBinding é uma variável que contém uma associação de texto existente no documento.

No exemplo, o primeiro parâmetro é o valor a definir em myBinding. Como esta é uma associação de texto, o valor é uma string. Diferentes tipos de associação aceitam diferentes tipos de dados.

A função anónima que é transmitida para o método é uma chamada de retorno que é executada quando a operação é concluída. A função é chamada com um único parâmetro, asyncResult, que contém o estado do resultado.

Detectar alterações nos dados ou a seleção em uma associação

O exemplo a seguir mostra como anexar um manipulador de eventos ao evento DataChanged de uma associação com uma 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;
}

myBinding é uma variável que contém uma associação de texto existente no documento.

O primeiro parâmetro eventType do método addHandlerAsync especifica o nome do evento a subscrever. Office.EventType é uma enumeração de valores de tipos de eventos disponíveis. Office.EventType.BindingDataChanged avalia para a cadeia "bindingDataChanged".

A dataChanged função que é transmitida para o método como o segundo parâmetro do processador é um processador de eventos que é executado quando os dados no enlace são alterados. A função é chamada com um único parâmetro, eventArgs, que contém uma referência para a vinculação. Essa vinculação pode ser usada para recuperar os dados atualizados.

Da mesma forma, é possível detectar quando um usuário altera a seleção em uma associação ao anexar um manipulador de eventos ao evento SelectionChanged de uma associação. Para fazer isso, especifique o parâmetro eventType do método addHandlerAsync como Office.EventType.BindingSelectionChanged ou "bindingSelectionChanged".

Você pode adicionar vários manipuladores de eventos para um determinado evento chamando o método addHandlerAsync novamente e transmitindo uma função de manipulador de eventos adicional para o parâmetro handler. Isso funcionará corretamente, contanto que o nome de cada função do manipulador de eventos seja exclusivo.

Remover um manipulador de eventos

Para remover um manipulador de eventos de um evento, chame o método removeHandlerAsync ao transmitir o tipo de evento como o primeiro parâmetro eventType e o nome da função de manipulador de eventos a ser removida como o segundo parâmetro handler. Por exemplo, a função a seguir removerá a função de manipulador de eventos dataChanged adicionada no exemplo da seção anterior.

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

Confira também

• Entendendo a API de JavaScript do Office
• Programação assíncrona nos Suplementos do Office
• Ler e gravar dados para a seleção ativa em um documento ou planilha