予定の繰り返しを取得して設定する

2025-06-18

毎週のチームプロジェクトの進捗会議や毎年の誕生日通知など、定期的な予定の作成や更新が必要な場合があります。 Office JavaScript API を使用して、アドイン内の予定シリーズの繰り返しパターンを管理します。

注:

この機能のサポートは、要件セット 1.7 で導入されました。この要件セットをサポートするクライアントおよびプラットフォームを参照してください。

繰り返しパターン

予定の定期的なパターンは、定期的な種類 (毎日または毎週の繰り返しなど) と、その適用可能な繰り返しプロパティ (予定が発生した月の日など) で構成されます。

Outlook の [予定の繰り返し] ダイアログのサンプル。

次の表に、使用可能な繰り返しの種類、構成可能なプロパティ、使用状況の説明を示します。

定期的なパターン	有効な定期的なアイテムのプロパティ	使用方法
`daily`	`interval`	interval 日に一度、予定が発生する。たとえば、予定は 2 日ごとに発生します。
`weekday`	なし	予定が平日に毎日発生する。
`monthly`	`interval` `dayOfMonth` `dayOfWeek` `weekNumber`	予定は、1 か月ごとに dayOfMonth 日に発生します。たとえば、予定は 4 か月ごとに 5 日目に行われます。予定は、月ごとに weekNumberdayOfWeek に発生します。たとえば、予定は 2 か月ごとに第 3 木曜日に行われます。
`weekly`	`interval` `days`	予定が interval 週間に一度、days に発生する。たとえば、2 週間ごとに火曜日と木曜日に予定が発生します。
`yearly`	`interval` `dayOfMonth` `dayOfWeek` `weekNumber` `month`	予定は、各間隔年の日日OfMonthに発生します。たとえば、予定は 4 年ごとに 9 月7 日に行われます。予定は、年ごとに月の weekNumberdayOfWeek に発生します。たとえば、予定は 2 年ごとに 9 月の最初の木曜日に行われます。

ヒント

weekly の定期的なパターンで firstDayOfWeek プロパティを使用することもできます。指定された日は定期的なアイテムのダイアログに表示された日にちのリストを開始させます。

定期的なパターンにアクセスする

次の表に示すように、繰り返しパターンにアクセスする方法と、それに対して実行できる操作は、次の内容によって異なります。

予定の開催者か出席者か。
新規作成モードまたは読み取りモードでアドインを使用しているかどうか。
現在の予定が単一の予定であるか、系列であるか。

予定の状態	編集可能な定期的なアイテムですか。	表示可能な定期的なアイテムですか。
予定の開催者 - 定期的な予定を作成する	はい (`setAsync`)	はい (`getAsync`)
予定の開催者 - インスタンスを作成する	いいえ (`setAsync` がエラーを返します)	はい (`getAsync`)
予定の出席者 - 定期的な予定を確認する	いいえ (`setAsync` が使用不可)	はい (`item.recurrence`)
予定の出席者 - インスタンスを読む	いいえ (`setAsync` が使用不可)	はい (`item.recurrence`)
会議出席依頼 - 定期的な予定を確認する	いいえ (`setAsync` が使用不可)	はい (`item.recurrence`)
会議出席依頼 - インスタンスを確認する	いいえ (`setAsync` が使用不可)	はい (`item.recurrence`)

定期的なアイテムを開催者として設定する

定期的なパターンを使用するには、定期的な予定の開始日時、終了日時も決定する必要があります。 SeriesTime オブジェクトは、その情報を管理するために使用されます。

予定の開催者は、作成モードでのみ、定期的な予定のパターンを指定できます。次の例では、2019 年 11 月 2 日から 2019 年 12 月 2 日の期間中に、毎週火曜日と木曜日の、午前 10 時 30 分から午前 11 時 00 分 (米国太平洋標準時) に発生する定期的な予定が設定されています。

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

開催者として繰り返しを変更する

次の例では、予定の開催者が予定の系列の Recurrence オブジェクトを取得し、新しい繰り返し期間を設定します。これは作成モードで行われます。

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

定期的なアイテムを開催者として取得する

次の例では、予定の開催者が予定の Recurrence オブジェクトを取得して、定期的な系列であるかどうかを判断します。これは作成モードで行われます。

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

次の例は、系列の繰り返しを取得する getAsync 呼び出しの結果を示しています。

注:

この例では、seriesTimeObject は recurrence.seriesTime プロパティを表す JSON のプレースホルダーです。 SeriesTime メソッドを使用して、繰り返しの日付と時刻のプロパティを取得する必要があります。

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

定期的なアイテムを出席者として取得する

次の例では、予定の出席者は、予定または会議出席依頼の Recurrence オブジェクトを取得します。

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

次の例は、予定系列の item.recurrence プロパティの値を示しています。

注:

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

定期的なアイテムの詳細を取得する

(getAsync コールバックまたは item.recurrence のいずれかから) 繰り返しオブジェクトを取得した後、特定の定期的なアイテムのプロパティを表示できます。たとえば、recurrence.seriesTime プロパティの SeriesTime メソッドを使用して、系列の開始日と終了日時を取得します。

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

繰り返しパターンが変更されたタイミングを特定する

アドインで、系列の繰り返しパターンの変更を検出して処理するシナリオが存在する場合があります。たとえば、系列が拡張されている場合は、予定の場所を更新します。これを実装するには、 RecurrenceChanged イベントのハンドラーを作成する必要があります。 RecurrenceChanged イベントのイベントハンドラーを追加するには、Office.context.mailbox.item.addHandlerAsync を呼び出します。変更が検出されると、イベントハンドラーは Office.RecurrenceChangedEventArgs 型の引数を受け取り、更新された繰り返しオブジェクトを提供します。

次の例は、 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.
}

Script Labでサンプルスニペットを実行する

アドインを使用して予定の繰り返しを取得して設定する方法をテストするには、Outlook アドインのScript Labをインストールし、次のサンプルスニペットを実行します。

"繰り返しの取得 (読み取り)"
"繰り返しの取得と設定 (予定オーガナイザー)"

Script Lab の詳細については、「Script Lab を使用して Office JavaScript API を探索する」を参照してください。

Script Labの繰り返しサンプルスニペット。

次の方法で共有