Temporal.PlainDateTime.prototype.withPlainTime() — Methode · JavaScript-Referenz

Signatur

Temporal.PlainDateTime.prototype.withPlainTime(plainTime)

Beschreibung

withPlainTime() behält Datum und Kalender eines Temporal.PlainDateTime bei und ersetzt den gesamten Zeitteil (Stunde, Minute, Sekunde, Milli-, Mikro- und Nanosekunde) durch eine neue Uhrzeit. Das Ursprungsobjekt bleibt unverändert, denn alle Temporal-Objekte sind unveränderlich.

Anders als with({ hour, minute }), das nur die angegebenen Felder ändert und die übrigen beibehält, setzt withPlainTime() alle nicht angegebenen Zeitfelder auf 0. Ruft man die Methode ohne Argument auf, erhält man den Beginn des Tages (00:00:00). Das ist praktisch, um Termine auf eine feste Uhrzeit zu setzen, etwa „Arbeitsbeginn 09:00“ oder „Tagesende 23:59:59.999999999“.

Als Argument sind ein Temporal.PlainTime, ein ISO-8601-Zeitstring wie "14:30" oder ein Objekt mit Zeitfeldern ({ hour: 14, minute: 30 }) erlaubt. Intern wird der Wert wie bei Temporal.PlainTime.from() umgewandelt.

Parameter

Name	Typ	Default	Beschreibung
$plainTime	Temporal.PlainTime \| string \| object \| undefined	undefined (entspricht 00:00:00)	Die neue Uhrzeit. Wird wie bei `Temporal.PlainTime.from()` umgewandelt. Fehlende Felder in einem Objekt werden auf `0` gesetzt. Ohne Argument gilt Mitternacht.

Rückgabewert

Typ

Temporal.PlainDateTime

Beschreibung

Ein neues Temporal.PlainDateTime mit dem ursprünglichen Datum und Kalender und der neuen Uhrzeit.

Beispiele

Uhrzeit komplett ersetzen

const dt = Temporal.PlainDateTime.from("2024-05-17T16:42:13.5");

console.log(dt.withPlainTime("09:00").toString());
console.log(dt.withPlainTime({ hour: 12 }).toString());
console.log(dt.withPlainTime(new Temporal.PlainTime(18, 30)).toString());

2024-05-17T09:00:00 2024-05-17T12:00:00 2024-05-17T18:30:00

Tagesbeginn und Tagesende für Filter berechnen

const now = Temporal.PlainDateTime.from("2024-05-17T16:42:13");

const start = now.withPlainTime(); // Mitternacht
const end = now.withPlainTime("23:59:59.999999999");

console.log(start.toString());
console.log(end.toString());

2024-05-17T00:00:00 2024-05-17T23:59:59.999999999

Unterschied zu with()

const dt = Temporal.PlainDateTime.from("2024-05-17T16:42:13");

// with() behält Minuten und Sekunden bei
console.log(dt.with({ hour: 9 }).toString());
// withPlainTime() setzt fehlende Felder auf 0
console.log(dt.withPlainTime({ hour: 9 }).toString());

2024-05-17T09:42:13 2024-05-17T09:00:00

Wiederkehrende Termine mit fester Uhrzeit

const meetingTime = Temporal.PlainTime.from("10:15");
const firstDay = Temporal.PlainDateTime.from("2024-06-03T00:00");

const meetings = Array.from({ length: 3 }, (_, i) =>
  firstDay.add({ weeks: i }).withPlainTime(meetingTime).toString()
);

console.log(meetings);

[ '2024-06-03T10:15:00', '2024-06-10T10:15:00', '2024-06-17T10:15:00' ]

// Wichtig · Fallstricke

Nicht mit with() verwechseln: withPlainTime({ hour: 9 }) setzt Minuten, Sekunden und Sekundenbruchteile auf 0, with({ hour: 9 }) dagegen nicht.
Ungültige Zeiten wie "25:00" oder { hour: 24 } lösen einen RangeError aus. Werte außerhalb des Bereichs werden nicht angepasst, weil intern overflow: "reject" gilt. Ein falscher Argumenttyp (etwa eine Zahl) führt zu einem TypeError.
Ein String mit Datumsanteil wie "2024-01-01T10:00" wird akzeptiert, aber nur die Uhrzeit wird übernommen. Ein String mit dem Zeitzonenkürzel Z wird abgelehnt.
PlainDateTime kennt keine Zeitzone, deshalb gibt es hier keine Probleme mit der Sommerzeit. Für zeitzonenbezogene Werte gibt es Temporal.ZonedDateTime.prototype.withPlainTime().
Kompatibilität: Temporal wird bisher nur in neuen Browsern unterstützt (u. a. Firefox 139+, Chrome 144+). Für ältere Umgebungen und Node.js braucht man einen Polyfill wie @js-temporal/polyfill oder temporal-polyfill.

Siehe auch

Temporal.PlainDateTime Temporal.PlainDateTime.prototype.with() Temporal.PlainDateTime.prototype.withCalendar() Temporal.PlainTime Temporal.PlainTime.from() Temporal.ZonedDateTime.prototype.withPlainTime() Temporal.PlainDate.prototype.toPlainDateTime()