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

Use uma associação quando seu suplemento precisar de acesso confiável a uma região específica de uma pasta de trabalho do Excel ou documento do Word. Uma associação associa a região a uma ID exclusiva, para que o suplemento possa retornar a ela depois que o usuário alterar sua seleção ou reabrir o documento.

Com uma associação, seu suplemento pode:

• Acessar estruturas de dados comuns, como tabelas, intervalos ou texto.
• Leia e grave dados sem exigir que o usuário selecione a região primeiro.
• Monitore as alterações de dados e seleção na região associada.
• Mantenha a relação entre as sessões porque a associação é salva com o documento.

Escolha o tipo de associação correto

O Office dá suporte a três tipos de associação. Escolha um tipo com base na região e nos dados que o suplemento precisa ler ou gravar.

Especifique o tipo com o bindingType parâmetro ao criar uma associação usando addFromSelectionAsync, addFromPromptAsync ou addFromNamedItemAsync.

Associação de texto

Uma associação de texto representa uma região do documento como texto.

No Word, a maioria das seleções contíguas funciona. No Excel, somente seleções de célula única podem usar a associação de texto. O Excel dá suporte apenas a texto sem formatação, enquanto o Word dá suporte a três formatos: texto sem formatação, HTML e Open XML para Office.

Associação de matriz

Uma associação de matriz representa uma região fixa de dados tabulares sem cabeçalhos.

Ler ou gravar dados de matriz como bidimensionais Array (uma matriz de matrizes em JavaScript). Por exemplo, duas linhas de string valores em duas colunas são semelhantes a [['a', 'b'], ['c', 'd']], e uma única coluna de três linhas é semelhante a [['a'], ['b'], ['c']].

No Excel, qualquer seleção contígua de células funciona para a vinculação de matrizes. No Word, apenas as tabelas dão suporte à associação de matriz.

Associação de tabelas

Uma associação de tabela representa uma tabela com cabeçalhos.

Os dados em uma associação de tabela são lidos ou gravados como um objeto TableData . O TableData objeto expõe dados por meio das headers propriedades and rows .

Qualquer tabela do Excel ou Word pode ser a base para uma associação de tabela. Depois de estabelecer uma associação de tabela, novas linhas ou colunas que os usuários adicionam à tabela são automaticamente incluídas na associação.

Depois de criar uma associação com um dos três métodos "addFrom", você pode trabalhar com os dados e as propriedades da associação usando o objeto correspondente: MatrixBinding, TableBinding ou TextBinding. Todos os três objetos herdam os métodos getDataAsync e setDataAsync do Binding objeto para interagir com dados associados.

Criar uma associação a partir da seleção atual

O exemplo a seguir adiciona uma associação de texto chamada myBinding à seleção atual usando 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 associação é texto, portanto, um TextBinding é criado para a seleção. Diferentes tipos de vinculação expõem diferentes dados e operações. Office.BindingType é uma enumeração dos tipos de associação disponíveis.

O segundo parâmetro opcional especifica a ID da nova associação. Se você não especificar uma ID, uma será gerada automaticamente.

A função anônima passada como o parâmetro de retorno de chamada final é executada quando a criação da associação é concluída. A função recebe um único parâmetro, asyncResult, que fornece acesso a um objeto AsyncResult com o status da chamada. A AsyncResult.value propriedade 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.

Criar uma associação a partir de um prompt

A função a seguir adiciona uma associação de texto chamada myBinding usando o método addFromPromptAsync . Esse método permite que os usuários especifiquem o intervalo para a associação usando o prompt de seleção de intervalo interno 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 associação é texto, portanto, um TextBinding é criado para a seleção do usuário no prompt.

O segundo parâmetro contém a ID da nova associação. Se você não especificar uma ID, uma será gerada automaticamente.

A função anônima passada como o terceiro parâmetro de retorno de chamada é executada quando a criação da associação é concluída. Quando a função de retorno de chamada é executada, o objeto AsyncResult contém o status da chamada e a associação recém-criada.

A captura de tela a seguir mostra o prompt de seleção de intervalo interno no Excel.

Adicionar uma associação a um item nomeado

A função a seguir adiciona uma associação ao item nomeado existente myRange como uma associação de "matriz" usando o método addFromNamedItemAsync e atribui a associação 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 de addFromNamedItemAsync refere-se a um intervalo nomeado existente, um intervalo especificado com estilo de referência A1 ("A1:A3") ou uma tabela. Por padrão, o Excel atribui os nomes "Tabela1" para a primeira tabela, "Tabela2" para a segunda tabela e assim por diante. Para atribuir um nome significativo a uma tabela na interface do usuário do Excel, use a propriedade Nome da Tabela nas Ferramentas de Tabela | Guia Design .

A função a seguir cria uma associação no Excel para as três primeiras células na coluna A ("A1:A3"), atribui a ID "MyCities"e grava três nomes de cidade nessa associação.

 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 Title Word, o itemName parâmetro de addFromNamedItemAsync refere-se à propriedade de um Rich Text controle de conteúdo. Não é possível associar a controles de conteúdo diferentes de controles de conteúdo Rich Text.

Por padrão, um controle 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, use o comando Propriedades no grupo Controles para exibir a caixa de diálogo Propriedades do Controle de Conteúdo. Em seguida, defina a Title propriedade do controle de conteúdo como o nome que você deseja referenciar do seu código.

A função a seguir cria uma associação de texto no Word a um controle de conteúdo de rich text chamado "FirstName", atribui a ID"firstName" e exibe 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 obtém todas as associações em um documento usando o 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;
}

A função anônima passada como o parâmetro é executada callback quando a operação é concluída. A função é chamada com um único parâmetro, asyncResult, que contém uma matriz de associações 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 getByIdAsync

O exemplo a seguir usa o método getByIdAsync para obter uma associação em um documento especificando sua ID. Este exemplo pressupõe que uma associação nomeada 'myBinding' foi adicionada ao documento usando um dos métodos descritos anteriormente neste artigo.

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

Neste exemplo, o primeiro id parâmetro é a ID da associação a ser recuperada.

A função anônima passada como o segundo parâmetro de retorno de chamada é 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 a associação com a ID "myBinding".

Obter uma associação por ID usando Office.select

O exemplo a seguir usa a função Office.select para obter uma promessa de objeto Binding em um documento especificando sua ID em uma cadeia de caracteres do seletor. Em seguida, ele chama o método getDataAsync para obter dados da associação especificada. Este exemplo pressupõe que uma associação nomeada 'myBinding' foi adicionada ao documento usando um dos métodos descritos anteriormente neste artigo.

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

Se a select promessa de função retornar com êxito um objeto Binding , esse objeto exporá apenas os quatro métodos a seguir: getDataAsync, setDataAsync, addHandlerAsync e removeHandlerAsync. Se a promessa não puder retornar um objeto Binding, o retorno de onError chamada poderá ser usado para acessar um objeto asyncResult.error para obter mais informações. Se você precisar chamar um membro do objeto Binding diferente dos quatro métodos expostos pela promessa do objeto Binding retornada pela select função, use o método getByIdAsync usando a propriedade Document.bindings e o método getByIdAsync para recuperar o objeto Binding .

Liberar uma associação pela ID

O exemplo a seguir usa 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;
}

Neste exemplo, o primeiro id parâmetro é a ID da associação a ser liberada.

A função anônima passada como o segundo parâmetro é um retorno de chamada que é executado quando a operação é concluída. A função é chamada com um único parâmetro, asyncResult, que contém o status da chamada.

Ler os dados de uma associação

O exemplo a seguir usa 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, você pode usar Office.select para acessar a associação por sua ID e iniciar sua chamada para o método getDataAsync , da seguinte maneira:

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

A função anônima passada para o método é um retorno de chamada que é executado 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 associação neste exemplo é uma associaçã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 usa o método setDataAsync para definir 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.

Neste exemplo, o primeiro parâmetro é o valor a ser definido 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 passada para o método é um retorno de chamada que é executado quando a operação é concluída. A função é chamada com um único parâmetro, asyncResult, que contém o status do resultado.

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

A função a seguir anexa um manipulador de eventos ao evento DataChanged de uma associação com uma ID 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;
}

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

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

A dataChanged função passada como o segundo parâmetro do manipulador é um manipulador de eventos que é executado quando os dados na associação 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 vinculação anexando um manipulador de eventos ao evento SelectionChanged de uma vinculação. Para fazer isso, especifique o eventType parâmetro de addHandlerAsync como Office.EventType.BindingSelectionChanged ou "bindingSelectionChanged".

Você pode adicionar vários manipuladores de eventos para um determinado evento chamando addHandlerAsync novamente e passando uma função de manipulador de eventos adicional para o handler parâmetro. O nome de cada função de manipulador de eventos deve ser exclusivo.

Remover um manipulador de eventos

Para remover um manipulador de eventos de um evento, chame removeHandlerAsync passando o tipo de evento como o primeiro parâmetro eventType e o nome da função do manipulador de eventos a ser removida como o segundo parâmetro do manipulador . Por exemplo, a função a seguir remove a dataChanged função de manipulador de eventos 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