Скачать moment duration format - moment duration format Скачать исходный код

Формат продолжительности момента

Плагин формата для объекта Moment Duration.

Это плагин к библиотеке дат JavaScript Moment.js, позволяющий добавить комплексное форматирование к продолжительности момента.

Грамматика шаблона формата создана по образцу существующей грамматики шаблона формата «Момент-Дата» с некоторыми изменениями, поскольку продолжительность фундаментально отличается от дат.

Этот плагин не имеет никаких зависимостей, кроме самого Moment.js, и его можно использовать в браузере и в Node.js.

Форматирование чисел и тестирование

Там, где он доступен и функционален, этот плагин использует либо Intl.NumberFormat#format , либо Number#toLocaleString для рендеринга форматированного числового вывода. К сожалению, во многих средах не полностью реализован полный набор опций, указанных в соответствующих спецификациях, а в некоторых реализована ошибка.

Этот плагин запускает проверку функций для каждого средства форматирования и возвращается к резервной функции для рендеринга форматированного числового вывода, если проверка функции не пройдена. Чтобы заставить этот плагин всегда использовать функцию резервного формата числа, установите для useToLocaleString значение false . Вывод функции резервного формата числа можно локализовать с помощью параметров, подробно описанных внизу этой страницы. Как правило, вам следует указать резервные параметры форматирования чисел, если форматирование языкового стандарта "en" по умолчанию будет неприемлемым на некоторых устройствах или в некоторых средах.

Этот плагин протестирован с помощью BrowserStack на ряде устройств Android с версиями ОС от 2.2 до 7 и на ряде устройств iOS с версиями ОС от 4.3 до 11. Также протестировано в браузерах Chrome, Firefox, IE 8-11 и Edge. .

Пожалуйста, поднимите вопрос, если вы заметили проблемы с форматированием или аномалии в любой среде!

Дорожная карта

Версия 2

Для завершения Версии 2 осталось несколько вещей:

Добавьте определения типов для поддержки TypeScript, опубликуйте пакет NuGet и поддержите любые другие варианты упаковки, используемые в настоящее время.
Тестирование плагина должно быть модернизировано, в идеале, чтобы соответствовать настройке тестирования Moment.js.

Версия 3

После реализации второй версии плагина формата момента-длительности в версии 3 есть некоторые очевидные улучшения.

Приведенные ниже идеи регистрируются как проблемы и помечаются вехой 3.0.0. Если у вас есть идеи или комментарии по поводу того, что вы хотели бы видеть, зарегистрируйте проблему в этом проекте!

Параметры локализации резервного форматирования чисел должны быть включены в расширения объектов Moment Locale, которые этот плагин уже добавляет для локализации меток единиц длительности. Это позволит собрать всю конфигурацию локализации в одном месте.
moment-duration-format и его резервная функция форматирования чисел не используют тот же API, что и Number#toLocaleString для значащих цифр и дробных цифр. Резервную функцию следует обновить для использования API toLocaleString , а плагин должен напрямую предоставлять параметры API, а не скрывать некоторые параметры и маскировать их за параметрами precision и useSignificantDigits .
Предоставление резервной функции форматирования чисел, а также функции проверки функции форматирования облегчит тестирование и позволит использовать их вне контекста длительности форматирования.

Установка

Плагин зависит от moment.js, который не указан как зависимость пакета в текущей опубликованной версии.

Node.js

npm install moment-duration-format

Бауэр

bower install moment-duration-format

Браузер

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

Использование

Этот плагин всегда будет пытаться установить себя на экземпляр root.moment , если он существует.

Этот плагин установит свою функцию настройки в root.momentDurationFormatSetup , чтобы ее можно было позже вызвать в любой момент.

Браузер

Если при использовании этого плагина в браузере вы сначала не включаете moment.js на свою страницу, вам необходимо вручную вызвать window.momentDurationFormatSetup в экземпляре момента после его создания.

Модуль

Чтобы использовать этот плагин в качестве модуля, используйте функцию require .

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

Плагин экспортирует функцию инициализации, чтобы формат продолжительности можно было инициализировать в другие моменты времени.

Чтобы использовать этот плагин с любым другим пакетом moment.js, например, moment-timezone , вручную вызовите экспортированную функцию настройки, чтобы установить плагин в нужный пакет.

 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

Основы

Форматирование одной длительности

 moment . duration . fn . format

Метод duration.fn.format может форматировать продолжительность любого момента. Если шаблон или другие аргументы не указаны, функция шаблона по умолчанию сгенерирует строку шаблона на основе значения продолжительности.

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

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

Метод формата продолжительности может быть вызван с тремя дополнительными аргументами и возвращает отформатированную строку.

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

Форматирование нескольких длительностей

 moment . duration . format

Метод duration.format позволяет скоординировать форматирование нескольких длительностей моментов одновременно. Эта функция принимает массив длительностей в качестве первого аргумента, а затем те же три дополнительных аргумента, что и duration.fn.format . Эта функция возвращает массив форматированных строк.

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

Все параметры, доступные для функции формата одной длительности, можно использовать с функцией формата нескольких длительностей. Для форматирования каждой отдельной длительности используется один объект настроек.

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

Неверная длительность

Недопустимая длительность рассматривается как имеющая значение 0 для форматирования.

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

invalidDuration . isValid ( ) ;
// false

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

Шаблон

template (строка|функция) — это строка, используемая для создания форматированного вывода, или функция, возвращающая строку, которая будет использоваться в качестве шаблона формата.

Строка шаблона

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

Строка шаблона анализируется на наличие символов токена момента, которые заменяются значением продолжительности для каждого типа единицы. Моментные токены:

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

Экранируйте символы токена в строке шаблона с помощью квадратных скобок.

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

Длина токена

Для некоторых форматов продолжительности времени требуется значение, дополненное нулями. Используйте несколько символов-токенов вместе, чтобы создать правильное количество дополнений.

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

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

Когда шаблон формата обрезается, длину отображаемого токена наибольшей величины также можно обрезать. Более подробную информацию см. в разделах Trim и ForceLength ниже.

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

Длина токена в миллисекундах

Длина токена 2 для миллисекунд — это особый случай, который, скорее всего, используется для отображения миллисекунд как части выходных данных таймера, например mm:ss:SS . В этом случае значение миллисекунд дополняется до трех цифр, а затем усекается слева, чтобы получить двухзначный результат.

 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"

Несколько экземпляров токена

Токены могут появляться в шаблоне формата несколько раз, но все экземпляры должны иметь одинаковую длину. В противном случае все экземпляры будут отображаться с длиной первого токена этого типа.

 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"

Функция шаблона по умолчанию

Функция шаблона по умолчанию пытается отформатировать длительность на основе ее величины. Чем больше значение длительности, тем больше будут единицы форматированного вывода.

Для некоторых значений длительности функция шаблона по умолчанию будет trim до "both" , если этот параметр не установлен в объекте настроек (подробнее об этом ниже).

Функция шаблона по умолчанию использует автоматически локализованные метки единиц (подробнее об этом также ниже).

 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"

Функция пользовательского шаблона

Используйте пользовательскую функцию шаблона, если вам нужен контроль над строкой шаблона во время выполнения. Функции шаблона выполняются с привязкой this объекта настроек и имеют доступ к базовому объекту продолжительности через this.duration . Любые настройки могут быть доступны или изменены с помощью функции шаблона.

Эта пользовательская функция шаблона использует другой шаблон в зависимости от значения продолжительности:

 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"

Удаление пунктуации

Чтобы обеспечить удобство форматированного вывода, знаки пунктуации обрезаются в начале и конце форматированного вывода. В частности, ведущий и конечный период . , запятая , , двоеточие : и пробел символы удаляются.

Точность

precision (число) определяет количество десятичных дробей или целых цифр, отображаемых для окончательного значения.

Значение точности по умолчанию — 0 .

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

Положительная точность определяет количество отображаемых цифр десятичной дроби.

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

Отрицательная точность определяет количество целых цифр, которые необходимо обрезать до нуля.

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

Настройки

settings — это объект, который может переопределить любой из параметров формата продолжительности момента по умолчанию.

Аргументы template и precision могут быть указаны как свойства одного аргумента объекта settings или они могут быть переданы отдельно вместе с необязательным объектом настроек.

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

подрезать

Поведение trim по умолчанию — "large" .

Токены наибольшей величины автоматически обрезаются, когда они не имеют значения.

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

Обрезка также работает, когда строка формата ориентирована так, что величина токена увеличивается слева направо.

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

Чтобы вообще прекратить обрезку, установите { trim: false } .

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

При форматировании нескольких длительностей с использованием moment.duration.format обрезка для всех длительностей координируется по объединению набора длительностей.

 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 может быть строкой, списком строк с разделителями, массивом строк или логическим значением. Принятые значения следующие:

"large"

Обрезайте токены с нулевым значением наибольшей величины, пока не найдете токен со значением, токен, идентифицированный как stopTrim , или последний токен строки формата. Это значение 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"

Обрезайте токены с нулевым значением наименьшей величины, пока не найдете токен со значением, токен, идентифицированный как stopTrim , или последний токен строки формата.

 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"

Выполните "large" обрезку, затем "small" .

 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"

Обрежьте все токены с нулевым значением, которые не являются первыми или последними токенами. Обычно используется в сочетании с "large" или "both" . например "large mid" или "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"

Обрежьте последний токен, если он имеет нулевое значение. Используйте эту опцию с "large" или "both" для вывода пустой строки при форматировании длительности с нулевым значением. например, "large final" или "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"

Обрежьте все токены с нулевым значением. Сокращение от "both mid final" .

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

"left"

Сопоставляется с "large" для поддержки API версии 1 этого плагина.

"right"

Сопоставляется с "large" для поддержки API версии 1 этого плагина.

true

Карты "large" .

null

Карты "large" .

false

Отключает обрезку.

крупнейший

Задайте для параметра largest положительное целое число, чтобы выводить только n токенов момента наибольшей величины, начиная с токена наибольшей величины, имеющего значение.

Использование largest параметра по умолчанию trim до "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"

Установка для trim другого значения или использование stopTrim может изменить начальный токен, а также оставшийся вывод.

 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

Расширять

moment duration format

Формат продолжительности момента

Форматирование чисел и тестирование

Дорожная карта

Версия 2

Версия 3

Установка

Использование

Браузер

Модуль

Основы

Форматирование одной длительности

Форматирование нескольких длительностей

Неверная длительность

Шаблон

Строка шаблона

Длина токена

Длина токена в миллисекундах

Несколько экземпляров токена

Функция шаблона по умолчанию

Функция пользовательского шаблона

Удаление пунктуации

Точность

Настройки

подрезать

"large"

"small"

"both"

"mid"

"final"

"all"

"left"

"right"

true

null

false

крупнейший

`"large"`

`"small"`

`"both"`

`"mid"`

`"final"`

`"all"`

`"left"`

`"right"`

`true`

`null`

`false`