Tipps für den Umgang mit Datumswerten 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.

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.

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.

Im folgenden Beispiel wird ein Date-Objekt myLocalDate in Ortszeit erstellt und toUTCString aufgerufen, um das Datum in eine Datumszeichenfolge in UTC umzuwandeln.

// 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.

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.

Zeitzonen für Outlook-Clients

Lassen Sie uns zur Verdeutlichung die fraglichen Zeitzonen definieren.

Zeitzone Beschreibung
Zeitzone des Clientcomputers Diese wird im Betriebssystem des Clientcomputers festgelegt. Die meisten Browser verwenden die Zeitzone des Clientcomputers, um Datums- oder Zeitwerte des JavaScript-Objekts Date anzuzeigen.

Ein Outlook Rich Client verwendet diese Zeitzone, um Datums- oder Zeitwerte auf der Benutzeroberfläche anzuzeigen.

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.
EAC-Zeitzone (Exchange Admin Center) 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.

Outlook im Web und OWA für Geräte verwenden diese Zeitzone, um Datums- oder Zeitwerte auf der Benutzeroberfläche anzuzeigen.

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. 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.

Die folgenden Eigenschaften und Methoden in der JavaScript-API für Office unterstützen die datumspezifischen Features.reference/outlook/Office.context.mailbox.item.md

API-Element Zeitzonendarstellung Beispiel unter einem Outlook-Rich-Client Beispiel in Outlook im Web oder OWA für Geräte
Office.context.mailbox.userProfile.timeZone In einem Outlook-Rich-Client gibt diese Eigenschaft die Zeitzone des Clientcomputers zurück. In Outlook im Web und OWA für Geräte gibt diese Eigenschaft die EAC-Zeitzone zurück. EST PST
Office.context.mailbox.item.dateTimeCreated und Office.context.mailbox.item.dateTimeModified Jede dieser Eigenschaften gibt ein JavaScript-Objekt Date zurück. 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.

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.
Wird das Element um 9 Uhr UTC erstellt, gibt

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

Bei Änderung des Elements um 11 Uhr UTC, gibt

Office.mailbox.item.
dateTimeModified.getHours „6am EST“ zurück.
Bei Erstellungszeit 9 Uhr UTC gibt

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

Bei Änderung des Elements um 11 Uhr UTC, gibt

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

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.
Office.context.mailbox.displayNewAppointmentForm Sowohl für den Start- als auch für den End-Parameter ist ein JavaScript-Objekt Date erforderlich. 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. 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:

  • start.getUTCHours gibt „9am UTC“ zurück
  • end.getUTCHours gibt „11am UTC“ zurück
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:

  • start.getUTCHours gibt „9am UTC“ zurück
  • end.getUTCHours gibt „11am UTC“ zurück

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.

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.

Szenario A: Anzeigen der Erstellungs- oder Änderungszeit des Elements

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:

// 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:

  • 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.

  • 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.

Szenario B: Anzeigen von Anfangs- und Enddatum in einem neuen Terminformular

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.

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.

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.

Beachten Sie, dass convertToUtcClientTime die Unterschiede zwischen einem Outlook-Rich-Client und Outlook im Web bzw. OWA für Geräte verarbeitet:

  • 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.

  • 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. Dieses Date-Objekt ist UTC-richtig, wie von displayNewAppointmentForm erwartet.

Zusätzliche Ressourcen