Partager via

Obtenir et définir la périodicité des rendez-vous

Vous devez parfois créer et mettre à jour un rendez-vous périodique, par exemple une réunion hebdomadaire pour un projet d’équipe ou un rappel anniversaire annuel. Utilisez l’API JavaScript Office pour gérer les modèles de périodicité d’une série de rendez-vous dans votre complément.

Remarque

La prise en charge de cette fonctionnalité a été introduite dans l’ensemble de conditions requises 1.7. Voir les clients et les plateformes qui prennent en charge cet ensemble de conditions requises.

Périodicités

Le modèle de périodicité d’un rendez-vous est constitué d’un type de périodicité (par exemple, une périodicité quotidienne ou hebdomadaire) et de ses propriétés de périodicité applicables (par exemple, le jour du mois où le rendez-vous a lieu).

Exemple de boîte de dialogue Périodicité de rendez-vous dans Outlook.

Le tableau suivant répertorie les types de périodicité disponibles, leurs propriétés configurables et les descriptions de leur utilisation.

Type de récurrence Propriétés de récurrence valide Utilisation
daily
  • Un rendez-vous se produit tous les intervalle jours. Par exemple, un rendez-vous a lieu tous les deux jours.
weekday Aucun
  • Un rendez-vous se produit tous les jours de la semaine.
monthly
  • Un rendez-vous a lieu le jour dayOfMonth tous les mois d’intervalle . Par exemple, un rendez-vous a lieu le cinquième jour tous les quatre mois.
  • Un rendez-vous a lieu le weekNumberdayOfWeek tous les mois d’intervalle . Par exemple, un rendez-vous a lieu le troisième jeudi tous les deux mois.
weekly
  • Un rendez-vous se produit chaque jourstoutes les intervallesemaines. Par exemple, un rendez-vous a lieu le mardi et le jeudi toutes les deux semaines.
yearly
  • Un rendez-vous a lieu le jour dayOfMonth du mois tous les intervalles d’années. Par exemple, un rendez-vous a lieu le septième jour de septembre tous les quatre ans.
  • Un rendez-vous a lieu le weekNumberdayOfWeek du mois tous les intervalles d’années . Par exemple, un rendez-vous a lieu le premierjeudi de septembre tous les deux ans.

Conseil

Vous pouvez également utiliser la firstDayOfWeek propriété avec le type de weekly périodicité. Le jour spécifié commencera la liste des jours affichés dans la boîte de dialogue Récurrence.

Accéder au modèle de périodicité

Comme indiqué dans le tableau suivant, la façon dont vous accédez au modèle de périodicité et ce que vous pouvez faire avec celui-ci dépendent des éléments suivants :

  • Que vous soyez l’organisateur du rendez-vous ou un participant.
  • Que vous utilisiez le complément en mode composition ou lecture.
  • Indique si le rendez-vous actuel est une occurrence unique ou une série.
État de rendez-vous La récurrence est-elle modifiable ? La récurrence est-elle visible ?
Organisateur de rendez-vous - séries composer Oui (setAsync) Oui (getAsync)
Organisateur de rendez-vous - instance composer Non (setAsync renvoie une erreur) Oui (getAsync)
Participant rendez-vous - séries lire Non (setAsync non disponible) Oui (item.recurrence)
Participant rendez-vous - instance lire Non (setAsync non disponible) Oui (item.recurrence)
Demande de réunion - série lire Non (setAsync non disponible) Oui (item.recurrence)
Demande de réunion - instance lire Non (setAsync non disponible) Oui (item.recurrence)

Configurer la récurrence en tant qu’organisateur

Tout comme le modèle de récurrence, vous devez également déterminer les dates de début et de fin et heures de vos séries de rendez-vous. L’objet SeriesTime est utilisé pour gérer ces informations.

L’organisateur de rendez-vous peut spécifier la récurrence pour une série de rendez-vous dans le mode Composer uniquement. Dans l’exemple suivant, la série de rendez-vous est définie comme se produisant de 10 h 30 à 11 h 00 PST chaque mardi et jeudi dans la période du 2 novembre 2019 au 2 décembre 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));
});

Modifier la périodicité en tant qu’organisateur

Dans l’exemple suivant, l’organisateur de rendez-vous obtient l’objet Périodicité d’une série de rendez-vous, puis définit une nouvelle durée de périodicité. Cette opération s’effectue en mode composition.

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.");
  });
});

Obtenir la récurrence en tant qu’organisateur

Dans l’exemple suivant, l’organisateur de rendez-vous obtient l’objet Recurrence d’un rendez-vous pour déterminer s’il s’agit d’une série périodique. Cette opération s’effectue en mode composition.

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));
    }
});

L’exemple suivant montre les résultats de l’appel getAsync qui récupère la périodicité d’une série.

Remarque

Dans cet exemple, seriesTimeObject est un espace réservé pour JSON représentant la recurrence.seriesTime propriété. Vous devez utiliser les méthodes SeriesTime pour obtenir les propriétés de date et d’heure de périodicité.

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

Obtenir la récurrence en tant que participant

Dans l’exemple suivant, un participant au rendez-vous obtient l’objet Recurrence d’une demande de rendez-vous ou de réunion.

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));
    }
}

L’exemple suivant montre la valeur de la item.recurrence propriété d’une série de rendez-vous.

Remarque

Dans cet exemple, seriesTimeObject est un espace réservé pour JSON représentant la recurrence.seriesTime propriété. Vous devez utiliser les méthodes SeriesTime pour obtenir les propriétés de date et d’heure de périodicité.

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

Obtenir les détails de récurrence

Une fois que vous avez récupéré l’objet récurrence (soit à partir du getAsync rappel ou à partir de item.recurrence), vous pouvez obtenir les propriétés spécifiques de la récurrence. Par exemple, obtenez les dates et heures de début et de fin de la série à l’aide des méthodes SeriesTime sur la recurrence.seriesTime propriété .

// 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;

Identifier quand le modèle de périodicité change

Dans certains scénarios, vous souhaitez que votre complément détecte et gère les modifications apportées au modèle de périodicité d’une série. Par exemple, vous souhaitez mettre à jour l’emplacement du rendez-vous si la série est étendue. Pour implémenter cela, vous devez créer un gestionnaire pour l’événement RecurrenceChanged . Pour ajouter un gestionnaire d’événements pour l’événement RecurrenceChanged , appelez Office.context.mailbox.item.addHandlerAsync. Lorsqu’une modification est détectée, le gestionnaire d’événements reçoit un argument de type Office.RecurrenceChangedEventArgs, qui fournit l’objet de périodicité mis à jour.

L’exemple suivant montre comment inscrire un gestionnaire d’événements pour l’événement RecurrenceChanged .

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

Exécuter des exemples d’extraits de code dans Script Lab

Pour tester comment obtenir et définir la périodicité d’un rendez-vous avec un complément, installez le complément Script Lab pour Outlook et exécutez les exemples d’extraits de code suivants.

  • « Obtenir la périodicité (lecture) »
  • « Obtenir et définir la périodicité (Organisateur de rendez-vous) »

Pour en savoir plus sur Script Lab, consultez Explorer l’API JavaScript Office à l’aide de Script Lab.

L’exemple d’extrait de code de périodicité dans Script Lab.

Voir aussi