Obter ou definir a hora ao compor um compromisso no Outlook

  • Artigo

A API JavaScript do Office fornece métodos assíncronos (Time.getAsync e Time.setAsync) para obter e definir a hora de início ou término de um compromisso que está sendo composto. Esses métodos assíncronos estão disponíveis apenas para compor suplementos. Para usar esses métodos, certifique-se de ter configurado o manifesto XML do suplemento adequadamente para o Outlook para ativar o suplemento em formulários de composição, conforme descrito em Criar suplementos do Outlook para formulários de composição.

As propriedades start e end estão disponíveis para compromissos tanto em formulários de composição quanto de leitura. No formulário de leitura, você pode acessar as propriedades diretamente do objeto pai, como em:

Office.context.mailbox.item.start;
Office.context.mailbox.item.end;

Mas em um formulário de composição, porque o usuário e seu suplemento podem estar inserindo ou alterando a hora ao mesmo tempo, você deve usar o getAsync método assíncrono para obter a hora de início ou de término.

Office.context.mailbox.item.start.getAsync(callback);
Office.context.mailbox.item.end.getAsync(callback);

Como acontece com a maioria dos métodos assíncronos na API getAsync JavaScript do Office e setAsync use parâmetros de entrada opcionais. Para obter mais informações sobre como especificar esses parâmetros de entrada opcionais, confira "Passando parâmetros opcionais para métodos assíncronos" na programação assíncrona nos Suplementos do Office.

Obter a hora de início ou de término

Esta seção mostra um exemplo de código que obtém a hora de início do compromisso que está sendo composto e exibe a hora. Você pode usar o mesmo código, mas substituir a start propriedade pela end propriedade para obter a hora de término.

Para usar os item.start.getAsync métodos ouitem.end.getAsync, forneça uma função de retorno de chamada que verifica o status e o resultado da chamada assíncrona. Obtenha o status, os resultados e qualquer erro usando o parâmetro de saída asyncResult do retorno de chamada. Se a chamada assíncrona for bem-sucedida, use a asyncResult.value propriedade para obter a hora de início como um Date objeto no formato UTC. Para fornecer os argumentos necessários para a função de retorno de chamada, use o asyncContext parâmetro opcional da getAsync chamada.

let item;

// Confirms that the Office.js library is loaded.
Office.onReady((info) => {
    if (info.host === Office.HostType.Outlook) {
        item = Office.context.mailbox.item;
        getStartTime();
    }
});

// Gets the start time of the appointment being composed.
function getStartTime() {
    item.start.getAsync((asyncResult) => {
        if (asyncResult.status === Office.AsyncResultStatus.Failed) {
            write(asyncResult.error.message);
            return;
        }

        // Display the start time in UTC format on the page.
        write(`The start time in UTC is: ${asyncResult.value.toString()}`);
        // Convert the start time to local time and display it on the page.
        write(`The start time in local time is: ${asyncResult.value.toLocaleString()}`);
    });
}

// Writes to a div with id="message" on the page.
function write(message) {
    document.getElementById("message").innerText += message;
}

Definir a hora de início ou de término

Esta seção mostra um exemplo de código que define a hora de início de um compromisso que está sendo composto. Você pode usar o mesmo código, mas substituir a start propriedade pela end propriedade para definir o horário de término. Observe que alterações nas start propriedades ou end podem afetar outras propriedades do compromisso que está sendo composto.

  • Se o compromisso que está sendo composto já tiver um horário de início existente, definir o horário de início posteriormente ajustará o horário de término para manter qualquer duração anterior do compromisso.
  • Se o compromisso que está sendo composto já tiver um tempo de término existente, definir o horário de término posteriormente ajustará a duração e o tempo de término.
  • Se o compromisso tiver sido definido como um evento durante todo o dia, definir a hora de início ajustará o horário de término para 24 horas depois e limpará a caixa de seleção do evento durante todo o dia no compromisso.

Para usar item.start.setAsync ou item.end.setAsync, especifique um objeto formatado por Date UTC no dateTime parâmetro. Se você conseguir uma data com base em uma entrada do usuário no cliente, poderá usar mailbox.convertToUtcClientTime para converter o valor em um Date objeto no formato UTC. Se você fornecer uma função opcional de retorno de chamada, inclua o asyncContext parâmetro e adicione quaisquer argumentos a ele. Além disso, marcar o status, o resultado e qualquer mensagem de erro por meio do asyncResult parâmetro de saída do retorno de chamada. Se a chamada assíncrona for bem-sucedida, setAsync insira a cadeia de caracteres de início ou hora de término especificada como texto sem formatação, substituindo qualquer hora de início ou término existente para esse item.

Observação

No Outlook no Windows, o setAsync método não pode ser usado para alterar o horário de início ou término de um compromisso recorrente.

let item;

// Confirms that the Office.js library is loaded.
Office.onReady((info) => {
    if (info.host === Office.HostType.Outlook) {
        item = Office.context.mailbox.item;
        setStartTime();
    }
});

// Sets the start time of the appointment being composed.
function setStartTime() {
    // Get the current date and time, then add two days to the date.
    const startDate = new Date();
    startDate.setDate(startDate.getDate() + 2);

    item.start.setAsync(
        startDate,
        { asyncContext: { optionalVariable1: 1, optionalVariable2: 2 } },
        (asyncResult) => {
            if (asyncResult.status === Office.AsyncResultStatus.Failed) {
                console.log(asyncResult.error.message);
                return;
            }

            console.log("Successfully set the start time.");
            /*
                Run additional operations appropriate to your scenario and
                use the optionalVariable1 and optionalVariable2 values as needed.
            */
        });
}

Confira também