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".

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.

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.