moment duration format

Format de durée du moment

Plugin de formatage pour l'objet Moment Duration.

Il s'agit d'un plugin pour la bibliothèque de dates JavaScript Moment.js pour ajouter un formatage complet aux durées des moments.

La grammaire du modèle de format est calquée sur la grammaire du modèle de format Moment Date existante, avec quelques modifications car les durées sont fondamentalement différentes des dates.

Ce plugin n'a aucune dépendance au-delà de Moment.js lui-même et peut être utilisé dans le navigateur et dans Node.js.

---

Formatage des nombres et tests

Lorsqu'il est disponible et fonctionnel, ce plugin utilise soit Intl.NumberFormat#format , soit Number#toLocaleString pour restituer une sortie numérique formatée. Malheureusement, de nombreux environnements n'implémentent pas entièrement la suite complète d'options dans leurs spécifications respectives, et certains fournissent une implémentation boguée.

Ce plugin exécute un test de fonctionnalité pour chaque formateur et reviendra à une fonction de secours pour restituer une sortie numérique formatée si le test de fonctionnalité échoue. Pour forcer ce plugin à toujours utiliser la fonction de format de numéro de secours, définissez useToLocaleString sur false . La sortie de la fonction de format de numéro de secours peut être localisée à l’aide des options détaillées au bas de cette page. En général, vous devez spécifier les options de formatage des nombres de secours si le formatage local "en" par défaut est inacceptable sur certains appareils ou dans certains environnements.

Ce plugin est testé à l'aide de BrowserStack sur une gamme d'appareils Android avec des versions de système d'exploitation de 2.2 à 7, et sur une gamme d'appareils iOS avec des versions de système d'exploitation de 4.3 à 11. Également testé sur les navigateurs Chrome, Firefox, IE 8-11 et Edge. .

Veuillez soulever un problème si vous remarquez des problèmes de formatage ou des anomalies dans n'importe quel environnement !

---

Feuille de route

Version 2

Il reste quelques éléments pour terminer la version 2 :

• Ajoutez des définitions de type pour prendre en charge TypeScript, publiez le package NuGet et prenez en charge toutes les autres options d'empaquetage utilisées de nos jours.

• Les tests du plugin doivent être modernisés, idéalement pour correspondre à la configuration de test Moment.js.

Version 3

Ayant implémenté la version 2 du plugin moment-duration-format, il y a quelques améliorations évidentes pour une version 3.

Les idées ci-dessous sont enregistrées en tant que problèmes et marquées du jalon 3.0.0. Si vous avez des idées ou des commentaires sur ce que vous aimeriez voir, veuillez signaler un problème sur ce projet !

• Les options de localisation de formatage des nombres de secours doivent être incluses avec les extensions d'objet Moment Locale que ce plugin ajoute déjà pour localiser les étiquettes d'unités de durée. Cela mettrait toute la configuration de localisation au même endroit.

• moment-duration-format et sa fonction de formatage de nombre de secours ne suivent pas la même API que Number#toLocaleString pour les chiffres significatifs et les chiffres de faction. La fonction de secours doit être mise à jour pour utiliser l'API toLocaleString , et le plugin doit exposer les options de l'API directement plutôt que de masquer certaines options et de les masquer derrière les options precision et useSignificantDigits .

• Exposer la fonction de formatage des nombres de secours ainsi que la fonction de test des fonctionnalités du formateur faciliterait les tests et permettrait de les utiliser en dehors du contexte des durées de formatage.

---

Installation

Le plugin dépend de moment.js, qui n'est pas spécifié comme dépendance de package dans la version actuellement publiée.

Noeud.js

npm install moment-duration-format

Tonnelle

bower install moment-duration-format

Navigateur

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

---

Usage

Ce plugin tentera toujours de s'installer sur l'instance root.moment , si elle existe.

Ce plugin installera sa fonction de configuration sur root.momentDurationFormatSetup afin qu'il puisse être appelé ultérieurement à tout moment.

Navigateur

Lorsque vous utilisez ce plugin dans le navigateur, si vous n'incluez pas d'abord moment.js sur votre page, vous devez appeler manuellement window.momentDurationFormatSetup sur votre instance moment une fois qu'elle est créée.

Module

Pour utiliser ce plugin comme module, utilisez la fonction require .

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

Le plugin exporte la fonction init afin que le format de durée puisse être initialisé sur d'autres instances de moment.

Pour utiliser ce plugin avec n'importe quel autre package moment.js, par exemple moment-timezone , appelez manuellement la fonction de configuration exportée pour installer le plugin dans le package souhaité.

 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

Les bases

Formatage d'une durée unique

 moment . duration . fn . format

La méthode duration.fn.format peut formater n’importe quelle durée d’instant. Si aucun modèle ou autre argument n'est fourni, la fonction de modèle par défaut générera une chaîne de modèle basée sur la valeur de la durée.

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

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

La méthode de format de durée peut être appelée avec trois arguments facultatifs et renvoie une chaîne formatée.

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

Formatage de plusieurs durées

 moment . duration . format

La méthode duration.format permet un formatage coordonné de plusieurs durées de moment à la fois. Cette fonction accepte un tableau de durées comme premier argument, puis les trois mêmes arguments facultatifs que la fonction duration.fn.format . Cette fonction renvoie un tableau de chaînes formatées.

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

Toutes les options disponibles pour la fonction de format de durée unique peuvent être utilisées avec la fonction de format de durée multiple. Un seul objet de paramètres est utilisé pour formater chacune des durées individuelles.

 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"] 

Durées invalides

Les durées non valides sont traitées comme ayant une valeur de 0 pour le formatage.

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

invalidDuration . isValid ( ) ;
// false

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

Modèle

template (string|function) est la chaîne utilisée pour créer la sortie formatée, ou une fonction qui renvoie la chaîne à utiliser comme modèle de format.

Chaîne de modèle

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

La chaîne du modèle est analysée pour les caractères de jeton de moment, qui sont remplacés par la valeur de durée pour chaque type d'unité. Les jetons du moment sont :

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

Échappez les caractères du jeton dans la chaîne du modèle à l'aide de crochets.

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

Longueur du jeton

Pour certains formats de durée, une valeur complétée par des zéros est requise. Utilisez plusieurs caractères symboliques ensemble pour créer la quantité correcte de remplissage.

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

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

Lorsque le modèle de format est rogné, la longueur du jeton rendu de plus grande magnitude peut également être rognée. Voir les sections trim et forceLength ci-dessous pour plus de détails.

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

Longueur du jeton en millisecondes

La longueur du jeton de 2 pour les millisecondes est un cas particulier, très probablement utilisé pour restituer les millisecondes dans le cadre d'une sortie de minuterie, telle que mm:ss:SS . Dans ce cas, la valeur en millisecondes est complétée à trois chiffres, puis tronquée à partir de la gauche pour afficher une sortie à deux chiffres.

 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" 

Plusieurs instances de jetons

Les jetons peuvent apparaître plusieurs fois dans le modèle de format, mais toutes les instances doivent partager la même longueur. Si ce n’est pas le cas, toutes les instances seront rendues à la longueur du premier jeton de ce type.

 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" 

Fonction de modèle par défaut

La fonction de modèle par défaut tente de formater une durée en fonction de son ampleur. Plus la valeur de durée est grande, plus les unités de la sortie formatée seront grandes.

Pour certaines valeurs de durée, la fonction de modèle par défaut trim par défaut sur "both" si cette option n'est pas définie dans l'objet de paramètres (plus d'informations ci-dessous).

La fonction de modèle par défaut utilise des étiquettes d'unités auto-localisées (plus d'informations à ce sujet ci-dessous également).

 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" 

Fonction de modèle personnalisé

Utilisez une fonction de modèle personnalisée si vous avez besoin d'un contrôle d'exécution sur la chaîne du modèle. Les fonctions de modèle sont exécutées avec une liaison this de l'objet settings et ont accès à l'objet de durée sous-jacent via this.duration . Tous les paramètres peuvent être consultés ou modifiés par la fonction de modèle.

Cette fonction de modèle personnalisé utilise un modèle différent en fonction de la valeur de la durée :

 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" 

Coupe de ponctuation

Pour garantir une sortie formatée conviviale, les caractères de ponctuation sont coupés au début et à la fin de la sortie formatée. Plus précisément, les périodes de début et de fin . , virgule , , deux-points : et espace les caractères sont supprimés.

Précision

precision (nombre) définit le nombre de fractions décimales ou de chiffres entiers à afficher pour la valeur finale.

La valeur de précision par défaut est 0 .

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

La précision positive définit le nombre de chiffres de fraction décimale à afficher.

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

La précision négative définit le nombre de chiffres entiers à tronquer à zéro.

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

Paramètres

settings est un objet qui peut remplacer n’importe quelle option de format de durée de moment par défaut.

Les arguments template et precision peuvent être spécifiés en tant que propriétés d’un seul argument d’objet settings , ou ils peuvent être transmis séparément avec un objet de paramètres facultatif.

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

garniture

Le comportement trim par défaut est "large" .

Les jetons de plus grande magnitude sont automatiquement supprimés lorsqu'ils n'ont aucune valeur.

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

Le découpage fonctionne également lorsque la chaîne de format est orientée avec une magnitude de jeton augmentant de gauche à droite.

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

Pour arrêter complètement le découpage, définissez { trim: false } .

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

Lors du formatage de plusieurs durées à l'aide de moment.duration.format , le découpage de toutes les durées est coordonné sur l'union de l'ensemble des durées.

 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 peut être une chaîne, une liste délimitée de chaînes, un tableau de chaînes ou un booléen. Les valeurs acceptées sont les suivantes :

• "large"

Supprimez les jetons de valeur nulle de plus grande magnitude jusqu'à trouver un jeton avec une valeur, un jeton identifié comme stopTrim ou le jeton final de la chaîne de format. Il s'agit de la valeur trim par défaut.

 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"

Supprimez les jetons de valeur nulle de plus petite magnitude jusqu'à trouver un jeton avec une valeur, un jeton identifié comme stopTrim ou le jeton final de la chaîne de format.

 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"

Exécutez "large" découpage, puis "small" découpage.

 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"

Supprimez tous les jetons de valeur nulle qui ne sont pas les premiers ou les derniers jetons. Habituellement utilisé en conjonction avec "large" ou "both" . par exemple "large mid" ou "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"

Coupez le jeton final s'il a une valeur nulle. Utilisez cette option avec "large" ou "both" pour afficher une chaîne vide lors du formatage d'une durée de valeur nulle. par exemple "large final" ou "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"

Coupez tous les jetons de valeur nulle. Raccourci pour "both mid final" .

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

• "left"

Mappé sur "large" pour prendre en charge l'API version 1 de ce plugin.

• "right"

Mappé sur "large" pour prendre en charge l'API version 1 de ce plugin.

• true

Cartes à "large" .

• null

Cartes à "large" .

• false

Désactive le découpage.

le plus grand

Définissez largest sur un entier positif pour afficher uniquement les n jetons de moment de plus grande magnitude, en commençant par le jeton de plus grande magnitude qui a une valeur.

En utilisant la largest option, trim par défaut est "all" .

 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"

Définir trim sur une valeur différente ou utiliser stopTrim peut modifier le jeton de départ ainsi que la sortie restante.

 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