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. Das Objekt Date bietet Methoden wie getUTCDate, getUTCHour, getUTCMinutes und toUTCString, die den angeforderten Datums- oder Zeitwert in Universal Coordinated Time (UTC) zurückgeben.The JavaScript API for Office uses the JavaScript Date object for most of the storage and retrieval of dates and times. 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.

Im folgenden Beispiel wird ein Date-Objekt myLocalDate in Ortszeit erstellt und toUTCString aufgerufen, um das Datum in eine Datumszeichenfolge in UTC 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());

Sie können zwar das JavaScript-Objekt Date verwenden, um einen Datums- oder Zeitwert auf der Grundlage von UTC oder der Zeitzone des Clientcomputers abzurufen, das Date-Objekt besitzt jedoch in einer Hinsicht eine Einschränkung: Es stellt keine Methoden zur Rückgabe von Datums- oder Zeitwerten für andere spezifische Zeitzonen bereit. Wenn für Ihren Clientcomputer beispielsweise Eastern Standard Time (EST) eingestellt ist, steht keine Date-Methode zur Verfügung, den Stundenwert einer anderen Zeitzone als EST oder UTC, beispielsweise Pacific Standard Time (PST), abzurufen.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 Outlook im 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 Diese wird im Betriebssystem des Clientcomputers festgelegt. Die meisten Browser verwenden die Zeitzone des Clientcomputers, um Datums- oder Zeitwerte des JavaScript-Objekts Date 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.

Ein Outlook Rich Client verwendet diese Zeitzone, um Datums- oder Zeitwerte auf 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 die EAC-Zeitzone, kann die lokale Zeitzone für ein für das gleiche Postfach installierte Outlook-Add-In bei Ausführung auf einem Outlook Rich Client und in Outlook im Web oder OWA für Geräte unterschiedlich sein.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. Als Entwickler von Outlook-Add-Ins sollten Sie Datumswerte entsprechend ein- und ausgeben, damit diese Werte immer konsistent mit der Zeitzone sind, die der Benutzer auf dem entsprechenden Client erwartet.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 die datumspezifischen Features.reference/outlook/Office.context.mailbox.item.mdThe following are the properties and methods in the JavaScript API for Office that support date-related features.reference/outlook/Office.context.mailbox.item.md

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 die Zeitzone des Clientcomputers zurück.In an Outlook rich client, this property returns the client computer time zone. In Outlook im Web und OWA für Geräte gibt diese Eigenschaft die EAC-Zeitzone zurück.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-Objekt Date zurück.Each of these properties returns a JavaScript Date object. Dieser Date-Wert ist UTC-gemäß, wie im folgenden Beispiel gezeigt – myUTCDate hat in einem Outlook Rich Client, in Outlook im Web und OWA für Geräte denselben Wert.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 Sowohl für den Start- als auch für den End-Parameter ist ein JavaScript-Objekt Date erforderlich.Each of the Start and End parameters requires a JavaScript Date object. Die Argumente sollten unabhängig von der auf der Benutzeroberfläche von einem Outlook Rich Client, von Outlook im Web oder OWA für Geräte verwendeten Zeitzone UTC-richtig sein.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 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 die Änderungszeit (Item.dateTimeModified) des Elements auf der Benutzeroberfläche anzeigen, verwenden Sie zunächst convertToLocalClientTime, um das von diesen Eigenschaften zum Abrufen einer Wörterbuchdarstellung bereitgestellte Date-Objekt in die entsprechende Ortszeit zu konvertieren. Das Folgende ist 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 verarbeitet: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, konvertiert die Methode die Date-Darstellung in eine Wörterbuchdarstellung in der gleichen Clientcomputer-Zeitzone, die konsistent mit der restlichen Benutzeroberfläche des Rich Client ist.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, konvertiert die Methode die UTC-richtige Date-Darstellung in ein Wörterbuchformat in der Zeitzone EAC, die konsistent mit dem Rest der Outlook im Web-Benutzeroberfläche ist.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 neuen TerminformularScenario 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 Wert als Start- oder Endzeit in einem Terminformular angeben möchten, verwenden Sie zuerst die Hilfsmethode convertToUtcClientTime zum Umwandeln des Werts in ein UTC-gemäßes Date-Objekt.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 resultierenden Werte myUTCCorrectStartDate und myUTCCorrectEndDate sind UTC-gemäß. Übergeben Sie diese Date-Objekte dann als Argumente für die Parameter Start und End der Methode Mailbox.displayNewAppointmentForm, um das neue Terminformular anzuzeigen.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 verarbeitet:Note that convertToUtcClientTime takes care of the difference between an Outlook rich client, and Outlook on the web or OWA for Devices:

  • Wenn convertToUtcClientTime feststellt, dass es sich bei dem aktuellen Host um einen Outlook Rich Client handelt, konvertiert die Methode die Wörterbuchdarstellung einfach in ein Date-Objekt. Dieses Date-Objekt ist UTC-richtig, wie von displayNewAppointmentForm erwartet.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 feststellt, dass es sich bei dem aktuellen Host um Outlook im Web handelt, konvertiert die Methode das Wörterbuchformat der in der Zeitzone EAC angezeigten Datums- und Zeitwerte in ein Date-Objekt.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. Dieses Date-Objekt ist UTC-richtig, wie von displayNewAppointmentForm erwartet.This Date object is UTC-correct, as expected by displayNewAppointmentForm.

Siehe auchSee also