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 tal, 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 só funciona com a seleção atual do utilizador. 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 (também pode especificar este parâmetro utilizando a cadeia "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 para a cadeia "texto".

A função anónima que é transmitida para o método como o segundo parâmetro, chamada de retorno, é 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 error do AsyncResult objeto fornece acesso ao objeto Erro . 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 dos valores de propriedade disponíveis AsyncResult.status . Office.AsyncResultStatus.Failed avalia para a cadeia "falhou" (e, mais uma vez, também pode ser especificado como essa cadeia 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 transmissão de diferentes tipos de objetos para o parâmetro de dados terá resultados diferentes. O resultado depende do que está atualmente selecionado no documento, qual a aplicação cliente do Office que está a alojar o seu suplemento e se os dados transmitidos 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 escreve dados na seleção com o setSelectedDataAsync método , o parâmetro asyncResult da chamada de retorno fornece acesso apenas ao status da chamada e ao objeto Erro 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 a subscrever. Transmitir a cadeia "documentSelectionChanged" para este parâmetro é equivalente a transmitir o Office.EventType.DocumentSelectionChanged tipo de evento da enumeração Office.EventType .

A myHandler() função que é transmitida para o método como o segundo parâmetro, processador, é um processador de eventos que é 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 é transmitido como o segundo parâmetro, processador, especifica o processador de eventos que será removido do SelectionChanged evento.