陈随易

Appearance

add ​

将指定的年、月、周、日、时、分、秒添加到给定的日期。

导入

js
import { add } from 'date-fns';

定义

ts
function add(
    date: DateArg<DateType>,
    duration: Duration,
    options?: AddOptions<ResultDate>
): ResultDate;

参数

名称类型描述
dateDateArg<DateType>更改日期
durationDuration需要添加年、月、周、日、时、分、秒的对象。
options?AddOptions<ResultDate>带有选项的对象

返回

类型定义
ResultDate添加了秒数的新日期

示例

js
const result = add(new Date(2014, 8, 1, 10, 19, 50), {
    years: 2,
    months: 9,
    weeks: 1,
    days: 7,
    hours: 5,
    minutes: 9,
    seconds: 30
});
//=> Thu Jun 15 2017 15:29:20

closestIndexTo ​

返回与给定日期相比数组中最接近的日期的索引。

导入

js
import { closestIndexTo } from 'date-fns';

定义

ts
function closestIndexTo(
    dateToCompare: string | number | Date,
    dates: Array<string | number | Date>
): number | undefined;

参数

名称类型描述
dateToComparestring | number | Date要比较的日期。
datesArray<string | number | Date>要搜索的日期数组。

返回

类型定义
number | undefined最接近给定日期的日期索引，如果没有给出有效值则为未定义

示例

哪一个日期更接近 2015年9月6日？

js
const dateToCompare = new Date(2015, 8, 6);
const datesArray = [
    new Date(2015, 0, 1),
    new Date(2016, 0, 1),
    new Date(2017, 0, 1)
];
const result = closestIndexTo(dateToCompare, datesArray);
//=> 1

closestTo ​

从数组中返回最接近给定日期的日期。

导入

js
import { closestTo } from 'date-fns';

定义

ts
function closestTo(
    dateToCompare: DateToCompare,
    dates: DatesType,
    options?: Options
): ClosestToResult<DateToCompare, DatesType, Options> | undefined;

参数

名称类型描述
dateToComparestring | number | Date要比较的日期。
datesDatesType要搜索的日期数组。
options?Options要搜索的日期数组。

返回

类型定义
ClosestToResult<DateToCompare, DatesType, Options> | undefined数组中最接近给定日期的日期，如果没有给出有效值，则为未定义

示例

哪个日期更接近 2015年9月6日？2000年1月1日 还是 2030年1月1日？

js
const dateToCompare = new Date(2015, 8, 6);
const result = closestTo(dateToCompare, [
    new Date(2000, 0, 1),
    new Date(2030, 0, 1)
]);
//=> Tue Jan 01 2030 00:00:00

compareAsc ​

比较两个日期，如果第一个日期在第二个日期之后则返回 1，如果第一个日期在第二个日期之前则返回 -1，如果日期相等则返回 0。

导入

js
import { compareAsc } from 'date-fns';

定义

ts
function compareAsc(
    dateLeft: string | number | Date,
    dateRight: string | number | Date
): number;

参数

名称类型描述
dateLeftstring | number | Date要比较的第一个日期。
dateRightstring | number | Date要比较的第二个日期。

返回

类型定义
number比较结果

示例

比较 1987年2月11日 和 1989年7月10日：

js
const result = compareAsc(new Date(1987, 1, 11), new Date(1989, 6, 10));
//=> -1

对日期数组进行排序：

js
const result = [
    new Date(1995, 6, 2),
    new Date(1987, 1, 11),
    new Date(1989, 6, 10)
].sort(compareAsc);
//=> [
//   Wed Feb 11 1987 00:00:00,
//   Mon Jul 10 1989 00:00:00,
//   Sun Jul 02 1995 00:00:00
// ]

compareDesc ​

比较两个日期，如果第一个日期在第二个日期之后，则返回 -1；如果第一个日期在第二个日期之前，则返回 1；如果日期相等，则返回 0。

导入

js
import { compareDesc } from 'date-fns';

定义

ts
function compareDesc(
    dateLeft: string | number | Date,
    dateRight: string | number | Date
): number;

参数

名称类型描述
dateLeftstring | number | Date要比较的第一个日期。
dateRightstring | number | Date要比较的第二个日期。

返回

类型定义
number比较结果

示例

按时间顺序反向比较 1987年2月11日 和 1989年7月10日：

js
const result = compareDesc(new Date(1987, 1, 11), new Date(1989, 6, 10));
//=> 1

按时间倒序对日期数组进行排序：

js
const result = [
    new Date(1995, 6, 2),
    new Date(1987, 1, 11),
    new Date(1989, 6, 10)
].sort(compareDesc);
//=> [
//   Sun Jul 02 1995 00:00:00,
//   Mon Jul 10 1989 00:00:00,
//   Wed Feb 11 1987 00:00:00
// ]

format ​

返回指定格式的格式化日期字符串，结果可能因地区而异。

两个单引号 (‘) 之间的字符会被转义。连续两个单引号 (无论是在引号序列内还是在引号序列外) 都表示 “真正的” 单引号。(参见最后一个例子)。

字符串格式基于 Unicode 技术标准，可接受的模式：

单位模式结果示例注意
EraG..GGGAD, BC
GGGGAnno Domini, Before Christ2
GGGGGA, B
Calendar yeary44, 1, 1900, 20175
yo44th, 1st, 0th, 17th5,7
yy44, 01, 00, 175
yyy044, 001, 1900, 20175
yyyy0044, 0001, 1900, 20175
yyyyy...3,5
Local week-numbering yearY44, 1, 1900, 20175
Yo44th, 1st, 1900th, 2017th5,7
YY44, 01, 00, 175,8
YYY044, 001, 1900, 20175
YYYY0044, 0001, 1900, 20175,8
YYYYY...3,5
ISO week-numbering yearR-43, 0, 1, 1900, 20175,7
RR-43, 00, 01, 1900, 20175,7
RRR-043, 000, 001, 1900, 20175,7
RRRR-0043, 0000, 0001, 1900, 20175,7
RRRRR...3,5,7
Extended yearu-43, 0, 1, 1900, 20175
uu-43, 01, 1900, 20175
uuu-043, 001, 1900, 20175
uuuu-0043, 0001, 1900, 20175
uuuuu...3,5
Quarter (formatting)Q1, 2, 3, 4
Qo1st, 2nd, 3rd, 4th7
QQ01, 02, 03, 04
QQQQ1, Q2, Q3, Q4
QQQQ1st quarter, 2nd quarter, ...2
QQQQQ1, 2, 3, 44
Quarter (stand-alone)q1, 2, 3, 4
qo1st, 2nd, 3rd, 4th7
qq01, 02, 03, 04
qqqQ1, Q2, Q3, Q4
qqqq1st quarter, 2nd quarter, ...2
qqqqq1, 2, 3, 44
Month (formatting)M1, 2, ..., 12
Mo1st, 2nd, ..., 12th7
MM01, 02, ..., 12
MMMJan, Feb, ..., Dec
MMMMJanuary, February, ..., December2
MMMMMJ, F, ..., D
Month (stand-alone)L1, 2, ..., 12
Lo1st, 2nd, ..., 12th7
LL01, 02, ..., 12
LLLJan, Feb, ..., Dec
LLLLJanuary, February, ..., December2
LLLLLJ, F, ..., D
Local week of yearw1, 2, ..., 53
wo1st, 2nd, ..., 53th7
ww01, 02, ..., 53
ISO week of yearI1, 2, ..., 537
Io1st, 2nd, ..., 53th7
II01, 02, ..., 537
Day of monthd1, 2, ..., 31
do1st, 2nd, ..., 31st7
dd01, 02, ..., 31
Day of yearD1, 2, ..., 365, 3669
Do1st, 2nd, ..., 365th, 366th7
DD01, 02, ..., 365, 3669
DDD001, 002, ..., 365, 366
DDDD...3
Day of week (formatting)E..EEEMon, Tue, Wed, ..., Sun
EEEEMonday, Tuesday, ..., Sunday2
EEEEEM, T, W, T, F, S, S
EEEEEEMo, Tu, We, Th, Fr, Sa, Su
ISO day of week (formatting)i1, 2, 3, ..., 77
io1st, 2nd, ..., 7th7
ii01, 02, ..., 077
iiiMon, Tue, Wed, ..., Sun7
iiiiMonday, Tuesday, ..., Sunday2,7
iiiiiM, T, W, T, F, S, S7
iiiiiiMo, Tu, We, Th, Fr, Sa, Su7
Local day of week (formatting)e2, 3, 4, ..., 1
eo2nd, 3rd, ..., 1st7
ee02, 03, ..., 01
eeeMon, Tue, Wed, ..., Sun
eeeeMonday, Tuesday, ..., Sunday2
eeeeeM, T, W, T, F, S, S
eeeeeeMo, Tu, We, Th, Fr, Sa, Su
Local day of week (stand-alone)c2, 3, 4, ..., 1
co2nd, 3rd, ..., 1st7
cc02, 03, ..., 01
cccMon, Tue, Wed, ..., Sun
ccccMonday, Tuesday, ..., Sunday2
cccccM, T, W, T, F, S, S
ccccccMo, Tu, We, Th, Fr, Sa, Su
AM, PMa..aaAM, PM
aaaam, pm
aaaaa.m., p.m.2
aaaaaa, p
AM, PM, noon, midnightb..bbAM, PM, noon, midnight
bbbam, pm, noon, midnight
bbbba.m., p.m., noon, midnight2
bbbbba, p, n, mi
Flexible day periodB..BBBat night, in the morning, ...
BBBBat night, in the morning, ...2
BBBBBat night, in the morning, ...
Hour [1-12]h1, 2, ..., 11, 12
ho1st, 2nd, ..., 11th, 12th7
hh01, 02, ..., 11, 12
Hour [0-23]H0, 1, 2, ..., 23
Ho0th, 1st, 2nd, ..., 23rd7
HH00, 01, 02, ..., 23
Hour [0-11]K1, 2, ..., 11, 0
Ko1st, 2nd, ..., 11th, 0th7
KK01, 02, ..., 11, 00
Hour [1-24]k24, 1, 2, ..., 23
ko24th, 1st, 2nd, ..., 23rd7
kk24, 01, 02, ..., 23
Minutem0, 1, ..., 59
mo0th, 1st, ..., 59th7
mm00, 01, ..., 59
Seconds0, 1, ..., 59
so0th, 1st, ..., 59th7
ss00, 01, ..., 59
Fraction of secondS0, 1, ..., 9
SS00, 01, ..., 99
SSS000, 001, ..., 999
SSSS...3
Timezone (ISO-8601 w/ Z)X-08, +0530, Z
XX-0800, +0530, Z
XXX-08:00, +05:30, Z
XXXX-0800, +0530, Z, +1234562
XXXXX-08:00, +05:30, Z, +12:34:56
Timezone (ISO-8601 w/o Z)x-08, +0530, +00
xx-0800, +0530, +0000
xxx-08:00, +05:30, +00:002
xxxx-0800, +0530, +0000, +123456
xxxxx-08:00, +05:30, +00:00, +12:34:56
Timezone (GMT)O...OOOGMT-8, GMT+5:30, GMT+0
OOOOGMT-08:00, GMT+05:30, GMT+00:002
Timezone (specific non-locat.)z...zzzGMT-8, GMT+5:30, GMT+06
zzzzGMT-08:00, GMT+05:30, GMT+00:002,6
Seconds timestampt5129695207
tt...3,7
Milliseconds timestampT5129695209007
TT...3,7
Long localized dateP04/29/14537
PPApr 29, 14537
PPPApril 29th, 14537
PPPPFriday, April 29th, 14532,7
Long localized timep12:00 AM7
pp12:00:00 AM7
ppp12:00:00 AM GMT+27
pppp12:00:00 AM GMT+02:002,7
Combination of date and timePp04/29/1453, 12:00 AM7
PPppApr 29, 1453, 12:00:00 AM7
PPPpppApril 29th, 1453 at ...7
PPPPppppFriday, April 29th, 1453 at ...2,7

注意 (1)

在默认的 en-US 语言环境中，“格式化” 单元 (例如格式化季度) 与 “独立” 单元相同，但在某些语言中有所不同。

“格式化” 单元根据语言规则在日期上下文中进行变格。

“独立” 单元始终为主格单数：

js
format(new Date(2017, 10, 6), 'do LLLL', { locale: cs }); //=> '6. listopad'
js
format(new Date(2017, 10, 6), 'do MMMM', { locale: cs }); //=> '6. listopadu'

注意 (2)

任何相同字母的序列都是一个模式，除非用单引号字符进行转义 (见下文)。

如果序列比表中列出的序列长 (例如 EEEEEEEEEEE)，则输出将与此单元的默认模式相同，通常是最长的模式 (对于 ISO 工作日，为 EEEE)。

单元的默认模式在表格的最后一列中标记为 “2”。

js
format(new Date(2017, 10, 6), 'MMM'); //=> 'Nov'
js
format(new Date(2017, 10, 6), 'MMMM'); //=> 'November'
js
format(new Date(2017, 10, 6), 'MMMMM'); //=> 'N'
js
format(new Date(2017, 10, 6), 'MMMMMM'); //=> 'November'
js
format(new Date(2017, 10, 6), 'MMMMMMM'); //=> 'November'

注意 (3)

有些模式的长度可能是无限的 (例如 yyyyyyyy)。输出将用零填充以匹配模式的长度。

js
format(new Date(2017, 10, 6), 'yyyyyyyy'); //=> '00002017'

注意 (4)

在某些地区，QQQQQ 和 qqqqq 可能不是严格意义上的数字。这些标记代表季度的最短形式。

注意 (5)

y 和 u 模式之间的主要区别是公元前年份：

Yearyu
AC 111
BC 110
BC 22-1

此外，yy 始终返回年份的最后两位数字，而 uu 将个位数年份填充为 2 个字符，并返回其他年份而不做任何更改：

Yearyyuu
10101
141414
37676376
1453531453

当地和 ISO 周数年份 (Y 和 R) 具有相同的差异，只是当地周数年份依赖于 options.weekStartsOn 和 options.firstWeekContainsDate (比较 getISOWeekYear 和 getWeekYear)。

注意 (6)

特定的非位置时区目前在 date-fns 中不可用，因此现在这些令牌会回退到 GMT 时区。

注意 (7)

这些模式不在 Unicode 技术标准中。

  • i ISO 星期几
  • I ISO 一年中的第几周
  • R ISO 周数年份
  • t 秒时间戳
  • T 毫秒时间戳
  • o 序数修饰符
  • P 长本地化日期
  • p 长本地化时间

注意 (8)

YY 和 YYYY 标记表示按周编号的年份，但它们经常与年份混淆。

您应该启用 options.useAdditionalWeekYearTokens 来使用它们。

注意 (9)

D 和 DD 标记表示一年中的天数，但它们经常与月份中的天数混淆。

您应该启用 options.useAdditionalDayOfYearTokens 来使用它们。

导入

js
import { format } from 'date-fns';

定义

ts
function format(
    date: string | number | Date,
    formatStr: string,
    options?: FormatOptions
): string;

参数

名称类型描述
datestring | number | Date原始日期。
formatStrstring格式化模式。
options?FormatOptions带有选项的对象。

返回

类型定义
string格式化的日期字符串

异常

描述
date 不能是无效日期
options.locale 必须包含 localize 属性
options.locale 必须包含 formatLong 属性
使用 yyyy 而不是 YYYY 来格式化年份，使用 [提供的格式] 输入 [提供的输入]；
使用 yy 而不是 YY 来格式化年份，使用 [提供的格式] 输入 [提供的输入]；
使用 d 而不是 D 来使用 [提供的格式] 对输入 [提供的输入] 格式化月份的日期；
使用 dd 而不是 DD 来使用 [提供的格式] 来格式化月份的日期 [提供的输入]；
格式字符串包含未转义的拉丁字母字符

示例

以中端格式表示 2014年2月11日：

js
const result = format(new Date(2014, 1, 11), 'MM/dd/yyyy');
//=> '02/11/2014'

用世界语表示 2014年7月2日：

js
import { eoLocale } from 'date-fns/locale/eo';
const result = format(new Date(2014, 6, 2), "do 'de' MMMM yyyy", {
    locale: eoLocale
});
//=> '2-a de julio 2014'

通过单引号字符转义字符串：

js
const result = format(new Date(2014, 6, 2, 15), "h 'o''clock'");
//=> "3 o'clock"

何以解忧，唯有代码。不忘初心，方得始终。

Copyright © 2019-present 陈随易