Compartilhar via

Obter e definir a periodicidade dos compromissos

Às vezes, você precisa criar e atualizar um compromisso recorrente, como uma reunião de status semanal para um projeto da equipe ou um lembrete anual de aniversário. Utilize a API JavaScript do Office para gerir os padrões de periodicidade de uma série de compromissos no seu suplemento.

Observação

O suporte para esta funcionalidade foi introduzido no conjunto de requisitos 1.7. Confira, clientes e plataformas que oferecem suporte a esse conjunto de requisitos.

Padrões de recorrência

O padrão de periodicidade de um compromisso é constituído por um tipo de periodicidade (por exemplo, periodicidade diária ou semanal) e as respetivas propriedades de periodicidade aplicáveis (por exemplo, o dia do mês em que ocorre o compromisso).

Uma caixa de diálogo Compromisso Periódico de exemplo no Outlook.

A tabela seguinte lista os tipos de periodicidade disponíveis, as respetivas propriedades configuráveis e descrições da respetiva utilização.

Tipo de recorrência Propriedades válidas das recorrências Uso
daily
  • Um compromisso ocorre a cada interval (intervalo) de dias. Por exemplo, um compromisso ocorre de dois em dois dias.
weekday Nenhum
  • Um compromisso ocorre todos os dias úteis.
monthly
  • Um compromisso ocorre no diaOfMonth a cada mês de intervalo . Por exemplo, um compromisso ocorre no quinto dia a cada quatro meses.
  • Um compromisso ocorre na semanaNumberdayOfWeek a cada mês de intervalo . Por exemplo, um compromisso ocorre na terceira quinta-feira a cada dois meses.
weekly
  • Ocorre um compromisso nos days (dias) a cada interval (intervalo) de semanas. Por exemplo, um compromisso ocorre às terças e quintas-feiras de duas em duas semanas.
yearly
  • Um compromisso ocorre em dayOfMonth of month todos os anos de intervalo . Por exemplo, uma nomeação ocorre no sétimo dia de setembro a cada quatro anos.
  • Um compromisso ocorre na semanaNumberdayOfWeek do mês em todos os anos de intervalo . Por exemplo, uma nomeação ocorre na primeiraquinta-feira de setembro de dois em dois anos.

Dica

Você também pode usar a propriedade firstDayOfWeek com o tipo de recorrência weekly. O dia especificado iniciará a lista de dias exibidos na caixa de diálogo de recorrência.

Aceder ao padrão de periodicidade

Conforme mostrado na tabela seguinte, a forma como acede ao padrão de periodicidade e o que pode fazer com o mesmo depende de:

  • Quer seja o organizador do compromisso ou um participante.
  • Quer esteja a utilizar o suplemento no modo de composição ou leitura.
  • Se o compromisso atual é uma única ocorrência ou uma série.
Estado do compromisso A recorrência é editável? A recorrência é visível?
Organizador de compromisso – redigir a série Sim (setAsync) Sim (getAsync)
Organizador de compromisso – redigir a instância Não (setAsync retorna um erro) Sim (getAsync)
Participante de compromisso – ler a série Não (setAsync não está disponível) Sim (item.recurrence)
Participante de compromisso – ler a instância Não (setAsync não está disponível) Sim (item.recurrence)
Solicitação de reunião – ler a série Não (setAsync não está disponível) Sim (item.recurrence)
Solicitação de reunião – ler a instância Não (setAsync não está disponível) Sim (item.recurrence)

Definir recorrência como o organizador

Com o padrão de recorrência, também é necessário determinar os horários e as datas de início e término da série de compromissos. O objeto SeriesTime é utilizado para gerir essas informações.

O organizador de compromisso só pode especificar o padrão de recorrência para uma série de compromissos no modo de redação. No exemplo a seguir, a série de compromissos está definida para ocorrer das 10:30 às 11:00 toda terça-feira e quinta-feira durante o período de 2 de novembro de 2019 a 2 de dezembro de 2019.

const seriesTimeObject = new Office.SeriesTime();
seriesTimeObject.setStartDate(2019,10,2);
seriesTimeObject.setEndDate(2019,11,2);
seriesTimeObject.setStartTime(10,30);
seriesTimeObject.setDuration(30);

const pattern = {
    seriesTime: seriesTimeObject,
    recurrenceType: Office.MailboxEnums.RecurrenceType.Weekly,
    recurrenceProperties:
    {
        interval: 1,
        days: [Office.MailboxEnums.Days.Tue, Office.MailboxEnums.Days.Thu]
    },
    recurrenceTimeZone: { name: Office.MailboxEnums.RecurrenceTimeZone.PacificStandardTime }
};

Office.context.mailbox.item.recurrence.setAsync(pattern, (asyncResult) => {
    console.log(JSON.stringify(asyncResult));
});

Alterar periodicidade como organizador

No exemplo seguinte, o organizador do compromisso obtém o objeto Periodicidade de uma série de compromissos e, em seguida, define uma nova duração de periodicidade. Isto é feito no modo de composição.

Office.context.mailbox.item.recurrence.getAsync((asyncResult) => {
  const recurrencePattern = asyncResult.value;
  recurrencePattern.seriesTime.setDuration(60);
  Office.context.mailbox.item.recurrence.setAsync(recurrencePattern, (asyncResult) => {
    if (asyncResult.status === Office.AsyncResultStatus.Failed) {
      console.log("Failed to set recurrence.");
      return;
    }

    console.log("Successfully set recurrence.");
  });
});

Obter recorrência como o organizador

No exemplo seguinte, o organizador do compromisso obtém o Recurrence objeto de um compromisso para determinar se é uma série periódica. Isto é feito no modo de composição.

Office.context.mailbox.item.recurrence.getAsync((asyncResult) => {
    const recurrence = asyncResult.value;

    if (recurrence == null) {
        console.log("Non-recurring meeting.");
    } else {
        console.log(JSON.stringify(recurrence));
    }
});

O exemplo seguinte mostra os resultados da getAsync chamada que obtém a periodicidade de uma série.

Observação

Neste exemplo, seriesTimeObject é um espaço reservado para o JSON que representa a propriedade recurrence.seriesTime. Deve utilizar os métodos SeriesTime para obter as propriedades de data e hora de periodicidade.

{
    "recurrenceType": "weekly",
    "recurrenceProperties": {
        "interval": 1,
        "days": ["tue","thu"],
        "firstDayOfWeek": "sun"},
    "seriesTime": {seriesTimeObject},
    "recurrenceTimeZone": {
        "name": "Pacific Standard Time",
        "offset": -480}}

Obter recorrência como um participante

No exemplo seguinte, um participante do compromisso obtém o Recurrence objeto de um compromisso ou pedido de reunião.

outputRecurrence(Office.context.mailbox.item);

function outputRecurrence(item) {
    const recurrence = item.recurrence;

    if (recurrence == null) {
        console.log("Non-recurring meeting.");
    } else {
        console.log(JSON.stringify(recurrence));
    }
}

O exemplo seguinte mostra o valor da item.recurrence propriedade de uma série de compromissos.

Observação

Neste exemplo, seriesTimeObject é um espaço reservado para o JSON que representa a propriedade recurrence.seriesTime. Deve utilizar os métodos SeriesTime para obter as propriedades de data e hora de periodicidade.

{
    "recurrenceType": "weekly",
    "recurrenceProperties": {
        "interval": 1,
        "days": ["tue","thu"],
        "firstDayOfWeek": "sun"},
    "seriesTime": {seriesTimeObject},
    "recurrenceTimeZone": {
        "name": "Pacific Standard Time",
        "offset": -480}}

Obter os detalhes de recorrência

Depois que você recuperou o objeto de recorrência (seja do retorno de chamada de getAsync ou de item.recurrence), é possível obter as propriedades específicas da recorrência. Por exemplo, obtenha as datas e horas de início e de fim da série com os métodos SeriesTime na recurrence.seriesTime propriedade .

// Get the date and time information of the series.
const seriesTime = recurrence.seriesTime;
const startTime = recurrence.seriesTime.getStartTime();
const endTime = recurrence.seriesTime.getEndTime();
const startDate = recurrence.seriesTime.getStartDate();
const endDate = recurrence.seriesTime.getEndDate();
const duration = recurrence.seriesTime.getDuration();

// Get the series time zone.
const timeZone = recurrence.recurrenceTimeZone;

// Get the recurrence properties.
const recurrenceProperties = recurrence.recurrenceProperties;

// Get the recurrence type.
const recurrenceType = recurrence.recurrenceType;

Identificar quando o padrão de periodicidade é alterado

Podem existir cenários em que pretende que o suplemento detete e processe alterações ao padrão de periodicidade de uma série. Por exemplo, gostaria de atualizar a localização do compromisso se a série for expandida. Para implementar isto, tem de criar um processador para o evento RecurrenceChanged . Para adicionar um processador de eventos para o RecurrenceChanged evento, ligue para Office.context.mailbox.item.addHandlerAsync. Quando é detetada uma alteração, o processador de eventos recebe um argumento do tipo Office.RecurrenceChangedEventArgs, que fornece o objeto de periodicidade atualizado.

O exemplo seguinte mostra como registar um processador de eventos para o RecurrenceChanged evento.

// This sample shows how to register an event handler in Outlook.
Office.onReady(() => {
    // Register an event handler to identify when the recurrence pattern of a series is updated.
    Office.context.mailbox.item.addHandlerAsync(Office.EventType.RecurrenceChanged, handleEvent, (asyncResult) => {
        if (asyncResult.status === Office.AsyncResultStatus.Failed) {
            console.log(asyncResult.error.message);
            return;
        }

        console.log("Event handler added for the RecurrenceChanged event.");
    });
});

function handleEvent(event) {
    // Get the updated recurrence object.
    const updatedRecurrence = event.recurrence;

    // Perform operations in response to the updated recurrence pattern.
}

Executar fragmentos de exemplo no Script Lab

Para testar como obter e definir a periodicidade de um compromisso com um suplemento, instale o suplemento Script Lab para Outlook e execute os seguintes fragmentos de exemplo.

  • "Obter periodicidade (Leitura)"
  • "Obter e definir periodicidade (Organizador de Compromissos)"

Para saber mais sobre o Script Lab, consulte Explorar a API JavaScript do Office usando o Script Lab.

O fragmento de exemplo de periodicidade no Script Lab.

Confira também