</> programmierung.net
Start · Sprachen · JavaScript · Referenz · Temporal.Duration.prototype.total()

Temporal.Duration.prototype.total()

Methode

Rechnet eine <code>Temporal.Duration</code> vollständig in eine einzige Einheit um und gibt das Ergebnis als (ggf. gebrochene) Zahl zurück.

seit JavaScript ES2026 (Temporal); Firefox 139+, Chrome/Edge 144+, Kategorie: method-property

Signatur

Temporal.Duration.prototype.total(unit | options)

Beschreibung

total() fasst alle Bestandteile einer Dauer – Jahre, Monate, Tage, Stunden bis hinunter zu Nanosekunden – zusammen und gibt aus, wie viele Einheiten der gewünschten Art die Dauer insgesamt umfasst. Anders als round() liefert die Methode keine neue Duration, sondern eine einfache number, die auch Nachkommastellen haben kann (z. B. 1.5 Stunden).

Typische Anwendungsfälle sind Arbeitszeiterfassung („wie viele Stunden insgesamt?“), Fortschrittsanzeigen, Abrechnungen nach Minuten oder die Umrechnung einer ISO-8601-Dauer wie "PT2H45M" in einen Zahlenwert für Diagramme oder Berechnungen.

Sobald kalenderabhängige Einheiten beteiligt sind – also Jahre, Monate oder Wochen in der Dauer oder als Zieleinheit –, braucht die Methode einen Bezugspunkt relativeTo. Denn ein Monat kann 28 bis 31 Tage lang sein. Ohne Bezugspunkt werden Tage als genau 24 Stunden behandelt. Übergibt man einen Temporal.ZonedDateTime, werden auch Zeitumstellungen berücksichtigt: Ein Tag kann dann 23 oder 25 Stunden dauern.

Parameter

Name Typ Default Beschreibung
$unit Pflicht string Kurzform: die Zieleinheit als String, z. B. "hours". Möglich sind "years", "months", "weeks", "days", "hours", "minutes", "seconds", "milliseconds", "microseconds", "nanoseconds" (auch in der Einzahl).
$options object Alternative zur Kurzform: ein Objekt mit den Eigenschaften unit und relativeTo.
$options.unit Pflicht string Zieleinheit wie oben. Pflichtangabe, wenn ein Optionsobjekt übergeben wird.
$options.relativeTo Temporal.ZonedDateTime | Temporal.PlainDate | Temporal.PlainDateTime | string | object undefined Bezugszeitpunkt für kalenderabhängige Berechnungen. Pflicht, wenn die Dauer Jahre, Monate oder Wochen enthält oder eine dieser Einheiten als Ziel gewählt ist. Mit ZonedDateTime werden auch Zeitumstellungen berücksichtigt.

Rückgabewert

Typ
number
Beschreibung
Die Gesamtdauer in der gewählten Einheit als Gleitkommazahl. Ist die Dauer negativ, ist auch das Ergebnis negativ.

Beispiele

Arbeitszeit in Stunden und Minuten umrechnen

const arbeitszeit = Temporal.Duration.from({ hours: 7, minutes: 45 });

console.log(arbeitszeit.total('hours'));
console.log(arbeitszeit.total({ unit: 'minutes' }));

// ISO-8601-String direkt verarbeiten
console.log(Temporal.Duration.from('PT2H45M').total('hours'));
7.75 465 2.75

Monate in Tage umrechnen – mit relativeTo

const einMonat = Temporal.Duration.from({ months: 1 });

const schaltjahr = einMonat.total({
  unit: 'days',
  relativeTo: Temporal.PlainDate.from('2024-02-01'),
});
const normaljahr = einMonat.total({
  unit: 'days',
  relativeTo: '2023-02-01',
});

console.log(schaltjahr, normaljahr);
29 28

Zeitumstellung berücksichtigen mit ZonedDateTime

const einTag = Temporal.Duration.from({ days: 1 });

// In der Nacht zum 31.03.2024 wird in Deutschland auf Sommerzeit umgestellt
const start = Temporal.ZonedDateTime.from('2024-03-31T00:00[Europe/Berlin]');

console.log(einTag.total({ unit: 'hours', relativeTo: start }));
console.log(einTag.total('hours')); // ohne Bezug: 24 h pro Tag
23 24

Fehler ohne Bezugspunkt abfangen

const projekt = Temporal.Duration.from({ years: 1, months: 2 });

try {
  projekt.total('days');
} catch (err) {
  console.log(err.name);
}

const tage = projekt.total({ unit: 'days', relativeTo: '2025-01-01' });
console.log(tage);
RangeError 424

// Wichtig · Fallstricke

  • RangeError ohne relativeTo: Enthält die Dauer Jahre, Monate oder Wochen oder soll in eine dieser Einheiten umgerechnet werden, wirft total() ohne Bezugspunkt einen RangeError.
  • Tage ohne Bezugspunkt sind immer 24 Stunden. Wenn Zeitumstellungen eine Rolle spielen, einen Temporal.ZonedDateTime als relativeTo übergeben – ein PlainDate reicht dafür nicht.
  • Genauigkeit: Das Ergebnis ist ein number (Gleitkommazahl). Bei sehr großen Dauern in \"nanoseconds\" können Stellen verloren gehen. Für exakte Werte besser mit round() oder den einzelnen Feldern arbeiten.
  • Kein Runden: total() gibt Brüche zurück. Wer eine ganze Zahl oder wieder eine Duration braucht, nimmt round() oder Math.floor().
  • Kompatibilität: Temporal ist noch neu. Firefox unterstützt es ab Version 139, Chromium-Browser ab etwa Version 144. Safari und ältere Umgebungen brauchen einen Polyfill wie @js-temporal/polyfill. Vorher mit typeof Temporal !== 'undefined' prüfen, ob Temporal vorhanden ist.

Siehe auch

Temporal.Duration Temporal.Duration.prototype.round() Temporal.Duration.from() Temporal.Duration.prototype.toString() Temporal.ZonedDateTime Temporal.PlainDate
← Vorheriger Eintrag Temporal.Duration.prototype.toString()