Compartilhar via

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 de fim de um compromisso que está a ser composto. Estes métodos assíncronos só estão disponíveis para compor suplementos. Para utilizar estes métodos, certifique-se de que configurou o manifesto apenas de suplemento do suplemento adequadamente para o Outlook ativar os formulários de composição do suplemento, 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;

No entanto, num formulário de composição, uma vez que tanto o utilizador como o suplemento podem estar a inserir ou a alterar a hora ao mesmo tempo, tem de utilizar o método assíncrono getAsync para obter a hora de início ou de fim.

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

Tal como acontece com a maioria dos métodos assíncronos na API getAsync JavaScript do Office e setAsync utilize parâmetros de entrada opcionais. Para obter mais informações sobre como especificar estes parâmetros de entrada opcionais, consulte "Transmitir parâmetros opcionais para métodos assíncronos" em Programação assíncrona nos Suplementos do Office.

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

Esta secção mostra um exemplo de código que obtém a hora de início do compromisso a ser composto e apresenta a hora. Pode utilizar o mesmo código, mas substituir a start propriedade pela end propriedade para obter a hora de fim.

Para utilizar os item.start.getAsync métodos ou item.end.getAsync , forneça uma função de chamada de retorno que verifica o estado e o resultado da chamada assíncrona. Obtenha o estado, os resultados e qualquer erro com o parâmetro de saída asyncResult da chamada de retorno. Se a chamada assíncrona for bem-sucedida, utilize a asyncResult.value propriedade para obter a hora de início como um Date objeto no formato UTC. Para fornecer os argumentos necessários à função de chamada de retorno, utilize 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 secção mostra um exemplo de código que define a hora de início de um compromisso a ser composto. Pode utilizar o mesmo código, mas substituir a start propriedade pela end propriedade para definir a hora de fim. Tenha em atenção que as alterações às start propriedades ou end podem afetar outras propriedades do compromisso que está a ser composto.

  • Se o compromisso que está a ser composto já tiver uma hora de início existente, definir a hora de início posteriormente ajusta a hora de fim para manter qualquer duração anterior do compromisso.
  • Se o compromisso que está a ser composto já tiver uma hora de fim existente, definir a hora de fim posteriormente ajusta a duração e a hora de fim.
  • Se o compromisso tiver sido definido como um evento para todo o dia, definir a hora de início ajusta a hora de fim para 24 horas mais tarde e desmarca a caixa de verificação do evento para todo o dia no compromisso.

Para utilizar item.start.setAsync ou item.end.setAsync, especifique um objeto formatado em Date UTC no dateTime parâmetro . Se receber uma data com base numa entrada do utilizador no cliente, pode utilizar mailbox.convertToUtcClientTime para converter o valor num Date objeto no formato UTC. Se fornecer uma função de chamada de retorno opcional, inclua o asyncContext parâmetro e adicione argumentos à mesma. Além disso, verifique o estado, o resultado e qualquer mensagem de erro através do asyncResult parâmetro de saída da chamada de retorno. Se a chamada assíncrona for bem-sucedida, setAsync insere a cadeia de hora de início ou de fim especificada como texto simples, substituindo qualquer hora de início ou de fim existente para esse item.

Observação

No Outlook clássico no Windows, o setAsync método não pode ser utilizado para alterar a hora de início ou de fim de um compromisso periódico.

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