Ler e gravar dados na seleção ativa em um documento ou em uma planilha

Aprenda a ler e escrever a seleção atual do usuário com Document.getSelectedDataAsync e Document.setSelectedDataAsync. Os exemplos incluem um snippet baseado em retorno de chamada e um wrapper Promise/async moderno para que você possa usar async/await.

• Quando usar isto: edições rápidas e temporárias na seleção do usuário (como uma área de transferência), interações leves ou atualizações imediatas da interface do usuário. Use uma associação quando precisar de persistência entre as sessões.
• Aplica-se a: Word e Excel (o comportamento difere de acordo com o host — veja as notas do host mais tarde). Para diferenças entre Web e Área de Trabalho, teste em plataformas compatíveis.
• APIs principais: Office.context.document.getSelectedDataAsync, Office.context.document.setSelectedDataAsync, Office.EventType.DocumentSelectionChanged.

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 and 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 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) {
        // Failure handling: Show the error message in the UI.
        write('Action failed. Error: ' + asyncResult.error.message);
    }
    else {
        // Success: `asyncResult.value` contains the selected text.
        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 é avaliada como a cadeia de caracteres "texto".

Saída esperada: grava o texto selecionado no elemento da página com messageid .

A função anônima que é passada para o método como o segundo parâmetro, 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 error 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 é avaliada como a cadeia de caracteres "Falhou" (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 "Olá, Mundo!".

Office.context.document.setSelectedDataAsync("Hello World!", function (asyncResult) {
    if (asyncResult.status === Office.AsyncResultStatus.Failed) {
        // Show the error message if the call fails.
        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 objeto para o parâmetro data terá resultados diferentes. O resultado depende do que está selecionado no documento, qual aplicativo cliente do Office está hospedando seu suplemento e se os dados passados podem ser forçados para a 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.

Saída esperada: A seleção atual no documento é substituída pelo texto "Olá, Mundo!" (se a seleção e o host dão suporte à inserção de texto).

Promessa Moderna / wrapper assíncrono

Se você preferir async/await, use um pequeno wrapper de promessa em torno das APIs de retorno de chamada. Exemplos de wrappers:

function getSelectedDataAsyncWithPromise(coercionType) {
    return new Promise((resolve, reject) => {
        Office.context.document.getSelectedDataAsync(coercionType, (result) => {
            if (result.status === Office.AsyncResultStatus.Failed) reject(result.error);
            else resolve(result.value);
        });
    });
}

function setSelectedDataAsyncWithPromise(data) {
    return new Promise((resolve, reject) => {
        Office.context.document.setSelectedDataAsync(data, (result) => {
            if (result.status === Office.AsyncResultStatus.Failed) reject(result.error);
            else resolve();
        });
    });
}

// Usage with async/await.
async function example() {
    try {
        const text = await getSelectedDataAsyncWithPromise(Office.CoercionType.Text);
        console.log('Selected:', text);
        await setSelectedDataAsyncWithPromise(text + ' (processed)');
    } catch (err) {
        console.error(err.message || err);
    }
}

Para obter mais informações, consulte Encapsular APIs comuns em funções de retorno de promessa.

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){
    // `eventArgs` contains a `document` reference when available.
    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 no qual se inscrever. Passar a cadeia de caracteres "documentSelectionChanged" para esse parâmetro é equivalente a transmitir 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, handler, é um manipulador 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.

Observações do aplicativo host: No Excel, os eventos de alteração de seleção geralmente se referem a intervalos de pasta de trabalho (use tipos de coerção de matriz ou tabela). No Word, os eventos de seleção são focados em texto ou conteúdo. Teste os manipuladores de eventos nos hosts compatíveis com seu suplemento.

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.

Solução de problemas

• Seleção vazia: nada será retornado se o usuário não tiver nenhuma seleção. Verifique e solicite que o usuário selecione o conteúdo.
• Incompatibilidade de coerção: use o coercionType correto (text, matrix, table, html) para os dados esperados.
• Limitações do host: Alguns hosts podem não permitir certas coerções. Confira Office.CoercionType para obter detalhes.
• Permissões: verifique se o manifesto do suplemento tem as permissões apropriadas para as APIs que você usa.

Próximas etapas

Para dados persistentes entre sessões, consulte Associar a regiões em um documento ou planilha. Outros tópicos úteis: autenticação, tempos de execução e exemplos específicos do aplicativo.