moment duration format

Momentdauerformat

Format-Plugin für das Moment-Dauer-Objekt.

Dies ist ein Plugin für die JavaScript-Datumsbibliothek Moment.js, um eine umfassende Formatierung zu Moment-Dauern hinzuzufügen.

Die Grammatik der Formatvorlagen orientiert sich an der vorhandenen Grammatik der Formatvorlagen „Moment Date“, mit einigen Änderungen, da sich Dauern grundlegend von Datumsangaben unterscheiden.

Dieses Plugin hat keine Abhängigkeiten über Moment.js selbst hinaus und kann im Browser und in Node.js verwendet werden.

---

Zahlen formatieren und testen

Sofern verfügbar und funktionsfähig, verwendet dieses Plugin entweder Intl.NumberFormat#format oder Number#toLocaleString um formatierte numerische Ausgaben darzustellen. Leider implementieren viele Umgebungen nicht alle Optionen in ihren jeweiligen Spezifikationen vollständig und einige bieten eine fehlerhafte Implementierung.

Dieses Plugin führt einen Funktionstest für jeden Formatierer durch und greift auf eine Fallback-Funktion zurück, um formatierte numerische Ausgaben zu rendern, wenn der Funktionstest fehlschlägt. Um zu erzwingen, dass dieses Plugin immer die Fallback-Zahlenformatfunktion verwendet, setzen Sie useToLocaleString auf false . Die Ausgabe der Fallback-Nummernformatfunktion kann mithilfe der unten auf dieser Seite beschriebenen Optionen lokalisiert werden. Im Allgemeinen sollten Sie die Formatierungsoptionen für Ersatznummern angeben, wenn die Standardformatierung des Gebietsschemas "en" auf einigen Geräten oder in bestimmten Umgebungen nicht akzeptabel wäre.

Dieses Plugin wurde mit BrowserStack auf einer Reihe von Android-Geräten mit Betriebssystemversionen von 2.2 bis 7 und auf einer Reihe von iOS-Geräten mit Betriebssystemversionen von 4.3 bis 11 getestet. Auch auf Chrome-, Firefox-, IE 8-11- und Edge-Browsern getestet .

Bitte melden Sie ein Problem, wenn Sie Formatierungsprobleme oder Anomalien in einer Umgebung bemerken!

---

Roadmap

Version 2

Zum Abschluss von Version 2 sind noch einige Punkte zu erledigen:

• Fügen Sie Typdefinitionen hinzu, um TypeScript zu unterstützen, veröffentlichen Sie NuGet-Pakete und unterstützen Sie alle anderen Verpackungsoptionen, die heutzutage verwendet werden.

• Das Testen des Plugins sollte modernisiert werden, idealerweise um mit dem Test-Setup von Moment.js übereinzustimmen.

Version 3

Nach der Implementierung von Version 2 des Moment-Duration-Format-Plugins gibt es einige offensichtliche Verbesserungen für Version 3.

Die folgenden Ideen werden als Probleme protokolliert und mit dem Meilenstein 3.0.0 gekennzeichnet. Wenn Sie Ideen oder Kommentare zu dem haben, was Sie gerne sehen würden, melden Sie bitte ein Problem zu diesem Projekt!

• Die Optionen zur Lokalisierung der Fallback-Zahlenformatierung sollten in den Moment Locale-Objekterweiterungen enthalten sein, die dieses Plugin bereits für die Lokalisierung von Bezeichnungen von Dauereinheiten hinzufügt. Dadurch würde die gesamte Lokalisierungskonfiguration an einem Ort zusammengefasst.

• moment-duration-format und seine Fallback-Zahlenformatierungsfunktion folgen nicht derselben API wie Number#toLocaleString für signifikante Ziffern und Fraktionsziffern. Die Fallback-Funktion sollte aktualisiert werden, um die toLocaleString -API zu verwenden, und das Plugin sollte die API-Optionen direkt verfügbar machen, anstatt einige der Optionen auszublenden und sie hinter den Optionen precision und useSignificantDigits zu maskieren.

• Das Offenlegen der Fallback-Zahlenformatierungsfunktion sowie der Formatierungsfunktionstestfunktion würde das Testen erleichtern und ermöglichen, sie außerhalb des Kontexts der Formatierungsdauern zu verwenden.

---

Installation

Das Plugin hängt von moment.js ab, das in der aktuell veröffentlichten Version nicht als Paketabhängigkeit angegeben ist.

Node.js

npm install moment-duration-format

Laube

bower install moment-duration-format

Browser

<script src="path/to/moment-duration-format.js"></script>

---

Verwendung

Dieses Plugin wird immer versuchen, sich selbst auf der root.moment -Instanz zu installieren, sofern diese vorhanden ist.

Dieses Plugin installiert seine Setup-Funktion in root.momentDurationFormatSetup , sodass es später auf jeder Moment-Instanz aufgerufen werden kann.

Browser

Wenn Sie dieses Plugin im Browser verwenden und moment.js nicht zuerst in Ihre Seite einbinden, müssen Sie window.momentDurationFormatSetup manuell für Ihre Moment-Instanz aufrufen, sobald diese erstellt wurde.

Modul

Um dieses Plugin als Modul zu verwenden, verwenden Sie die Funktion require .

 var moment = require ( "moment" ) ;
var momentDurationFormatSetup = require ( "moment-duration-format" ) ;

Das Plugin exportiert die Init-Funktion, sodass das Dauerformat für andere Momentinstanzen initialisiert werden kann.

Um dieses Plugin mit einem anderen moment.js-Paket zu verwenden, zum Beispiel moment-timezone , rufen Sie manuell die exportierte Setup-Funktion auf, um das Plugin im gewünschten Paket zu installieren.

 var moment = require ( "moment-timezone" ) ;
var momentDurationFormatSetup = require ( "moment-duration-format" ) ;

momentDurationFormatSetup ( moment ) ;
typeof moment . duration . fn . format === "function" ;
// true
typeof moment . duration . format === "function" ;
// true

Grundlagen

Formatieren einer einzelnen Dauer

 moment . duration . fn . format

Die Methode duration.fn.format kann jede beliebige Momentdauer formatieren. Wenn keine Vorlage oder andere Argumente angegeben werden, generiert die Standardvorlagenfunktion eine Vorlagenzeichenfolge basierend auf dem Wert der Dauer.

 moment . duration ( 123 , "minutes" ) . format ( ) ;
// "2:03:00"

moment . duration ( 123 , "months" ) . format ( ) ;
// "10 years, 3 months"

Die Methode zur Dauerformatierung kann mit drei optionalen Argumenten aufgerufen werden und gibt eine formatierte Zeichenfolge zurück.

 moment . duration ( value , units ) . format ( [ template ] [ , precision ] [ , settings ] )
// formattedString 

Formatieren mehrerer Dauern

 moment . duration . format

Die Methode duration.format ermöglicht die koordinierte Formatierung mehrerer Momentdauern gleichzeitig. Diese Funktion akzeptiert als erstes Argument ein Array von Dauern und anschließend dieselben drei optionalen Argumente wie die Funktion duration.fn.format . Diese Funktion gibt ein Array formatierter Zeichenfolgen zurück.

 moment . duration . format ( durationsArray , [ template ] [ , precision ] [ , settings ] ) ;
// formattedStringsArray

Alle Optionen, die für die Formatfunktion für eine einzelne Dauer verfügbar sind, können mit der Formatfunktion für mehrere Dauern verwendet werden. Zur Formatierung jeder einzelnen Dauer wird ein einzelnes Einstellungsobjekt verwendet.

 moment . duration . format ( [
    moment . duration ( 1 , "second" ) ,
    moment . duration ( 1 , "minute" ) ,
    moment . duration ( 1 , "hour" )
] , "d [days] hh:mm:ss" ) ;
// ["0:00:01", "0:01:00", "1:00:00"] 

Ungültige Dauer

Ungültige Dauern werden für die Formatierung so behandelt, als hätten sie den Wert 0 .

 var invalidDuration = moment . duration ( NaN , "second" ) ;

invalidDuration . isValid ( ) ;
// false

invalidDuration . format ( ) ;
// "0 seconds"

Vorlage

template (Zeichenfolge|Funktion) ist die Zeichenfolge, die zum Erstellen der formatierten Ausgabe verwendet wird, oder eine Funktion, die die Zeichenfolge zurückgibt, die als Formatvorlage verwendet werden soll.

Vorlagenzeichenfolge

 moment . duration ( 123 , "minutes" ) . format ( "h:mm" ) ;
// "2:03"

Die Vorlagenzeichenfolge wird nach Moment-Token-Zeichen analysiert, die durch den Wert der Dauer für jeden Einheitentyp ersetzt werden. Die Moment-Token sind:

 years:   Y or y
months:  M
weeks:   W or w
days:    D or d
hours:   H or h
minutes: m
seconds: s
ms:      S

Escape-Token-Zeichen innerhalb der Vorlagenzeichenfolge in eckigen Klammern verwenden.

 moment . duration ( 123 , "minutes" ) . format ( "h [hrs], m [min]" ) ;
// "2 hrs, 3 mins" 

Tokenlänge

Für einige Zeitdauerformate ist ein mit Nullen aufgefüllter Wert erforderlich. Verwenden Sie mehrere Token-Zeichen zusammen, um die richtige Füllmenge zu erzielen.

 moment . duration ( 3661 , "seconds" ) . format ( "h:mm:ss" ) ;
// "1:01:01"

moment . duration ( 15 , "seconds" ) . format ( "sss [s]" ) ;
// "015 s"

Wenn die Formatvorlage gekürzt wird, kann auch die Tokenlänge auf dem gerenderten Token mit der größten Größe gekürzt werden. Weitere Einzelheiten finden Sie in den Abschnitten trim und forceLength weiter unten.

 moment . duration ( 123 , "seconds" ) . format ( "h:mm:ss" ) ;
// "2:03" 

Millisekunden-Token-Länge

Die Tokenlänge 2 für Millisekunden ist ein Sonderfall und wird höchstwahrscheinlich zum Rendern von Millisekunden als Teil einer Timer-Ausgabe verwendet, z. B. mm:ss:SS . In diesem Fall wird der Millisekundenwert auf drei Ziffern aufgefüllt und dann von links abgeschnitten, um eine zweistellige Ausgabe zu erhalten.

 moment . duration ( 9 , "milliseconds" ) . format ( "mm:ss:SS" , {
    trim : false
} ) ;
// "00:00:00"

moment . duration ( 10 , "milliseconds" ) . format ( "mm:ss:SS" , {
    trim : false
} ) ;
// "00:00:01"

moment . duration ( 999 , "milliseconds" ) . format ( "mm:ss:SS" , {
    trim : false
} ) ;
// "00:00:99"

moment . duration ( 1011 , "milliseconds" ) . format ( "mm:ss:SS" , {
    trim : false
} ) ;
// "00:01:01" 

Mehrere Token-Instanzen

Token können in der Formatvorlage mehrfach vorkommen, alle Instanzen müssen jedoch dieselbe Länge haben. Ist dies nicht der Fall, werden alle Instanzen mit der Länge des ersten Tokens dieses Typs gerendert.

 moment . duration ( 15 , "seconds" ) . format ( "ssss sss ss s" ) ;
// "0015 0015 0015 0015"

moment . duration ( 15 , "seconds" ) . format ( "s ss sss ssss" ) ;
// "15 15 15 15" 

Standardvorlagenfunktion

Die Standardvorlagenfunktion versucht, eine Dauer basierend auf ihrer Größe zu formatieren. Je größer der Wert für die Dauer ist, desto größer sind die Einheiten der formatierten Ausgabe.

Bei einigen Dauerwerten trim die Standardvorlagenfunktion standardmäßig auf "both" wenn diese Option nicht im Einstellungsobjekt festgelegt ist (mehr dazu weiter unten).

Die Standardvorlagenfunktion verwendet automatisch lokalisierte Einheitenbezeichnungen (mehr dazu weiter unten).

 moment . duration ( 100 , "milliseconds" ) . format ( ) ;
// "100 milliseconds"

moment . duration ( 100 , "seconds" ) . format ( ) ;
// "1:40"

moment . duration ( 100 , "days" ) . format ( ) ;
// "3 months, 9 days"

moment . duration ( 100 , "weeks" ) . format ( ) ;
// "1 year, 10 months, 30 days"

moment . duration ( 100 , "months" ) . format ( ) ;
// "8 years, 4 months" 

Benutzerdefinierte Vorlagenfunktion

Verwenden Sie eine benutzerdefinierte Vorlagenfunktion, wenn Sie Laufzeitkontrolle über die Vorlagenzeichenfolge benötigen. Vorlagenfunktionen werden mit einer this Bindung des Einstellungsobjekts ausgeführt und haben über this.duration Zugriff auf das zugrunde liegende Dauerobjekt. Auf alle Einstellungen kann über die Vorlagenfunktion zugegriffen oder diese geändert werden.

Diese benutzerdefinierte Vorlagenfunktion verwendet eine andere Vorlage basierend auf dem Wert der Dauer:

 function customTemplate ( ) {
    return this . duration . asSeconds ( ) >= 86400 ? "w [weeks], d [days]" : "hh:mm:ss" ;
}

moment . duration ( 65 , 'seconds' ) . format ( customTemplate , {
    trim : false
} ) ;
// "00:01:05"

moment . duration ( 1347840 , 'seconds' ) . format ( customTemplate , {
    trim : false
} ) ;
// "2 weeks, 2 days" 

Interpunktion kürzen

Um eine benutzerfreundliche formatierte Ausgabe zu gewährleisten, werden Satzzeichen am Anfang und Ende der formatierten Ausgabe abgeschnitten. Insbesondere der führende und der nachgestellte Punkt . , Komma , , Doppelpunkt : und Leerzeichen Zeichen werden entfernt.

Präzision

precision (Zahl) definiert die Anzahl der Dezimalbrüche oder ganzzahligen Ziffern, die für den Endwert angezeigt werden sollen.

Der Standardwert für die Genauigkeit ist 0 .

 moment . duration ( 123 , "minutes" ) . format ( "h [hrs]" ) ;
// "2 hrs"

Die positive Genauigkeit definiert die Anzahl der anzuzeigenden Dezimalbruchstellen.

 moment . duration ( 123 , "minutes" ) . format ( "h [hrs]" , 2 ) ;
// "2.05 hrs"

Die negative Genauigkeit definiert die Anzahl der ganzzahligen Ziffern, die auf Null gekürzt werden sollen.

 moment . duration ( 223 , "minutes" ) . format ( "m [min]" , - 2 ) ;
// "200 mins"

Einstellungen

settings ist ein Objekt, das alle Standardoptionen für das Momentdauerformat überschreiben kann.

Sowohl das template als auch das precision können als Eigenschaften eines einzelnen settings angegeben oder separat zusammen mit einem optionalen Einstellungsobjekt übergeben werden.

 moment . duration ( 123 , "minutes" ) . format ( {
    template : "h [hrs]" ,
    precision : 2
} ) ;
// "2.05 hrs" 

trimmen

Das standardmäßige trim ist "large" .

Token mit der größten Größe werden automatisch gekürzt, wenn sie keinen Wert haben.

 moment . duration ( 123 , "minutes" ) . format ( "d[d] h:mm:ss" ) ;
// "2:03:00"

Das Trimmen funktioniert auch, wenn die Formatzeichenfolge so ausgerichtet ist, dass die Tokengröße von links nach rechts zunimmt.

 moment . duration ( 123 , "minutes" ) . format ( "s [seconds], m [minutes], h [hours], d [days]" ) ;
// "0 seconds, 3 minutes, 2 hours"

Um das Trimmen ganz zu stoppen, legen Sie { trim: false } fest.

 moment . duration ( 123 , "minutes" ) . format ( "d[d] h:mm:ss" , {
    trim : false
} ) ;
// "0d 2:03:00"

Beim Formatieren mehrerer Dauern mit moment.duration.format wird das Zuschneiden für alle Dauern auf der Vereinigungsmenge der Dauern koordiniert.

 moment . duration . format ( [
    moment . duration ( 1 , "minute" ) ,
    moment . duration ( 1 , "hour" ) ,
    moment . duration ( 1 , "day" )
] , "y [years], w [weeks], d [days], h [hours], m [minutes]" ) ;
// [
//    "0 days, 0 hours, 1 minute",
//    "0 days, 1 hour, 0 minutes",
//    "1 day, 0 hours, 0 minutes"
// ]

trim kann eine Zeichenfolge, eine durch Trennzeichen getrennte Liste von Zeichenfolgen, ein Array von Zeichenfolgen oder ein boolescher Wert sein. Akzeptierte Werte sind wie folgt:

• "large"

Schneiden Sie Nullwert-Tokens mit der größten Größe ab, bis ein Token mit einem Wert, ein als stopTrim identifiziertes Token oder das letzte Token der Formatzeichenfolge gefunden wird. Dies ist der Standard- trim .

 moment . duration ( 123 , "minutes" ) . format ( "d[d] h:mm:ss" ) ;
// "2:03:00"

moment . duration ( 123 , "minutes" ) . format ( "d[d] h:mm:ss" , {
    trim : "large"
} ) ;
// "2:03:00"

moment . duration ( 0 , "minutes" ) . format ( "d[d] h:mm:ss" , {
    trim : "large"
} ) ;
// "0" 

• "small"

Trimmen Sie Nullwert-Token mit der kleinsten Größe, bis ein Token mit einem Wert, ein als stopTrim identifiziertes Token oder das letzte Token der Formatzeichenfolge gefunden wird.

 moment . duration ( 123 , "minutes" ) . format ( "d[d] h:mm:ss" , {
    trim : "small"
} ) ;
// "0d 2:03"

moment . duration ( 0 , "minutes" ) . format ( "d[d] h:mm:ss" , {
    trim : "small"
} ) ;
// "0d" 

• "both"

Führen Sie "large" Schnitt und dann "small" Schnitt durch.

 moment . duration ( 123 , "minutes" ) . format ( "d[d] h[h] m[m] s[s]" , {
    trim : "both"
} ) ;
// "2h 3m"

moment . duration ( 0 , "minutes" ) . format ( "d[d] h[h] m[m] s[s]" , {
    trim : "both"
} ) ;
// "0s" 

• "mid"

Schneiden Sie alle Token mit dem Wert Null ab, die nicht die ersten oder letzten Token sind. Wird normalerweise in Verbindung mit "large" oder "both" verwendet. zB "large mid" oder "both mid" .

 moment . duration ( 1441 , "minutes" ) . format ( "w[w] d[d] h[h] m[m] s[s]" , {
    trim : "mid"
} ) ;
// "0w 1d 1m 0s"

moment . duration ( 1441 , "minutes" ) . format ( "w[w] d[d] h[h] m[m] s[s]" , {
    trim : "large mid"
} ) ;
// "1d 1m 0s"

moment . duration ( 1441 , "minutes" ) . format ( "w[w] d[d] h[h] m[m] s[s]" , {
    trim : "small mid"
} ) ;
// "0w 1d 1m"

moment . duration ( 1441 , "minutes" ) . format ( "w[w] d[d] h[h] m[m] s[s]" , {
    trim : "both mid"
} ) ;
// "1d 1m"

moment . duration ( 0 , "minutes" ) . format ( "w[w] d[d] h[h] m[m] s[s]" , {
    trim : "both mid"
} ) ;
// "0s" 

• "final"

Schneiden Sie das letzte Token ab, wenn es einen Nullwert hat. Verwenden Sie diese Option mit "large" oder "both" um beim Formatieren einer Nullwertdauer eine leere Zeichenfolge auszugeben. zB "large final" oder "both final" .

 moment . duration ( 0 , "minutes" ) . format ( "d[d] h:mm:ss" , {
    trim : "large final"
} ) ;
// ""

moment . duration ( 0 , "minutes" ) . format ( "d[d] h:mm:ss" , {
    trim : "small final"
} ) ;
// ""

moment . duration ( 0 , "minutes" ) . format ( "d[d] h[h] m[m] s[s]" , {
    trim : "both final"
} ) ;
// "" 

• "all"

Schneiden Sie alle Nullwert-Token ab. Abkürzung für "both mid final" .

 moment . duration ( 0 , "minutes" ) . format ( "d[d] h[h] m[m] s[s]" , {
    trim : "all"
} ) ;
// "" 

• "left"

Wird auf "large" abgebildet, um die API der Version 1 dieses Plugins zu unterstützen.

• "right"

Wird auf "large" abgebildet, um die API der Version 1 dieses Plugins zu unterstützen.

• true

Karten auf "large" .

• null

Karten auf "large" .

• false

Deaktiviert das Trimmen.

größte

Setzen Sie largest auf eine positive ganze Zahl, um nur die n Moment-Tokens mit der größten Größe auszugeben, beginnend mit dem Token mit der größten Größe, das einen Wert hat.

Wenn Sie die largest Option verwenden, wird standardmäßig auf "all" trim .

 moment . duration ( 7322 , "seconds" ) . format ( "d [days], h [hours], m [minutes], s [seconds]" , {
    largest : 2
} ) ;
// "2 hours, 2 minutes"

moment . duration ( 1216800 , "seconds" ) . format ( "y [years], w [weeks], d [days], h [hours], m [minutes], s [seconds]" , {
    largest : 3
} ) ;
// "2 weeks, 2 hours"

Wenn Sie trim auf einen anderen Wert festlegen oder stopTrim verwenden, können sowohl das Starttoken als auch die verbleibende Ausgabe geändert werden.

 moment . duration ( 1216800 , "seconds" ) . format ( "y [years], w [weeks], d [days], h [hours], m [minutes], s [seconds]" , {
    largest : 3 ,
    trim : "both"
} ) ;
// "2 weeks, 0 days, 2 hours"

moment . duration ( 1216800 , "seconds" ) . format ( "y [years], w [weeks], d [days], h [hours], m [minutes], s [seconds]" , {
    largest : 3 ,
    trim : "both" ,
    stopTrim : "m"
} ) ;
// "2 weeks, 0 days, 2 hours"

moment . duration ( 1216800 , "seconds" ) . format ( "y [years], w [weeks], d [days], h [hours], m [minutes], s [seconds]" , {
    largest : 4 ,
    trim : false