时长

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