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

Saiba como ler e escrever a seleção atual do utilizador com Document.getSelectedDataAsync e Document.setSelectedDataAsync. Os exemplos incluem um fragmento baseado na chamada de retorno e um wrapper Promise/async moderno para que possa utilizar assíncrona/aguardar.

• Quando utilizar isto: edições rápidas e temporárias à seleção do utilizador (semelhante à área de transferência), interações leves ou atualizações imediatas da IU. Utilize um enlace quando precisar de persistência entre sessões.
• Aplica-se a: Word e Excel (o comportamento difere consoante o anfitrião — consulte as notas do anfitrião mais tarde). Para diferenças na Web versus no ambiente de trabalho, teste em plataformas suportadas.
• APIs principais: Office.context.document.getSelectedDataAsync, , Office.context.document.setSelectedDataAsyncOffice.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 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) {
        // 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 (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".

Resultado esperado: escreve o texto selecionado no elemento da página com o ID message.

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) {
        // 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 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.

Resultado esperado: a seleção atual no documento é substituída pelo texto "Olá, Mundo!" (se a seleção e o anfitrião suportarem a inserção de texto).

Modern Promise /async wrapper

Se preferir assíncrona/aguarda, utilize um pequeno wrapper Promise em torno das APIs de chamada de retorno. Wrappers de exemplo:

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, veja Moldar APIs Comuns em funções que devolvem promessas.

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

Notas da aplicação anfitriã: no Excel, os eventos de alteração de seleção são frequentemente sobre intervalos de livros (utilizar tipos de coerção de matriz ou tabela). No Word, os eventos de seleção são focados no texto ou no conteúdo. Teste os processadores de eventos nos anfitriões suportados pelo 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 é transmitido como o segundo parâmetro, processador, especifica o processador de eventos que será removido do SelectionChanged evento.

Solução de problemas

• Seleção vazia: nada é devolvido se o utilizador não tiver seleção. Verifique e peça ao utilizador para selecionar conteúdo.
• Erro de correspondência de coerção: utilize o coercionType correto (text, matrix, table, html) para os dados esperados.
• Limitações do anfitrião: alguns anfitriões podem não permitir determinadas coerções. Consulte Office.CoercionType para obter detalhes.
• Permissões: certifique-se de que o manifesto do suplemento tem as permissões adequadas para as APIs que utiliza.

Próximas etapas

Para obter dados persistentes em todas as sessões, veja Vincular a regiões num documento ou folha de cálculo. Outros tópicos úteis: autenticação, runtimes e exemplos específicos da aplicação.