毎週のチーム プロジェクトの進捗会議や毎年の誕生日通知など、定期的な予定の作成や更新が必要な場合があります。 Office JavaScript API を使用して、アドイン内の予定シリーズの繰り返しパターンを管理します。
注:
この機能のサポートは 、要件セット 1.7 で導入されました。 この要件セットをサポートする クライアントおよびプラットフォーム を参照してください。
繰り返しパターン
予定の定期的なパターンは、定期的な種類 (毎日または毎週の 繰り返 しなど) と、その適用可能な 繰り返しプロパティ (予定が発生した月の日など) で構成されます。
次の表に、使用可能な繰り返しの種類、構成可能なプロパティ、使用状況の説明を示します。
定期的なパターン | 有効な定期的なアイテムのプロパティ | 使用方法 |
---|---|---|
daily |
|
|
weekday |
なし |
|
monthly |
|
|
weekly |
|
|
yearly |
|
ヒント
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
プロパティの値を示しています。
注:
この例では、seriesTimeObject
は recurrence.seriesTime
プロパティを表す JSON のプレースホルダーです。
SeriesTime メソッドを使用して、繰り返しの日付と時刻のプロパティを取得する必要があります。
{
"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 を探索する」を参照してください。
関連項目
Office Add-ins