获取和设置约会的重复周期

有时候，你需要创建和更新某个定期约会，例如团队项目的每周状态会议或每年生日提醒。 使用 Office JavaScript API 管理外接程序中约会系列的重复模式。

定期模式

约会的定期模式由 定期类型 (（例如每日或每周重复) ）组成，其适用的 定期属性 (例如，约会发生) 的月份日期。

下表列出了可用的定期类型、其可配置属性及其用法说明。

访问重复周期模式

如下表所示，如何访问重复模式以及可以使用该模式执行的作取决于：

• 你是约会组织者还是与会者。
• 无论你是在撰写模式还是阅读模式下使用加载项。
• 当前约会是单个事件还是系列。

以组织者身份设置定期

除了定期模式之外，你还需要确定约会系列的开始和结束日期和时间。 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 重复周期的调用的结果。

{
    "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）之后，可以获取定期的特定属性。 例如，通过使用 属性上的 SeriesTime 方法 recurrence.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 探索 Office JavaScript API。

另请参阅

• 在 Outlook 中撰写约会时获取或设置时间
• 在 Outlook 中撰写约会时获取或设置位置