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

项目
08/17/2023

Office JavaScript API 提供异步方法 (Time.getAsync 和 Time.setAsync) 来获取和设置正在撰写的约会的开始或结束时间。这些异步方法仅适用于撰写加载项。若要使用这些方法，请确保已为 Outlook 适当地设置加载项的仅加载项清单，以激活撰写窗体中的外接程序，如为撰写窗体创建 Outlook 外接程序中所述。

start 和 end 属性对撰写和阅读窗体中的约会均适用。在阅读窗体中，您可以直接从父对象访问属性，类似于：

Office.context.mailbox.item.start;
Office.context.mailbox.item.end;

但在撰写窗体中，由于用户和加载项可以同时插入或更改时间，因此必须使用 getAsync 异步方法来获取开始或结束时间。

Office.context.mailbox.item.start.getAsync(callback);
Office.context.mailbox.item.end.getAsync(callback);

与 Office JavaScript API 中的大多数异步方法一样， getAsync 采用 setAsync 可选的输入参数。有关如何指定这些可选输入参数的详细信息，请参阅 Office 外接程序中的异步编程中的“将可选参数传递给异步方法”。

获取开始或结束时间

本部分演示一个代码示例，该示例获取正在撰写的约会的开始时间并显示时间。可以使用相同的代码，但将属性end替换为 start 属性以获取结束时间。

若要使用 item.start.getAsync 或 item.end.getAsync 方法，请提供一个回调函数，用于检查异步调用的状态和结果。使用回调的 asyncResult 输出参数获取状态、结果和任何错误。如果异步调用成功，请使用 asyncResult.value 属性以 UTC 格式作为 Date 对象获取开始时间。若要向回调函数提供任何必需的参数，请使用 asyncContext 调用的 getAsync 可选参数。

let item;

// Confirms that the Office.js library is loaded.
Office.onReady((info) => {
    if (info.host === Office.HostType.Outlook) {
        item = Office.context.mailbox.item;
        getStartTime();
    }
});

// Gets the start time of the appointment being composed.
function getStartTime() {
    item.start.getAsync((asyncResult) => {
        if (asyncResult.status === Office.AsyncResultStatus.Failed) {
            write(asyncResult.error.message);
            return;
        }

        // Display the start time in UTC format on the page.
        write(`The start time in UTC is: ${asyncResult.value.toString()}`);
        // Convert the start time to local time and display it on the page.
        write(`The start time in local time is: ${asyncResult.value.toLocaleString()}`);
    });
}

// Writes to a div with id="message" on the page.
function write(message) {
    document.getElementById("message").innerText += message;
}

设置开始或结束时间

本部分演示一个代码示例，该示例设置正在撰写的约会的开始时间。可以使用相同的代码，但将属性end替换为 start 属性来设置结束时间。请注意， start 对或 end 属性的更改可能会影响正在撰写的约会的其他属性。

如果正在撰写的约会已有一个开始时间，则设置开始时间随后会调整结束时间，以保持约会以前的任何持续时间。
如果正在撰写的约会已有结束时间，则设置结束时间随后会同时调整持续时间和结束时间。
如果约会已设置为全天事件，则设置开始时间会将结束时间调整为 24 小时后，并清除约会中全天事件的复选框。

若要使用 item.start.setAsync 或 item.end.setAsync，请在参数中dateTime指定 UTC 格式Date的对象。如果根据用户在客户端中的输入获取日期，则可以使用 mailbox.convertToUtcClientTime 将值转换为 Date UTC 格式的对象。如果提供可选的回调函数，请包含 asyncContext 参数并向其添加任何参数。此外，通过 asyncResult 回调的输出参数检查状态、结果和任何错误消息。如果异步调用成功， setAsync 则以纯文本形式插入指定的开始或结束时间字符串，覆盖该项目的任何现有开始或结束时间。

注意

在经典 Outlook on Windows 中， setAsync 方法不能用于更改定期约会的开始或结束时间。

let item;

// Confirms that the Office.js library is loaded.
Office.onReady((info) => {
    if (info.host === Office.HostType.Outlook) {
        item = Office.context.mailbox.item;
        setStartTime();
    }
});

// Sets the start time of the appointment being composed.
function setStartTime() {
    // Get the current date and time, then add two days to the date.
    const startDate = new Date();
    startDate.setDate(startDate.getDate() + 2);

    item.start.setAsync(
        startDate,
        { asyncContext: { optionalVariable1: 1, optionalVariable2: 2 } },
        (asyncResult) => {
            if (asyncResult.status === Office.AsyncResultStatus.Failed) {
                console.log(asyncResult.error.message);
                return;
            }

            console.log("Successfully set the start time.");
            /*
                Run additional operations appropriate to your scenario and
                use the optionalVariable1 and optionalVariable2 values as needed.
            */
        });
}

通过

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

获取开始或结束时间

设置开始或结束时间

另请参阅

其他资源