Ler e gravar dados na seleção ativa em um documento ou em uma planilha
O objeto Document expõe métodos que permitem ler e gravar a seleção atual do usuário em um documento ou uma planilha. Para fazer isso, o Document objeto fornece os getSelectedDataAsync métodos e setSelectedDataAsync . Este tópico também descreve como ler, gravar e criar manipuladores de eventos para detectar alterações na seleção do usuário.
O getSelectedDataAsync método funciona apenas na seleção atual do usuário. Se você precisar persistir a seleção no documento de forma que a mesma seleção esteja disponível para ler e gravar entre sessões de execução do suplemento, adicione uma associação usando o métodoBindings.addFromSelectionAsync (ou crie uma associação com um dos outros métodos "addFrom" do objeto Bindings). Para saber mais sobre como criar uma associação a uma região de um documento e a leitura e a gravação em uma associação, confira Associar a regiões em um documento ou uma planilha.
Ler dados selecionados
O exemplo a seguir mostra como obter dados de uma seleção em um documento usando o método getSelectedDataAsync.
Office.context.document.getSelectedDataAsync(Office.CoercionType.Text, function (asyncResult) {
if (asyncResult.status == Office.AsyncResultStatus.Failed) {
write('Action failed. Error: ' + asyncResult.error.message);
}
else {
write('Selected data: ' + asyncResult.value);
}
});
// Function that writes to a div with id='message' on the page.
function write(message){
document.getElementById('message').innerText += message;
}
Neste exemplo, o primeiro parâmetro, coercionType, é especificado como Office.CoercionType.Text (você também pode especificar esse parâmetro usando a cadeia de caracteres "text"literal ). Isso significa que a propriedade value do objeto AsyncResult, que está disponível por meio do parâmetro asyncResult na função de retorno de chamada, retorne uma string que contenha o texto selecionado no documento. A especificação de tipos diferentes de coerção resulta em valores diferentes. Office.CoercionType é uma enumeração dos valores de tipos de coerção disponíveis. Office.CoercionType.Text avalia a cadeia de caracteres "text".
Dica
Quando devo usar a matriz ou a tabela coercionType para o acesso aos dados? Se você precisar de seus dados tabulares selecionados para crescer dinamicamente quando linhas e colunas forem adicionadas e trabalhar com cabeçalhos de tabela, use o tipo de dados de tabela (especificando o parâmetro coercionType do getSelectedDataAsync método como "table" ou Office.CoercionType.Table). A adição de linhas e colunas na estrutura de dados tem suporte nos dados de tabela e matriz, mas o acréscimo de linhas e colunas só tem suporte para dados de tabela. Se você não estiver planejando adicionar linhas e colunas e seus dados não exigirem funcionalidade de cabeçalho, use o tipo de dados de matriz (especificando o parâmetro coercionType do getSelectedDataAsync método como "matrix" ou Office.CoercionType.Matrix), que fornece um modelo mais simples de interação com os dados.
A função anônima que é passada para o método como o segundo parâmetro, o retorno de chamada, é executada quando a getSelectedDataAsync operação é concluída. A função é chamada com um único parâmetro, asyncResult, que contém o resultado e o status da chamada. Se a chamada falhar, a propriedade de erro do AsyncResult objeto fornecerá acesso ao objeto Error . Você pode verificar o valor das propriedades Error.name e Error.message para determinar por quê a operação set falhou. Caso contrário, o texto selecionado no documento é exibido.
A propriedade AsyncResult.status é usada na instrução if para testar se a chamada foi bem-sucedida. Office.AsyncResultStatus é uma enumeração de valores de propriedade disponíveis AsyncResult.status . Office.AsyncResultStatus.Failed avalia a cadeia de caracteres "falha" (e, novamente, também pode ser especificada como essa cadeia de caracteres literal).
Gravar dados na seleção
O exemplo a seguir mostra como definir a seleção para mostrar "Hello World!".
Office.context.document.setSelectedDataAsync("Hello World!", function (asyncResult) {
if (asyncResult.status == Office.AsyncResultStatus.Failed) {
write(asyncResult.error.message);
}
});
// Function that writes to a div with id='message' on the page.
function write(message){
document.getElementById('message').innerText += message;
}
A passagem de diferentes tipos de objeto para o parâmetro de dados terá resultados diferentes. O resultado depende do que está selecionado atualmente no documento, qual aplicativo cliente do Office está hospedando seu suplemento e se os dados passados podem ser coagidos à seleção atual.
A função anônima passada para o método setSelectedDataAsync como o parâmetro callback é executada quando a chamada assíncrona é concluída. Quando você grava dados na seleção usando o setSelectedDataAsync método, o parâmetro asyncResult do retorno de chamada fornece acesso apenas ao status da chamada e ao objeto Error se a chamada falhar.
Detectar alterações na seleção
O exemplo a seguir mostra como detectar alterações na seleção usando o método Document.addHandlerAsync para adicionar um manipulador de eventos ao evento SelectionChanged no documento.
Office.context.document.addHandlerAsync("documentSelectionChanged", myHandler, function(result){}
);
// Event handler function.
function myHandler(eventArgs){
write('Document Selection Changed');
}
// Function that writes to a div with id='message' on the page.
function write(message){
document.getElementById('message').innerText += message;
}
O primeiro parâmetro, eventType, especifica o nome do evento ao qual assinar. Passar a cadeia de caracteres "documentSelectionChanged" para esse parâmetro é equivalente a passar o Office.EventType.DocumentSelectionChanged tipo de evento da enumeração Office.EventType .
A myHandler() função que é passada para o método como o segundo parâmetro, manipulador, é um manipulador de eventos executado quando a seleção é alterada no documento. A função é chamada com um único parâmetro, eventArgs, que conterá uma referência a um objeto DocumentSelectionChangedEventArgs quando a operação assíncrona for concluída. Você pode usar a propriedade DocumentSelectionChangedEventArgs.document para acessar o documento que gerou o evento.
Observação
Você pode adicionar vários manipuladores de eventos para um determinado evento chamando o addHandlerAsync método novamente e passando uma função de manipulador de eventos adicional para o parâmetro do manipulador . This will work correctly as long as the name of each event handler function is unique.
Parar de detectar alterações na seleção
O exemplo a seguir mostra como deixar de ouvir o evento Document.SelectionChanged chamando o método document.removeHandlerAsync.
Office.context.document.removeHandlerAsync("documentSelectionChanged", {handler:myHandler}, function(result){});
O myHandler nome da função que é passado como o segundo parâmetro, manipulador, especifica o manipulador de eventos que será removido do SelectionChanged evento.
Importante
Se o parâmetro de manipulador opcional for omitido quando o removeHandlerAsync método for chamado, todos os manipuladores de eventos do eventType especificado serão removidos.