Tipps für den Umgang mit Datumswerten in Outlook-Add-InsTips for handling date values in Outlook add-ins

Die JavaScript-API für Office verwendet das JavaScript-Objekt Date für die meisten Speicher- und Abrufvorgänge von Datums- und Uhrzeitangaben.The JavaScript API for Office uses the JavaScript Date object for most of the storage and retrieval of dates and times.

Das Objekt Date stellt Methoden wie getUTCDate, getUTCHour, getUTCMinutes und toUTCString bereit, die den angeforderten Datums- oder Uhrzeitwert im Format UTC (Universal Coordinated Time) zurückgeben.That Date object provides methods such as getUTCDate, getUTCHour, getUTCMinutes, and toUTCString, which return the requested date or time value according to Universal Coordinated Time (UTC) time.

Das Objekt Date bietet auch andere Methoden wie z. B. getDate, getHour, getMinutes und toString, die das angeforderte Datum bzw. die Uhrzeit in Ortszeit („local time“) zurückgeben.The Date object also provides other methods such as getDate, getHour, getMinutes, and toString, which return the requested date or time according to "local time".

Das Konzept der Ortszeit wird größtenteils von Browser und Betriebssystem des Clientcomputers bestimmt. So gibt beispielsweise in den meisten Browsern auf Windows-basierten Clientcomputern ein JavaScript-Aufruf von getDate ein Datum zurück, das auf der in Windows auf dem Clientcomputer festgelegten Zeitzone basiert.The concept of "local time" is largely determined by the browser and operating system on the client computer. For instance, on most browsers running on a Windows-based client computer, a JavaScript call to getDate, returns a date based on the time zone set in Windows on the client computer.

Das folgende Beispiel erstellt ein Objekt myLocalDate des Typs Date in Ortszeit und ruft toUTCString auf, um dieses Datum in eine Datumszeichenfolge im UTC-Format umzuwandeln.The following example creates a Date object myLocalDate in local time, and calls toUTCString to convert that date to a date string in UTC.

// Create and get the current date represented 
// in the client computer time zone.
var 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());

Während Sie das JavaScript Date -Objekt verwenden können, um einen Datums- oder Zeitwerte Wert basierend auf UTC oder die Zeitzone des Clientcomputers abzurufen, wird das Date -Objekt in einer Hinsicht - begrenzt ist es kein Methoden zum Zurückgeben eines Werts Datums- oder Zeitwerte für jede bestimmte Zeitzone bereitgestellt. Ihre Clientcomputer auf Standard EST (Eastern Time) festgelegt ist, besteht beispielsweise keine Datum -Methode, die den anderen Stundenwert als in EST oder UTC, wie etwa Pacific Standard Time (PST) abgerufen werden können.While you can use the JavaScript Date object to get a date or time value based on UTC or the client computer time zone, the Date object is limited in one respect - it does not provide methods to return a date or time value for any other specific time zone. For example, if your client computer is set to be on Eastern Standard Time (EST), there is no Date method that allows you to get the hour value other than in EST or UTC, such as Pacific Standard Time (PST).

Die vorgenannten JavaScript-Einschränkungen sind für Sie von Bedeutung, wenn Sie die JavaScript-API für Office zur Verarbeitung von Datums- oder Zeitwerten in Outlook-Add-Ins verwenden, die auf einem Outlook Rich Client und in Outlookim Web oder OWA für mobile Geräte ausgeführt werden.The afore-mentioned JavaScript limitation has an implication for you, when you use the JavaScript API for Office to handle date or time values in Outlook add-ins that run in an Outlook rich client, and in Outlook on the web or OWA for Devices.

Zeitzonen für Outlook-ClientsTime zones for Outlook clients

Lassen Sie uns zur Verdeutlichung die fraglichen Zeitzonen definieren.For clarity, let's define the time zones in question.

ZeitzoneTime zone BeschreibungDescription
Zeitzone des ClientcomputersClient computer time zone Dies wird unter dem Betriebssystem des Clientcomputers festgelegt. Den meisten Browsern verwenden die Zeitzone des Clientcomputers, um Datums- oder Zeitwerte des JavaScript Date -Objekts anzuzeigen.This is set on the operating system of the client computer. Most browsers use the client computer time zone to display date or time values of the JavaScript Date object.

Outlook-Rich-Clients verwenden diese Zeitzone, um Datums- oder Uhrzeitwerte in der Benutzeroberfläche anzuzeigen.An Outlook rich client uses this time zone to display date or time values in the user interface.

Beispielsweise verwendet Outlook auf einem Clientcomputer unter Windows die in Windows festgelegte Zeitzone als lokale Zeitzone. Wenn der Benutzer die Zeitzone auf einem Mac-Clientcomputer ändert, fordert Outlook für Mac den Benutzer auf, die Zeitzone auch in Outlook zu aktualisieren.For example, on a client computer running Windows, Outlook uses the time zone set on Windows as the local time zone. On the Mac, if the user changes the time zone on the client computer, Outlook for Mac would prompt the user to update the time zone in Outlook as well.
EAC-Zeitzone (Exchange Admin Center)Exchange Admin Center (EAC) time zone Dieser Zeitzonenwert (und die bevorzugte Sprache) wird vom Benutzer festgelegt, wenn er sich erstmals bei Outlook im Web oder OWA für Geräte anmeldet.The user sets this time zone value (and the preferred language) when he or she logs on to Outlook on the web or OWA for Devices the first time.

Outlook im Web und OWA für Geräte verwenden diese Zeitzone, um Datums- oder Zeitwerte auf der Benutzeroberfläche anzuzeigen.Outlook on the web and OWA for Devices use this time zone to display date or time values in the user interface.

Da ein Outlook-rich-Client die Zeitzone des Clientcomputers verwendet und die Benutzeroberfläche von Outlook im Web und OWA für Geräte der Zeitzone EAC verwendet werden, können die Ortszeit für die gleiche add-in für dasselbe Postfach installierten anders, wenn in einer Outlook-rich-ander ausgeführt NT und in Outlook im Web oder OWA for Devices. Als Outlook-add-ins Entwickler sollten Sie entsprechend Eingabe- und Ausgabeparameter Datum Werte, damit diese Werte immer konsistent mit der Time-Zone sind, die der Benutzer auf dem entsprechenden Client erwartet.Because an Outlook rich client uses the client computer time zone, and the user interface of Outlook on the web and OWA for Devices uses the EAC time zone, the local time for the same add-in installed for the same mailbox can be different when running in an Outlook rich client and in Outlook on the web or OWA for Devices. As an Outlook add-in developer, you should appropriately input and output date values so that those values are always consistent with the time zone that the user expects on the corresponding client.

Die folgenden Eigenschaften und Methoden in der JavaScript-API für Office unterstützen datumsspezifische Features.The following are the properties and methods in the JavaScript API for Office that support date-related features.

API-ElementAPI member ZeitzonendarstellungTime zone representation Beispiel unter einem Outlook-Rich-ClientExample in an Outlook rich client Beispiel in Outlook im Web oder OWA für GeräteExample in Outlook on the web or OWA for Devices
Office.context.mailbox.userProfile.timeZoneOffice.context.mailbox.userProfile.timeZone In einem Outlook-rich-Client gibt diese Eigenschaft den Client Zeitzone des Clientcomputers. In Outlook im Web und OWA für Geräte gibt diese Eigenschaft die Zeitzone des Exchange-Verwaltungskonsole.In an Outlook rich client, this property returns the client computer time zone. In Outlook on the web and OWA for Devices, this property returns the EAC time zone. ESTEST PSTPST
Office.context.mailbox.item.dateTimeCreated und Office.context.mailbox.item.dateTimeModifiedOffice.context.mailbox.item.dateTimeCreated and Office.context.mailbox.item.dateTimeModified Jede dieser Eigenschaften gibt ein JavaScript Date -Objekt zurück. Diese Datumswert UTC-richtig ist, wie im folgenden Beispiel - myUTCDate hat den gleichen Wert in einer Outlook-rich-Client, Outlook im Web und OWA for Devices.Each of these properties returns a JavaScript Date object. This Date value is UTC-correct, as shown in the following example - myUTCDate has the same value in an Outlook rich client, Outlook on the web and OWA for Devices.

var myDate = Office.mailbox.item.dateTimeCreated;
var myUTCDate = myDate.getUTCDate;

Wird jedoch myDate.getDate aufgerufen, so wird ein Datumswert in der Zeitzone des Clientcomputers zurückgegeben, der der Zeitzone entspricht, die zum Anzeigen von Datums- und Zeitwerten in der Benutzeroberfläche des Outlook Rich Client verwendet wird, sich aber von der EAC-Zeitzone der Benutzeroberflächen von Outlook im Web und OWA für Geräte unterscheiden kann.However, calling myDate.getDate returns a date value in the client computer time zone, which is consistent with the time zone used to display date times values in the Outlook rich client interface, but may be different from the EAC time zone that Outlook on the web and OWA for Devices use in its user interface.
Wird das Element um 9 Uhr UTC erstellt, gibtIf the item is created at 9am UTC:

Office.mailbox.item.
dateTimeCreated.getHours „4am EST“ zurück.dateTimeCreated.getHours returns 4am EST.

Bei Änderung des Elements um 11 Uhr UTC, gibtIf the item is modified at 11am UTC:

Office.mailbox.item.
dateTimeModified.getHours „6am EST“ zurück.dateTimeModified.getHours returns 6am EST.
Bei Erstellungszeit 9 Uhr UTC gibtIf the item creation time is 9am UTC:

Office.mailbox.item.
dateTimeCreated.getHours „4am EST“ zurück.dateTimeCreated.getHours returns 4am EST.

Bei Änderung des Elements um 11 Uhr UTC, gibtIf the item is modified at 11am UTC:

Office.mailbox.item.
dateTimeModified.getHours „6am EST“ zurück.dateTimeModified.getHours returns 6am EST.

Beachten Sie bei der Anzeige der Erstellungs- und Änderungszeiten auf der Benutzeroberfläche, dass Sie diese zunächst in PST konvertieren sollten, damit diese konsistent mit dem Rest der Benutzeroberfläche sind.Notice that if you want to display the creation or modification time in the user interface, you would want to first convert the time to PST to be consistent with the rest of the user interface.
Office.context.mailbox.displayNewAppointmentFormOffice.context.mailbox.displayNewAppointmentForm Jedes der Parameter Start und End erfordert ein JavaScript Date -Objekt. Die Argumente sollte UTC-richtige unabhängig von der Zeitzone, die in der Benutzeroberfläche von einer Outlook-rich-Client, Outlook im Web oder OWA für Geräte verwendet werden.Each of the Start and End parameters requires a JavaScript Date object. The arguments should be UTC-correct regardless of the time zone used in the user interface of an Outlook rich client, Outlook on the web or OWA for Devices. Wenn die Anfangs- und Endzeiten des Terminformulars 9 Uhr UTC und 11 Uhr UTC angeben, sollten Sie sicherstellen, dass das start- und end-Argument UTC-richtig sind, das bedeutet:If the start and end times for the appointment form are 9am UTC and 11am UTC, then you should assure that the start and end arguments are UTC-correct, which means:

  • start.getUTCHours gibt „9am UTC“ zurückstart.getUTCHours returns 9am UTC
  • end.getUTCHours gibt „11am UTC“ zurückend.getUTCHours returns 11am UTC
Wenn die Anfangs- und Endzeiten des Terminformulars 9 Uhr UTC und 11 Uhr UTC angeben, sollten Sie sicherstellen, dass das start- und end-Argument UTC-richtig sind, das bedeutet:If the start and end times for the appointment form are 9am UTC and 11am UTC, then you should assure that the start and end arguments are UTC-correct, which means:

  • start.getUTCHours gibt „9am UTC“ zurückstart.getUTCHours returns 9am UTC
  • end.getUTCHours gibt „11am UTC“ zurückend.getUTCHours returns 11am UTC

Wie in den vorhergehenden Abschnitten beschrieben, bietet die JavaScript-API für Office zwei Hilfsmethoden, da die Ortszeit für Benutzer von Outlook im Web oder OWA für Geräte sich von der in einem Outlook-Rich-Client unterscheiden kann, das JavaScript-Objekt Date aber nur die Umwandlung in die Zeitzone des Clientcomputers oder in UTC unterstützt: Office.context.mailbox.convertToLocalClientTime und Office.context.mailbox.convertToUtcClientTime.As described in the preceding sections, because the "local time" for a user in Outlook on the web or OWA for Devices can be different on an Outlook rich client, but the JavaScript Date object supports converting to only the client computer time zone or UTC, the JavaScript API for Office provides two helper methods: Office.context.mailbox.convertToLocalClientTime and Office.context.mailbox.convertToUtcClientTime.

Diese Hilfsmethoden können immer dann verwendet werden, wenn Datum oder Uhrzeit für die folgenden zwei datumsbezogenen Szenarien in einem Outlook-Rich-Client, in Outlook im Web und OWA für mobile Geräte unterschiedlich behandelt werden müssen.These helper methods take care of any need to handle date or time differently for the following two date-related scenarios, in an Outlook rich client, Outlook on the web and OWA for Devices, thus reinforcing "write-once" for different clients of your add-in.

Szenario A: Anzeigen der Erstellungs- oder Änderungszeit des ElementsScenario A: Displaying item creation or modified time

Wenn Sie die Erstellungszeit (Item.dateTimeCreated) oder Änderungszeit (Item.dateTimeModified) in der Benutzeroberfläche anzeigen, zunächst mit dem ConvertToLocalClientTime das Date -Objekt bereitgestellt, die durch diese konvertieren Eigenschaften, um eine Wörterbuch-Darstellung in der entsprechenden lokalen Zeit zu erhalten. Zeigen Sie dann die Teile des Datums Wörterbuch an. Es folgt ein Beispiel dieses Szenarios:If you are displaying the item creation time (Item.dateTimeCreated) or modification time (Item.dateTimeModified) in the user interface, first use convertToLocalClientTime to convert the Date object provided by these properties to obtain a dictionary representation in the appropriate local time. Then display the parts of the dictionary date. The following is an example of this scenario:

// This date is UTC-correct.
var myDate = Office.context.mailbox.item.dateTimeCreated;

// Call helper method to get date in dictionary format, 
// represented in the appropriate local time.
// In an Outlook rich client, this is dictionary format 
// in client computer time zone.
// In Outlook on the web or OWA for Devices, this dictionary 
// format is in EAC time zone.
var myLocalDictionaryDate = Office.context.mailbox.convertToLocalClientTime(myDate);

// Display different parts of the dictionary date.
document.write ("The item was created at " + myLocalDictionaryDate["hours"] + 
    ":" + myLocalDictionaryDate["minutes"]);)

Beachten Sie, dass convertToLocalClientTime die Unterschiede zwischen einem Outlook-Rich-Client und Outlook im Web bzw. OWA für Geräte berücksichtigt:Note that convertToLocalClientTime takes care of the difference between an Outlook rich client, and Outlook on the web or OWA for Devices:

  • Wenn convertToLocalClientTime feststellt, dass der aktuelle Host ein Rich-Client ist, wandelt die Methode die Darstellung von Date in eine Wörterbuchdarstellung in der gleichen Clientcomputer-Zeitzone um, konsistent mit der restlichen Benutzeroberfläche des Rich-Client.If convertToLocalClientTime detects the current host is a rich client, the method converts the Date representation to a dictionary representation in the same client computer time zone, consistent with the rest of the rich client user interface.

  • Wenn convertToLocalClientTime feststellt, dass der aktuelle Host Outlook im Web ist, wandelt die Methode die UTC-konforme Darstellung von Date in ein Wörterbuchformat in der Zeitzone EAC um, konsistent mit dem Rest der Outlook im Web- bzw. OWA für Geräte-Benutzeroberfläche.If convertToLocalClientTime detects the current host is Outlook on the web or OWA for Devices, the method converts the UTC-correct Date representation to a dictionary format in the EAC time zone, consistent with the rest of the Outlook on the web or OWA for Devices user interface.

Szenario B: Anzeigen von Anfangs- und Enddatum in einem Formular für neue TermineScenario B: Displaying start and end dates in a new appointment form

Wenn Sie als Eingabe verschiedene Teile eines Datum-Uhrzeit-Werts in Ortszeit erhalten und diesen Wörterbucheingabewert als Start- oder Endzeit in einem Terminformular angeben möchten, verwenden Sie zuerst die Hilfsmethode convertToUtcClientTime zum Umwandeln des Werts in ein UTC-konformes Objekt des Typs Date.If you are obtaining as input different parts of a date-time value represented in the local time, and would like to provide this dictionary input value as a start or end time in an appointment form, first use the convertToUtcClientTime helper method to convert the dictionary value to a UTC-correct Date object.

Im folgenden Beispiel wird davon ausgegangen, dass myLocalDictionaryStartDate und myLocalDictionaryEndDate Datum-/Uhrzeit-Werte im Wörterbuchformat sind, das Sie vom Benutzer erhalten haben. Diese Werte basieren auf der lokalen Zeit, die abhängig von der Host-Anwendung ist.In the following example, assume myLocalDictionaryStartDate and myLocalDictionaryEndDate are date-time values in dictionary format that you have obtained from the user. These values are based on the local time, dependent on the host application.

var myUTCCorrectStartDate = Office.context.mailbox.convertToUtcClientTime(myLocalDictionaryStartDate);
var myUTCCorrectEndDate = Office.context.mailbox.convertToUtcClientTime(myLocalDictionaryEndDate);

Die resultierende Werte myUTCCorrectStartDate und myUTCCorrectEndDate, UTC-richtig sind. Übergeben Sie diese Objekte Datum als Argumente für die Parameter Start und Ende der Mailbox.displayNewAppointmentForm -Methode zum Anzeigen des neuen Terminformulars.The resultant values, myUTCCorrectStartDate and myUTCCorrectEndDate, are UTC-correct. Then pass these Date objects as arguments for the Start and End parameters of the Mailbox.displayNewAppointmentForm method to display the new appointment form.

Beachten Sie, dass convertToUtcClientTime die Unterschiede zwischen einem Outlook-Rich-Client und Outlook im Web bzw. OWA für Geräte berücksichtigt:Note that convertToUtcClientTime takes care of the difference between an Outlook rich client, and Outlook on the web or OWA for Devices:

  • Wenn ConvertToUtcClientTime , dass der aktuelle Host ein Outlook-rich-Client ist erkennt, konvertiert die Methode einfach Wörterbuch-Darstellung in ein Date -Objekt. Diese Date -Objekt ist UTC-richtig, wie durch die DisplayNewAppointmentFormerwartet.If convertToUtcClientTime detects the current host is an Outlook rich client, the method simply converts the dictionary representation to a Date object. This Date object is UTC-correct, as expected by displayNewAppointmentForm.

  • Wenn ConvertToUtcClientTime , dass der aktuelle Host Outlook im Web oder OWA for Devices ist erkennt, konvertiert die Methode die Wörterbuchformat in der Exchange-Verwaltungskonsole Zeitzone in ein Date -Objekt ausgedrückten Werte Datum und Uhrzeit. Diese Date -Objekt ist UTC-richtig, wie durch die DisplayNewAppointmentFormerwartet.If convertToUtcClientTime detects the current host is Outlook on the web or OWA for Devices, the method converts the dictionary format of the date and time values expressed in the EAC time zone to a Date object. This Date object is UTC-correct, as expected by displayNewAppointmentForm.

Siehe auchSee also