Day.js 有表示时间长度的对象。 将 Day.js 对象定义为单个时间点,将 duration 定义为时间的长度。
时长没有定义的开始和结束日期。 它们是无上下文的。
从概念上讲,时长比 '今天下午2点到4点之间' 更类似于 '2 小时'。 因此,在依赖上下文的时间单位之间的转换中,时长并不是一个合适的选择。
例如,一年可以定义为366天、365天、365.25天、12个月、52周。 没有上下文,试图将年转换为天是毫无意义的。 与使用 Durations 相比,使用 dayjs#diff 计算两个时刻之间的天数或年数要好得多。
注意
此功能依赖 Duration 插件
dayjs.extend(duration)
dayjs.duration({ months: 12 })
# 创建
要创建时长,则调用 dayjs.duration()
,并以毫秒为单位。
注意
此功能依赖 Duration 插件
dayjs.extend(duration)
dayjs.duration(100); // 100 milliseconds
如果要使用毫秒以外的其他度量单位来创建时长对象,则也可以传入度量单位。
dayjs.duration(2, 'days');
支持的单位列表:
单位 | 缩写 |
---|---|
days | d |
weeks | w |
months | M |
years | y |
hours | h |
minutes | m |
seconds | s |
milliseconds | ms |
如果需要同时传入多个不同的度量单位,则可以传入值的对象。
dayjs.duration({
seconds: 2,
minutes: 2,
hours: 2,
days: 2,
weeks: 2,
months: 2,
years: 2
});
Day.js 也支持解析 ISO 8601 时长格式。
dayjs.duration('P1Y2M3DT4H5M6S');
dayjs.duration('P1M');
# 克隆
dayjs.duration().clone();
复制一个时长对象。 时长是不可变的,就像 Day.js 对象一样。 当然,这可以用来保存在某个时间点的快照。
# 人性化
当仅仅是想显示一段时长,要得到类似 dayjs#from 的结果,但又不想创建两个 Day.js 对象时。
注意
此功能依赖 Duration 插件,才能正常运行
注意
此功能依赖 RelativeTime 插件,才能正常运行
dayjs.extend(duration)
dayjs.extend(relativeTime)
dayjs.duration(1, "minutes").humanize(); // a minute
dayjs.duration(2, "minutes").humanize(); // 2 minutes
dayjs.duration(24, "hours").humanize(); // a day
默认情况下,返回的字符串是没有后缀。 如果需要后缀,则按如下所示传入 true。
dayjs.duration(1, "minutes").humanize(true); // in a minute
对于当前时间之前的后缀,则传入负数。
dayjs.duration(-1, "minutes").humanize(true); // a minute ago
# 格式化
根据传入的占位符返回格式化后的时长。
将字符放在方括号中,即可原样返回而不被格式化替换 (例如, [MM
])。
dayjs.duration({
seconds: 1,
minutes: 2,
hours: 3,
days: 4,
months: 6,
years: 7
}).format('YYYY-MM-DDTHH:mm:ss') // 0007-06-04T03:02:01
支持的格式化占位符列表:
Format | 输出 | 详情 |
---|---|---|
Y | 18 | 年 |
YY | 18 | 年,两位数 |
YYYY | 2018 | 年,四位数 |
M | 1-12 | 月份,从 1 开始 |
MM | 01-12 | 月份,两位数 |
D | 1-31 | 日 |
DD | 01-31 | 日,两位数 |
H | 0-23 | 小时 |
HH | 00-23 | 小时,两位数 |
m | 0-59 | 分钟 |
mm | 00-59 | 分钟,两位数 |
s | 0-59 | 秒 |
ss | 00-59 | 秒,两位数 |
SSS | 000-999 | 毫秒,三位数 |
# 毫秒
要获取时长的毫秒数,请使用 dayjs.duration().milliseconds()
。
它将返回0到999之间的数字。
dayjs.duration(500).milliseconds(); // 500
dayjs.duration(1500).milliseconds(); // 500
dayjs.duration(15000).milliseconds(); // 0
如果想得到要以毫秒为单位时长长度,则改用 dayjs.duration().asMilliseconds()
。
dayjs.duration(500).asMilliseconds(); // 500
dayjs.duration(1500).asMilliseconds(); // 1500
dayjs.duration(15000).asMilliseconds(); // 15000
# 秒
要获取时长的秒数,请使用 dayjs.duration().seconds()
。
它将返回0到59之间的数字。
dayjs.duration(500).seconds(); // 0
dayjs.duration(1500).seconds(); // 1
dayjs.duration(15000).seconds(); // 15
如果想得到要以秒为单位时长长度,则改用 dayjs.duration().asSeconds()
。
dayjs.duration(500).asSeconds(); // 0.5
dayjs.duration(1500).asSeconds(); // 1.5
dayjs.duration(15000).asSeconds(); // 15
# 分钟
dayjs.duration().minutes();
dayjs.duration().asMinutes();
和其他 getters 类似, dayjs.duration().minutes()
用来获取时长的分钟部分 (0-59)。
dayjs.duration().asMinutes()
获取以分钟为单位的时长。
# 小时
dayjs.duration().hours();
dayjs.duration().asHours();
和其他 getters 类似, dayjs.duration().hours()
用来获取时长的小时部分 (0-23)。
dayjs.duration().asHours()
获取以小时为单位的时长。
# 日
dayjs.duration().days();
dayjs.duration().asDays();
和其他 getters 类似, dayjs.duration().days()
用来获取时长的天部分 (0-30)。
dayjs.duration().asDays()
获取以天为单位的时长。
# 周
dayjs.duration().weeks();
dayjs.duration().asWeeks();
和其他 getters 类似, dayjs.duration().weeks()
用来获取时长的周部分 (0-4)。
dayjs.duration().asWeeks()
获取以周为单位的时长。
与时长的其他 getter 不同,周数是作为天数的子集,且不会从天数中扣除。
注意:以周为单位的时长的长度定义为 7 天。
# 月
dayjs.duration().months();
dayjs.duration().asMonths();
和其他 getters 类似, dayjs.duration().months()
用来获取时长的月份部分 (0-11)。
dayjs.duration().asMonths()
获取以月份为单位的时长。
# 年
dayjs.duration().years();
dayjs.duration().asYears();
和其他 getters 类似, dayjs.duration().years()
用来获取时长的年部分。
dayjs.duration().asYears()
获取以年为单位的时长。
# 增加时间
返回增加一定时间的复制的时长对象。
var a = dayjs.duration(1, 'd');
var b = dayjs.duration(2, 'd');
a.add(b).days(); // 3
a.add({ days: 2 } ).days();
a.add(2, 'days');
# 减少时间
返回减去一定时间的复制的时长对象。
var a = dayjs.duration(3, 'd');
var b = dayjs.duration(2, 'd');
a.subtract(b).days(); // 1
a.subtract({ days: 2 } ).days();
a.subtract(2, 'days');
支持的可用单位同上。
# Diff时长
可以将时长与 dayjs#diff
一起使用,以获取两个时刻之间的时长。 为此,只需将 dayjs#diff
方法传给 dayjs#duration
,如下所示:
var x = dayjs()
var y = dayjs()
var duration = dayjs.duration(x.diff(y))
// 返回时长对象,其时长在 x 和 y 之间。
查看 这里 了解更多关于 dayjs#diff
的信息。
# 单位转换
作为 Duration#asX
的替代,可以使用 Duration#as('x')
。
var duration = dayjs.duration()
duration.as('hours');
duration.as('minutes');
duration.as('seconds');
duration.as('milliseconds');
支持的可用单位同上。
# 获取单位时间
作为 Duration#x()
获取器的替代,可以使用 Duration#get('x')
。
var duration = dayjs.duration
duration.get('hours');
duration.get('minutes');
duration.get('seconds');
duration.get('milliseconds');
支持的可用单位同上。
# 序列化为JSON
当将时长对象序列化为 JSON 时,它将会表示为 ISO8601 字符串。
JSON.stringify({
postDuration : dayjs.duration(5, 'm')
}); // '{"postDuration":"PT5M"}'
# 是否duration
要检查变量是否为 Day.js 时长对象,请使用 dayjs.isDuration()
。
dayjs.isDuration() // false
dayjs.isDuration(new Date()) // false
dayjs.isDuration(dayjs()) // false
dayjs.isDuration(dayjs.duration()) // true
dayjs.isDuration(dayjs.duration(2, 'minutes')) // true
# ISO 8601标准
返回 ISO 8601 (opens new window) 标准指定的字符串形式的时长。
dayjs.duration(1, 'd').toISOString() // "P1D"
格式 PnYnMnDTnHnMnS
的说明:
单位 | 描述 |
---|---|
P | P 代表周期。 放置在时长表示的开始处。 |
Y | 年 |
M | 月 |
D | 日 |
T | 在时间分量之前的指示符。 |
H | 时 |
M | 分 |
S | 秒 |
# 本地化
您可以使用 locale 获取或设置时长的国际化。 本地化会影响一些方法输出的字符串内容,例如 humanize()。 更多关于国际化的信息,请参阅 i18n 部分。
注意
此功能依赖 RelativeTime 插件
require('dayjs/locale/es')
dayjs.duration(1, "minutes").locale("en").humanize(); // a minute
dayjs.duration(1, "minutes").locale("es").humanize(); // un minuto