Temporal.Duration.prototype.nanoseconds — Eigenschaft · JavaScript-Referenz

Signatur

get Temporal.Duration.prototype.nanoseconds

Beschreibung

Die Zugriffseigenschaft nanoseconds gibt nur das Nanosekunden-Feld einer Temporal.Duration zurück. Sie hat keinen Setter. Eine Duration ist unveränderlich, einen geänderten Wert erhält man über with().

Wichtig: Der Wert ist nicht ausgeglichen (unbalanced). Eine Dauer aus { nanoseconds: 1500 } meldet 1500 und nicht 1 Mikrosekunde plus 500 Nanosekunden. Der Wert ist also nicht auf 0–999 begrenzt. Ist die Dauer negativ, ist auch dieser Wert negativ oder 0. Wurde das Feld nicht angegeben, ist der Wert 0.

Die Eigenschaft ist nützlich für hochauflösende Zeitangaben, zum Beispiel für Differenzen zwischen Temporal.Instant-Werten, für Messwerte oder für die eigene Formatierung von Sekundenbruchteilen. Wer die gesamte Dauer in Nanosekunden braucht, nimmt duration.total("nanoseconds"). Wer eine Aufteilung in ms/µs/ns braucht, gleicht die Dauer vorher mit round() aus.

Rückgabewert

Typ

number

Beschreibung

Ganzzahl mit dem Nanosekunden-Feld der Dauer. Sie kann größer als 999 und bei negativen Dauern negativ sein. Wurde das Feld nicht angegeben, ist sie 0.

Beispiele

Nanosekunden-Feld auslesen

const d = Temporal.Duration.from({ seconds: 2, nanoseconds: 500 });
console.log(d.nanoseconds);
console.log(d.seconds);

// Aus einem ISO-8601-String
const p = Temporal.Duration.from("PT1.123456789S");
console.log(p.milliseconds, p.microseconds, p.nanoseconds);

500 2 123 456 789

Nicht ausgeglichene Werte und round()

const d = Temporal.Duration.from({ nanoseconds: 1500 });
console.log(d.nanoseconds); // wird nicht umgerechnet

const balanced = d.round({ largestUnit: "microseconds" });
console.log(balanced.microseconds, balanced.nanoseconds);

// Gesamte Dauer in Nanosekunden
const gesamt = Temporal.Duration.from({ milliseconds: 2, nanoseconds: 7 });
console.log(gesamt.total("nanoseconds"));

1500 1 500 2000007

Hochauflösende Differenz zwischen zwei Instants

const start = Temporal.Instant.fromEpochNanoseconds(0n);
const ende = Temporal.Instant.fromEpochNanoseconds(1_000_000_123n);

const dauer = start.until(ende);
console.log(dauer.seconds, dauer.nanoseconds);

// Negative Dauer: das Vorzeichen gilt für alle Felder
console.log(ende.until(start).nanoseconds);

1 123 -123

Wert ändern mit with()

const d = Temporal.Duration.from({ seconds: 5, nanoseconds: 42 });
const ohneNs = d.with({ nanoseconds: 0 });

console.log(ohneNs.toString());
console.log(d.nanoseconds); // das Original bleibt unverändert

PT5S 42

// Wichtig · Fallstricke

Nicht ausgeglichen: Man kann sich nicht darauf verlassen, dass nanoseconds unter 1000 liegt. Für eine Anzeige wie „x ms y µs z ns“ vorher round({ largestUnit: … }) aufrufen.
Nicht die Gesamtdauer: Die Eigenschaft enthält nur dieses eine Feld. Für die gesamte Dauer in Nanosekunden total(\"nanoseconds\") verwenden. Bei sehr großen Dauern kann das Ergebnis ungenau werden, weil es eine number und kein BigInt ist.
String-Rundreise: toString() fasst Sekundenbruchteile in die Sekunden zusammen ({ nanoseconds: 1500 } → \"PT0.0000015S\"). Liest man den String wieder ein, erhält man microseconds: 1, nanoseconds: 500.
Schreibgeschützt: Eine Zuweisung an nanoseconds hat keine Wirkung (im Strict Mode: TypeError). Stattdessen with() verwenden.
Kompatibilität: Temporal ist noch nicht in allen Browsern verfügbar (vorhanden in Firefox 139+ und Chrome/Edge 144+, in Safari noch nicht). Für breite Unterstützung einen Polyfill wie @js-temporal/polyfill oder temporal-polyfill einsetzen.

Siehe auch

Temporal.Duration Temporal.Duration.prototype.microseconds Temporal.Duration.prototype.milliseconds Temporal.Duration.prototype.total() Temporal.Duration.prototype.round() Temporal.Duration.prototype.with() Temporal.Instant.prototype.until()