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

Os enlaces permitem que o seu suplemento aceda consistentemente a regiões específicas de um documento ou folha de cálculo. Pense num enlace como um marcador que memoriza uma localização específica, mesmo que os utilizadores alterem a seleção ou naveguem para outro local no documento. Especificamente, eis os enlaces que oferecem o seu suplemento.

• Aceda a estruturas de dados comuns em aplicações do Office suportadas, como tabelas, intervalos ou texto.
• Ler e escrever dados sem exigir que os utilizadores efetuem uma seleção primeiro.
• Crie relações persistentes entre o suplemento e os dados do documento. Os enlaces são guardados com o documento e funcionam entre sessões.

Para criar um enlace, chame um destes métodos de objeto Enlaces para associar uma região de documento a um identificador exclusivo: addFromPromptAsync, addFromSelectionAsync ou addFromNamedItemAsync. Depois de estabelecer o enlace, utilize o respetivo identificador para ler ou escrever nessa região em qualquer altura.

Também pode subscrever eventos de alteração de dados e seleção para regiões vinculadas específicas. Isto significa que o suplemento só é notificado sobre as alterações na área vinculada e não sobre todo o documento.

Escolher o tipo de enlace correto

O Office suporta três tipos diferentes de enlaces. Especifique o tipo com o parâmetro bindingType ao criar um enlace com addFromSelectionAsync, addFromPromptAsync ou addFromNamedItemAsync.

Enlace de Texto

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

No Word, as seleções mais contíguas funcionam. No Excel, apenas as seleções de célula única podem utilizar o enlace de texto. O Excel suporta apenas texto simples, enquanto Word suporta três formatos: texto simples, HTML e Open XML para o Office.

Enlace de Matriz

Enlace de Matriz – vincula-se a uma região fixa que contém dados tabulares sem cabeçalhos.

Os dados num enlace de matriz são lidos ou escritos como uma Matriz bidimensional (uma matriz de matrizes em JavaScript). Por exemplo, duas linhas de valores de cadeia em duas colunas seriam semelhantes [['a', 'b'], ['c', 'd']]a e uma única coluna de três linhas seria [['a'], ['b'], ['c']].

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

Enlace de Tabela

Enlace de Tabela – vincula-se a uma região do documento que contém uma tabela com cabeçalhos.

Os dados num enlace de tabela são lidos ou escritos 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. Depois de estabelecer um enlace de tabela, as novas linhas ou colunas que os utilizadores adicionam à tabela são incluídas automaticamente no enlace.

Depois de criar um enlace com um dos três métodos "addFrom", pode trabalhar com os dados e propriedades do enlace com o objeto correspondente: MatrixBinding, TableBinding ou TextBinding. Os três objetos herdam os métodos getDataAsync e setDataAsync do Binding objeto para interagir com dados vinculados.

Criar um enlace a partir da seleção atual

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

O segundo parâmetro opcional especifica o ID do novo enlace. Se não especificar um ID, um é gerado automaticamente.

A função anónima transmitida como o parâmetro de chamada de retorno final é executada quando a criação do enlace é 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 De enlace do tipo especificado para o enlace recentemente criado. Você pode usar esse objeto Binding para obter e definir os dados.

Criar um enlace a partir de uma linha de comandos

A função seguinte adiciona um enlace de texto chamado myBinding com o método addFromPromptAsync . Este método permite que os utilizadores especifiquem o intervalo para o enlace com o pedido de seleção de intervalo incorporado da aplicação.

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 enlace é texto, pelo que é criado um TextBinding para a seleção do utilizador na linha de comandos.

O segundo parâmetro contém o ID do novo enlace. Se não especificar um ID, um é gerado automaticamente.

A função anónima passou à medida que o terceiro parâmetro de chamada de retorno é executado quando a criação do enlace está concluída. Quando a função de chamada de retorno é executada, o objeto AsyncResult contém o status da chamada e o enlace recentemente criado.

A seguinte captura de ecrã mostra o pedido de seleção de intervalo incorporado no Excel.

Adicionar uma associação a um item nomeado

A função seguinte adiciona 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 de addFromNamedItemAsync refere-se a um intervalo com nome existente, um intervalo especificado com estilo de referência A1 ("A1:A3") ou uma tabela. Por predefinição, o Excel atribui os nomes "Table1" à primeira tabela, "Tabela2" para a segunda tabela e assim sucessivamente. Para atribuir um nome significativo a uma tabela na IU do Excel, utilize a propriedade Nome da Tabela nas Ferramentas de Tabela | Separador Estrutura .

A função 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 Word, o itemName parâmetro de 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 IU do Word, depois de inserir um controlo de conteúdo RtF a partir do grupo Controlos no separador Programador, utilize o comando Propriedades no grupo Controlos para apresentar a caixa de diálogo Propriedades do Controlo 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.

A função seguinte cria um enlace de texto no Word a 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 seguinte obtém todos os enlaces num documento com 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 transmitida à medida que o callback parâmetro é executado quando a operação está 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 um enlace por ID com getByIdAsync

O exemplo seguinte utiliza o método getByIdAsync para obter um enlace num documento ao especificar o respetivo ID. Este exemplo pressupõe que foi adicionado um enlace com o nome 'myBinding' ao documento através de 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 é o ID do enlace a obter.

A função anónima passou à medida que o segundo parâmetro de chamada de retorno é executado quando a operação é concluída. A função é chamada com um único parâmetro, asyncResult, que contém o status da chamada e o enlace com o ID "myBinding".

Obter um enlace por ID com Office.select

O exemplo seguinte utiliza 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 getDataAsync para obter dados do enlace especificado. Este exemplo pressupõe que foi adicionado um enlace com o nome 'myBinding' ao documento através de 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 promessa da select função devolver com êxito um objeto Enlace , esse objeto expõe apenas os quatro métodos seguintes: getDataAsync, setDataAsync, addHandlerAsync e removeHandlerAsync. Se a promessa não conseguir devolver um objeto De enlace, a onError chamada de retorno pode ser utilizada para aceder a um objeto asyncResult.error para obter mais informações. Se precisar de chamar um membro do objeto Enlace para além dos quatro métodos expostos pela promessa de objeto enlace devolvida pela select função, utilize o método getByIdAsync com a propriedade Document.bindings e o método getByIdAsync para obter o objeto Binding .

Liberar uma associação pela ID

O exemplo seguinte utiliza o método releaseByIdAsync para libertar um enlace num documento ao especificar o respetivo 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 é o ID do enlace a libertar.

A função anónima transmitida como segundo parâmetro é uma chamada de retorno que é executada quando a operação está 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 seguinte utiliza o método getDataAsync para obter dados de um 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 é uma variável que contém uma associação de texto existente no documento. Em alternativa, pode utilizar o Office.select para aceder ao enlace através do respetivo ID e iniciar a chamada para o método getDataAsync , da seguinte forma:

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

A função anónima transmitida para o método é uma chamada de retorno que é executada quando a operação está concluída. A propriedade AsyncResult.value contém os dados em myBinding. O tipo do valor depende do tipo de associação. O enlace neste exemplo é um enlace de texto, pelo que o valor irá conter uma cadeia. 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 seguinte utiliza o método setDataAsync para definir dados num enlace 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 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 transmitida para o método é uma chamada de retorno que é executada quando a operação está concluída. A função é chamada com um único parâmetro, asyncResult, que contém o status do resultado.

Detetar alterações aos dados ou à seleção num enlace

A função seguinte anexa um processador de eventos ao evento DataChanged de um enlace com um 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 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 transmitida 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 vinculação anexando um manipulador de eventos ao evento SelectionChanged de uma vinculação. Para tal, especifique o eventType parâmetro addHandlerAsync como Office.EventType.BindingSelectionChanged ou "bindingSelectionChanged".

Pode adicionar vários processadores de eventos para um determinado evento ao chamar addHandlerAsync novamente e ao transmitir uma função de processador de eventos adicional para o handler parâmetro . O nome de cada função de processador de eventos tem de ser exclusivo.

Remover um manipulador de eventos

Para remover um processador de eventos para um evento, chame removeHandlerAsync transmitindo o tipo de evento como o primeiro parâmetro eventType e o nome da função de processador de eventos a remover como o segundo parâmetro do processador . Por exemplo, a função seguinte remove a função de dataChanged processador de eventos adicionada no exemplo da secçã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