Office JavaScript API 使用 JavaScript Date 对象进行大部分日期和时间的存储和检索。
对象 Date 提供 getUTCDate、 getUTCHour、 getUTCMinutes 和 toUTCString 等方法，这些方法根据世界协调时 (UTC) 时间返回请求的日期或时间值。
它还提供 getDate、 getHour、 getMinutes 和 toString 等其他方法，这些方法根据“本地时间”返回请求的日期或时间。
“本地时间”概念很大程度上取决于客户端计算机上的浏览器和操作系统。 例如，在基于 Windows 的客户端计算机上运行的大多数浏览器上，对 的 JavaScript 调用 getDate将返回基于客户端计算机上 Windows 中设置的时区的日期。
以下示例创建 myLocalDate，它是本地时间的 对象 Date ，并调用 toUTCString 以将该日期转换为 UTC 中的日期字符串。
// Create and get the current date represented
// in the client computer time zone.
const myLocalDate = new Date ();
// Convert the Date value in the client computer time zone
// to a date string in UTC, and display the string.
document.write ("The current UTC time is " +
myLocalDate.toUTCString());
虽然可以使用 JavaScript Date 对象获取基于 UTC 或客户端计算机时区的日期或时间值， Date 但对象在一个方面受到限制 - 它不提供返回任何其他特定时区的日期或时间值的方法。 例如，如果客户端计算机设置为东部Standard时间 (EST) ，则没有Date方法允许获取除 EST 或 UTC 以外的小时值，例如太平洋时间Standard (PST) 。
Outlook 加载项的日期相关功能
当你使用 Office JavaScript API 处理在 Outlook on Windows (新 (经典) 、Mac、Web 或移动设备上运行的加载项中的日期或时间值时，上述 JavaScript 限制将影响你。
Outlook 客户端的时区
为清楚起见，让我们先定义要讨论的时区。
| 时区 | 说明 |
|---|---|
| 客户端计算机时区 | 这在客户端计算机的操作系统上设置。 大多数浏览器使用客户端计算机时区来显示 JavaScript Date 对象的日期或时间值。Outlook on Windows (经典) 和 Outlook on Mac 使用此时区在用户界面中显示日期或时间值。 例如，在运行 Windows 的客户端计算机上，经典 Outlook 使用 Windows 上设置的时区作为本地时区。 在 Mac 上，如果用户更改客户端计算机上的时区，Outlook on Mac 也会提示用户更新 Outlook 中的时区。 |
| Exchange 管理中心 (EAC) 时区 | 当用户首次登录到Outlook 网页版、新 Outlook on Windows 或移动设备时， (和首选语言) 设置此时区值。 Outlook 网页版，新的 Outlook on Windows 和移动设备使用此时区在用户界面中显示日期或时间值。 |
由于 Windows 上的 Outlook (经典) 和 Mac 版 Outlook 使用客户端计算机时区，并且 Outlook 网页版、Windows 上的新 Outlook 和移动设备的用户界面使用 EAC 时区，因此在同一邮箱上安装的同一外接程序的本地时间可能会有所不同，具体取决于 Outlook 客户端运行的平台。 作为 Outlook 外接程序开发人员，您应该正确输入和输出日期值，以便那些值始终与用户期望的相应客户端上的时区保持一致。
日期相关的 API
以下是 Office JavaScript API 中支持日期相关功能的属性和方法。
| API 成员 | 时区表示 | Outlook 网页版、新 Windows 客户端和移动设备中的示例 | Outlook on Windows (经典) 和 Mac 中的示例 |
|---|---|---|---|
| Office.context.mailbox.userProfile.timeZone | 在 Outlook on Windows (经典) 和 Outlook on Mac 中，此属性返回客户端计算机时区。 在 Outlook 网页版、移动设备和新的 Outlook on Windows 中，此属性返回 EAC 时区。 | PST | EST |
| Office.context.mailbox.item.dateTimeCreated 和 Office.context.mailbox.item.dateTimeModified | 其中每个属性都返回一个 JavaScript Date 对象。 此值Date是 UTC 正确的，如以下示例所示 - myUTCDate 在Outlook 网页版、Windows (新 (和经典) 、Mac 和移动设备上具有相同的值。const myDate = Office.mailbox.item.dateTimeCreated;const myUTCDate = myDate.getUTCDate;但是，调用 myDate.getDate 将返回客户端计算机时区中的日期值，该时区与用于在 Windows 上的 Outlook (经典) 和 Mac 界面中显示日期时间值的时区一致，但可能不同于在移动设备上Outlook 网页版 EAC 时区，以及在其用户界面中使用的新 Outlook on Windows 时区。 |
如果项目是在 UTC 上午 9 点创建的：Office.mailbox.item.dateTimeCreated.getHours 返回 4am EST。如果在 UTC 上午 11 点修改了该项： Office.mailbox.item.dateTimeModified.getHours 返回 6am EST。请注意，如果您想要在用户界面中显示创建或修改时间，要首先将时间转换为 PST 以与用户界面的其余部分保持一致。 |
如果项目创建时间是 UTC 上午 9 点：Office.mailbox.item.
dateTimeCreated.getHours 返回 EST 凌晨 4 点。如果在 UTC 上午 11 点修改了该项： Office.mailbox.item.
dateTimeModified.getHours 返回 EST 上午 6 点。 |
| Office.context.mailbox.displayNewAppointmentForm |
start每个 和 end 参数都需要一个 JavaScript Date 对象。 无论Outlook 网页版用户界面、Windows (新 (经典) 、Mac 或移动设备上使用的时区，参数都应是 UTC 正确的。 |
如果约会表单的开始和结束时间为 UTC 上午 9 点和 11 点 UTC，则应确保 start 和 end 参数为 UTC 正确，这意味着：
|
如果约会表单的开始和结束时间为 UTC 上午 9 点和 11 点 UTC，则应确保 start 和 end 参数为 UTC 正确，这意味着：
|
日期相关应用场景的帮助程序方法
Outlook 网页版、移动设备和新 Outlook on Windows 中的用户的本地时间可能不同于 Windows 版 Outlook (经典) 和 Mac 版 Outlook 中的本地时间，但 JavaScript 日期对象仅支持转换为客户端计算机时区或 UTC。 为了克服此问题，Office JavaScript API 提供了两种帮助程序方法： Office.context.mailbox.convertToLocalClientTime 和 Office.context.mailbox.convertToUtcClientTime。
对于Outlook 网页版、Windows (新 (经典) 、Mac 和移动设备上的以下两个与日期相关的方案，这些帮助程序方法可处理以下两个与日期相关的方案，从而强化加载项的不同客户端的“写入一次”。
应用场景 A：显示项创建时间或修改时间
如果要在用户界面中显示项创建时间 (Item.dateTimeCreated) 或修改时间 (Item.dateTimeModified，请先使用 convertToLocalClientTime 转换 Date 这些属性提供的对象，以在适当的本地时间获取字典表示形式。 然后显示字典日期的各个部分。 下面是此方案的示例。
// This date is UTC-correct.
const myDate = Office.context.mailbox.item.dateTimeCreated;
// Call helper method to get date in dictionary format,
// represented in the appropriate local time.
// In Outlook on Windows (classic) and Outlook on Mac, this dictionary format
// is in the client computer time zone.
// In Outlook on the web, on mobile devices, or in new Outlook on Windows,
// this dictionary format is in the EAC time zone.
const myLocalDictionaryDate = Office.context.mailbox.convertToLocalClientTime(myDate);
// Display different parts of the dictionary date.
document.write ("The item was created at " + myLocalDictionaryDate["hours"] +
":" + myLocalDictionaryDate["minutes"]);)
请注意，convertToLocalClientTime请注意 Outlook on Windows (经典) 或 Outlook on Mac 与 Outlook 网页版、移动设备或新 Outlook on Windows 之间的差异。
如果
convertToLocalClientTime检测到当前应用程序是 Outlook on Windows (经典) 或 Outlook on Mac，则该方法会将表示形式转换为Date同一客户端计算机时区中的字典表示形式，这与 Windows 上的 Outlook (经典) 或 Outlook on Mac 用户界面的其余部分一致。如果
convertToLocalClientTime检测到当前应用程序Outlook 网页版、移动设备或 Windows 上的新 Outlook，该方法会将 UTC 正确的Date表示形式转换为 EAC 时区中的字典格式，这与这些 Outlook 客户端的其余用户界面一致。
应用场景 B：在新的约会窗体中显示开始日期和结束日期
如果要获取以本地时间表示的日期时间值的不同部分作为输入，并且希望在约会表单中将此字典输入值作为开始或结束时间提供，请先使用 convertToUtcClientTime 帮助程序方法将字典值转换为 UTC 正确的 Date 对象。
在以下示例中，假设 myLocalDictionaryStartDate 和 myLocalDictionaryEndDate 是你从用户获取的字典格式的日期时间值。 这些值基于本地时间，具体取决于客户端平台。
const myUTCCorrectStartDate = Office.context.mailbox.convertToUtcClientTime(myLocalDictionaryStartDate);
const myUTCCorrectEndDate = Office.context.mailbox.convertToUtcClientTime(myLocalDictionaryEndDate);
结果值 myUTCCorrectStartDate 和 myUTCCorrectEndDate是 UTC 正确的。 然后，将这些Date对象作为 start 方法的 Mailbox.displayNewAppointmentForm 和 end 参数的参数传递，以显示新的约会窗体。
请注意，convertToUtcClientTime请注意 Outlook on Windows (经典) 、Mac 和 Outlook 网页版、移动设备或新的 Windows 版 Outlook 之间的差异：
如果
convertToUtcClientTime检测到当前应用程序是 Windows 上的 Outlook (经典) 或在 Mac 上，该方法只是将字典表示形式转换为Date对象。 此Date对象与 预期一样displayNewAppointmentForm是 UTC 正确的。如果
convertToUtcClientTime检测到当前应用程序Outlook 网页版、移动设备或 Windows 上的新 Outlook，该方法会将 EAC 时区中表示的日期和时间值的字典格式转换为Date对象。 此Date对象与 预期一样displayNewAppointmentForm是 UTC 正确的。