# @date/holidays 中文文档

规范地址：https://npmcn.com/package/%40date/holidays/

版本：0\.4\.2
npm 元数据更新时间：2022-06-12T16:57:16.758Z
中文译文更新时间：2026-11-11T15:28:10.872Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40date/holidays
原文对照：https://npmcn.com/package/%40date/holidays/?lang=original
项目主页：https://github.com/elidoran/node-date-holidays#readme
源码仓库：https://github.com/elidoran/node-date-holidays

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：38 kB，5 个文件
- 模块格式：CommonJS
- TypeScript 类型：未声明
- Node.js 要求：\>=8
- 运行依赖：0 个
- 首次发布：2016-06-30T04:21:30.214Z
- 最新版本发布：2019-07-29T01:06:37.904Z
- 近 30 天下载量：12411（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：8（近 12 个月 0 个）

## 中文简介

存储和比较假日日期

## 安装

```sh
npm install @date/holidays
```

也可以使用：`pnpm add @date/holidays`、`yarn add @date/holidays`、`bun add @date/holidays`

## README

# @ 日期/ 工作日

[![Build Status](https://travis-ci.org/elidoran/node-date-holidays.svg?branch=master)](https://travis-ci.org/elidoran/node-date-holidays) [![npm version](https://badge.fury.io/js/%40date%2Fholidays.svg)](http://badge.fury.io/js/%40date%2Fholidays) [![Coverage Status](https://coveralls.io/repos/github/elidoran/node-date-holidays/badge.svg?branch=master)](https://coveralls.io/github/elidoran/node-date-holidays?branch=master)

测试日期是否为节假日,并管理与节假日有关的信息.

注:0.4.0版由于完全重写而更改了API. 通过安装0.3的最新补丁版本来使用旧API.

## 安装

```sh
npm install --save @date/holidays
```

## 用法: 添加简单假日

有些假期总是在同一天,因此很容易确定.

```javascript
const Holidays = require('@date/holidays')
const holidays = Holidays()
// all in one: const holidays = require('@date/holidays')()

// at this point `holidays` is empty so all calls to isHoliday() return false.

// simplest method for fixed dates only requires the month and day.
const removerFn = holidays.add({
  // optional holiday info.
  // defaults to {}.
  // may be a function returning an object.
  mainInfo: {
    name: 'Valentine\'s Day',
    public: true,
  },
  // provide both the month and day
  month: 1,  // NOTE: I prefer using months as 1-12, but, Date uses 0-11
  day  : 14,
})

// You can remove the holiday from the holidays instance by calling its remover.
// it will remove the function and its cache (if it's a caching holiday).
removerFn()
```

### 用法: 添加复杂的假日

有些假日需要计算何时发生,以及是否还有“观察”日期.

指定假日的日期范围 `is()` 函数以测试是否 `Date` 是个节日.

```javascript
// this holiday is available as: @date/IndependenceDay
// Independence Day is always on July 4th
// It has an "observed" holiday on the nearest weekday if it's on the weekend
holidays.add({
  // first way to specify the holiday's date range.
  month: 6, // July is 6 because Date because 0-11
  firstDay: 3,
  lastDay: 5,

  // // second way allows specifying multiple date ranges (as for New Year's Day)
  // dateRange: [ // each element is an array with a range or individual date.
  //   // this means July 3rd through July 5th.
  //   [ 6, 3, 5 ]
  //
  //   // an individual day would be:
  //   // [ 11, 31 ] // for December 31st (not relevant for Independence Day)
  // ],

  // optional holiday info.
  // defaults to {}.
  // may be a function returning an object.
  mainInfo: {
    name: 'Independence Day',
    public: true, // it's a public holiday in USA
    bank: true, // it's a bank holiday in USA when it's on a weekday.
  },

  // optional info for the observed days.
  // defaults to `mainInfo`.
  // may be a function returning an object.
  observedInfo: {
    name: 'Independence Day (observed)',
    public: true,
    bank: true, // the observed date is always a bank holiday.
  },

  // optional info when main date is on a weekend.
  // defaults to `mainInfo`.
  // may be a function returning an object.
  mainInfoWhenObserved: {

    name: 'Independence Day',
    public: true,
    bank: false, // when it's on the weekend it's not a bank holiday (the observed is)
  },

  // `date` is the `Date` instance.
  // the other args are taken from the Date instance and used multiple times
  // so they are provided as a convenience so you don't have to call those
  // getters again.
  // `year` is the "full year" 4-digits.
  is: function isIndependenceDay(date, day, month, year) {

    // get the weekday so we can see if it's the main, observed, or neither.
    const weekday = date.getDay()

    // return:
    //  0 - not a match
    //  1 - is the main holiday on a business day
    //  2 - is the observed holiday on a business day
    //  3 - is the main holiday on a weekend day
    switch(day) {
      // 3 for July 3rd which is the observed holiday when it's a Friday
      case 3: return (weekday === 5) ? 2 : 0  // Friday July 3rd is "observed"

      // 4 for July 4th, always a holiday, but is either main, or "main when observed"
      case 4: return (1 <= weekday && weekday <= 5) ? 1 : 3

      // 5 for July 5th which is the observed holiday when it's a Monday
      case 5: return (weekday === 1) ? 2 : 0  // Monday July 5th is "observed"

      // otherwise, not a match for the holiday.
      default: return 0
    }
  },
})

// New Year's spans multiple months and multiple years because
// it can be observed on the day before which is December 31st.
// we support this with the `dateRange` property.
holidays.add({
  // all three "info" objects are optional.
  dateRange: [
    [ 12, 31 ],  // specific day: December 31st
    [ 0, 1, 2 ], // range of days: January 1st to 2nd
  ],
  is: (date, day, month, year) => {
    // Holidays ensures the date we receive is within the range we specified.
    // so, we need to look at the day of week to determine our result.
    const weekday = date.getDay()

    switch(day) {
      case 31: // only the observed holiday if it's a Friday
        return (weekday === 5) ? 2 : 0

      case 1: // always main holiday date, might be on weekend/weekday
        return (1 <= weekday && weekday <= 5) ? 1 : 3

      case 2: // only the observed holiday if it's a Monday
        return (weekday === 1) ? 2 : 0

      default: // otherwise, not a match
        return 0
    }
  },
})

// a date may not have a set number which requires more processing.
holidays.add({
  mainInfo: {
    name: 'Father\'s Day',
  },

  // it's the third Sunday in June.
  // so, month is 5 because Date uses 0-11,
  // and, the days it could be on are June 15th to 21st.
  dateRange: [
    [ 5, 15, 21 ]
  ],

  is: function isFathersDay(date, day, month, year) {
    // Holidays ensures it's within the date range we specified.
    // so, is it a Sunday?
    return (date.getDay() === 0) ? 1 : 0
  },
})
```

### 用法:帮助者

与日期合作时 [@ 日期/ 生成器](https://github.com/elidoran/node-date-generator) 财务报告和审定财务报表 [@ 日期/ 业务](https://github.com/elidoran/node-date-business) 帮助.

我所出版的个别节日都会有一个 `gen(year)` 函数返回 a `Date` 例如,在指定年份的假期。 也可能有一个 `observed` 属性设置在其中 `Date` 当年的节日是"观察"的 这是上一个版本使用的 `@date/holidays`编辑 `@date/generator` 软件包对此很有帮助.

这个 `@date/business` 软件包有助于将日期改为下一个或上一个工作日。 它接受一个 `Holidays` 这样它就可以跳过假日了.

## API 密码

### API: 是Holiday( )

假返回,除非它知道指定日期的假日.

额外标准可以指定 假日 `info` 将测试这些值。 所有指定值必须在 `info` 以它返回真实.

```javascript
const date = getSomeDate() // a `Date` object

// test the date without filters, returns true/false
holidays.isHoliday(date)

// test the date with a single filter, returns true/false
holidays.isHoliday(date, { some: 'thing' })

// now with two filters:
holidays.isHoliday(date, { some: 'thing', something: 'else' })
```

### API: 获取Holiday ()

在指定日期获得所有节假日的"info"阵列.

如果日期没有节日,则返回一个空阵列.

“ info”是调用时提供的可选对象 `holidays.add()`。 。 。 .

见 [API: 添加( )](https://npmcn.com/package/%40date/holidays/#readme-api-addobject)

```javascript
infos = holidays.getHoliday(date)

if (infos.length > 0) {
  // then there was at least one holiday on that date.
}

// you can filter the results by supplying properties to check for in the "info".
infos = holidays.getHoliday(date, {
  some: 'prop',
  to: 'filter',
})
```

### API: 负载( )和负载Many( )

将已公布的假日套件装入一个 `Holidays` 举个例子.

可以通过提供对象作为第二个参数来推翻假日的默认选项 。 它可能包含用于: [添加( )](https://npmcn.com/package/%40date/holidays/#readme-api_addobject)。默认选项和指定的选项将被合并.

为了方便, `loadMany()` 接受数组。 每个子阵列都应有包名作为第一个元素,一个可选选项将对象上覆作为第二个元素.

寻找出版的节日 [@ 日期](https://www.npmjs.com/org/date) 组织.

```javascript
// one-line require and build:
const holidays = require('@date/holidays')()

// load a single holiday package without overriding any options.
holidays.load('the-package-name')

// load a single holiday with some option overrides:
holidays.load('some-package-name', {
  // specify any properties used in holidays.add()
})

// to do the above for many packages at once:
holidays.loadMany([ // NOTE: argument is an array of sub-arrays.
  // sub-arrays may have only the package name:
  [ 'package-name' ],

  // or, they may also have an options override object:
  [ 'some-name', { name: 'Changed Holiday Name', cache: true } ]
])
```

### API: 添加( 对象)

将假日添加到 `holidays` 举个例子.

添加接受包含假日选项的单个对象参数。 可能的选择是:

| 属性 | 目的 |
| --: | :-- |
| 主信息 | 从 `getHoliday()` 用于过滤结果。 可能是一个函数, 然后每次调用 `getHoliday()` 财务报告和审定财务报表 `isHoliday()` 节日是当天的比赛 这允许每次返回一个新对象 。 当其他2"info"属性没有指定时,这也是默认的"info". 默认为空对象。 如果“主要信息”被同时指定,那么这个将只用于一年,当有 **没有** “观察日期”. |
| 已观测到信息 | 与 `mainInfo` 但当日期是节日的"观察日期"时,才归还. 默认为 `mainInfo` 如果未指明的话. |
| 主信息当使用时 | 与 `mainInfo` 除了,当日期是节假日"主要日期"时返回,但在周末,因此节假日在另一个日期被"观察". 默认为 `mainInfo` 如果未指明的话. |
| 月份 | 节月. 0- 11 用作 JavaScript `Date` 已经. |
| 日数 | 节之正月. 用途1-31。 用于"固定日期"假期,该假期总是在同一天. |
| 第一天 | 假期可能在一系列日期的第一天。 使用过的 `lastDay`. 对于不同日期的假日和可能“观察”日期的假日(通常是在“主要日期”之前或之后). |
| 最后一个日期 | 在一系列日期的最后一天,假期可能要到来。 使用过的 `firstDay`。 。 。 . |
| 日期范围 | 为涵盖一个月或一年以上的假日提供多个日期范围。 例如,可于12月31日庆祝新年,即上个月和上个年头。 每个子阵列的子阵列包含2个元素:月与日,或3个元素:月与日,首日与上日. |
| 实值 | 规定具体日期的试验功能是: 1. 不含"观察日期"的"主要日期"为当年; 2. 含有"观察日期"的"主要日期"为当年. 它的论点是: `is(date, day, month, year)`后面的词组是为了方便 `Holidays` 已经将函数调用到 `date` 以为自己获得这些价值. |
| 缓存 | 默认为 `false`当设置为 `true` 联合国 `is()` 将按年/月/天在对象中缓存。 打电话 `holidays.purge()` 以新的空对象替换所有假日缓存对象. |

阅读后面关于特定选项的章节. 下面,让我们一起看看他们:

```javascript
// the simplest holiday on a fixed date of March 3rd without info.
// the `mainInfo` will default to an empty object.
// an `is()` function will be created for it.
holidays.add({
  month: 2,
  day: 3,
})

// now returns true for any year:
holidays.isHoliday(new Date(2000, 2, 3))

// result is always an array containing holiday infos for the Date.
// in this instance, it has one element which is the default empty object.
result = holidays.getHoliday(new Date(2000, 2, 3))

if (result.length > 0) {
  // then there was at least one holiday info returned...
}

// add some info to the date to use elsewhere, or,
// use the info to filter results.
holidays.add({
  mainInfo: {
    name: 'Some Holiday',
    some: 'property',
  },
  month: 2,
  day: 3,
})

// to filter, specify the properties you want the holiday to have.
// this will return `true` because the property exists in `mainInfo`.
holidays.isHoliday(new Date(2000, 2, 3), { some: 'property' })

// can specify more than one property and both must exist and match.
holidays.isHoliday(new Date(2000, 2, 3), {
  name: 'Some Holiday',
  some: 'property',
})

// these both will return false.
holidays.isHoliday(new Date(2000, 2, 3), { some: 'thing else' })
holidays.isHoliday(new Date(2000, 2, 3), { another: 'property' })


// for holidays which can be on different dates or have observed dates
// then an `is()` function is necessary.
holidays.add({
  // these holidays can have different "info" for:
  //  1. the main date
  //  2. the observed date
  //  3. the main date when it's on a weekend, meaning there's an observed date.
  // for example, setting a property like { bank: true } for a bank holiday.
  // it'll only be true on the main date if it's a weekday.
  // it'll always be true for the observed date.
  // they can all be used for filtering as described above.
  // the three properties for them are:
  mainInfo: {},
  observedInfo: {},
  mainInfoWhenObserved: {},

  // method #1 of specifying a date range:
  // this is an array of arrays.
  // each sub-array must have either 2 or 3 elements.
  // 2 elements means it's specific date with the month then day.
  // 3 elements means it's a range of days with the month, first day, and last day.
  dateRange: [
    // many holidays are one a set date and may have an observed date
    // a day before or a day after it. So, a range of 3 days.
    // can be in month 1 between the 2nd and 4th:
    [ 1, 2, 4 ],
  ],

  // method #2 of specifying a date range:
  // for date ranges with only a single range it can instead be specified like this:
  month: 1,
  firstDay: 2,
  lastDay: 4,

  // this is called to check a Date.
  is: (date, day, month, year) {
    // must return:
    //  0 - not a match
    //  1 - is the main holiday on a business day
    //  2 - is the observed holiday on a business day
    //  3 - is the main holiday on a weekend day

    // get the weekday so we can see if it's the main, observed, or neither.
    const weekday = date.getDay()

    // check each day in the date range you specified.
    // based on the weekday you can determine whether it's main/observed/main-when-observed.
    switch(day) {
      // 2 for February 2nd which is the observed holiday when it's a Friday
      case 2: return (weekday === 5) ? 2 : 0

      // 3 for February 3rd, always a holiday, but is either main, or "main when observed"
      case 3: return (1 <= weekday && weekday <= 5) ? 1 : 3

      // 4 for February 4th which is the observed holiday when it's a Monday
      case 4: return (weekday === 1) ? 2 : 0

      // otherwise, not a match for the holiday.
      default: return 0
    }
  },
})

// any of the three "info" properties may specify a function instead of an Object.
// they must return an Object.
// this allows fresh objects to be returned each time it's needed.
holidays.add({
  mainInfo: () => { return { some: 'new object' } },
  month: 4,
  day: 5,
})

// by default, no caching is done. The `is()` function will be called each time.
// some holiday dates are complicated to calculate (example: Easter).
// it may be helpful to cache the results to avoid calling `is()` repeatedly.
// to do that, simply specify the `cache` property set to `true`.
holidays.add({
  cache: true,
  // ... the usual stuff here.
})

// To clear the cache of all caching holidays in a Holidays instance,
// call `purge()`.
holidays.purge()
```

#### API: 添加( ) - 信息三重奏

这个 `info` 用于两个位置:

1.  作为返回值 `getHoliday()`
2.  用于比较额外属性 `isHoliday()` 财务报告和审定财务报表 `getHoliday()` 作为"过滤"(第二个参数).

所有“ info”对象都是可选的.

若为 `mainInfo` 不提供默认为空对象.

两者 `observedInfo` 财务报告和审定财务报表 `mainInfoWhenObserved` 默认值为 `mainInfo` (默认为空对象).

如果假期总是在同一天 那么只有 `mainInfo` 将使用(我指那些"简单固定的日期"节假日).

如果假期可能在另一个日期,通常是"主要日期"之前的一天或之后的一天被"观察",那么"观察日期"将返回该日期 `observedInfo` 对象.

当年有"观察日期"时 `Date` 提供给 `getHoliday()` 或者说 `isHoliday()` 然后,"主要日期"是周末 它会返回 `mainInfoWhenObserved` 对象.

例如"情人节"总是2月14日,从未有过被观察的日期. 所以,只有一个 `mainInfo` 帮助.

例如,"独立日"的"主要日期"总是7月4日. 可在7月3日或7月5日观测到. 当7月4日是工作日(星期一至星期五)时 `mainInfo` 将于该年7月4日使用。 如果7月4日是周末的话 `mainInfoWhenObserved` 将于该年7月4日使用。 当3号或5号放假一年时 `observedInfo` 将被使用(否则那些日子不视为假日).

这有什么用? 考虑上述独立日的例子。 说得有道理 `mainInfo` 包含 `bank: true` 因为它是一个银行假日。 但是,当3号或5号节日被纪念时,4号是 _没有_ 银行假日。 所以,这时候 `mainInfoWhenObserved` 因为它可以包含 `bank: false`编辑 `observedInfo` 将包含 `bank: true` 因为"观察日期"(在其发生的年份)总是银行假日.

#### API: 添加( ) - 指定日期的方法

假日有不同的日期配置. 这么说吧, `Holidays` 允许以不同方式指定它们.

1.  简单的固定日期

总是在同一天没有"观察日期". 比如情人节 指定这样一个 :

```js
holidays.add({
  // February 14th
  month: 1,
  day: 14,
})
```

2.  固定日期和可能观测到的日期

"主要日期"总是在同一天,它可能在"主要日期"之前或之后的某一天有一个"观察日期". 例如,独立日总是在7月4日,但可以在7月3日或7月4日进行纪念. 指定这样一个 :

```js
// method 1: properties
// Independence Day: remember, 6 is July for JS Dates 0-11
holidays.add({
  month: 6,
  firstDay: 3,
  lastDay: 5,
})


// method 2: date range
holidays.add({
  dateRange: [
    // [ month, firstDay, lastDay ]
    // Independence Day:   (remember, 6 is July for JS Dates 0-11)
    [ 6, 3, 5 ],
  ],
})

// New Year's may span 2 months and 2 years when it's
// observed the day before, which is December 31st.
// here's how that would be specified:
holidays.add({
  dateRange: [
    // the possible observed date of December 31st:
    [ 11, 31 ],
    // the range covering the "main date" and possible observed Date:
    // January 1st to January 2nd:
    [ 0, 1, 2 ],
  ],
})
```

3.  可变日期

每年的节假日必须计算. 父亲节就是一个例子,它总是在6月的第三个星期日。 另一个例子是复活节,它有一个复杂的计算算法.

```js
// Father's day spans a week of possible dates:
// method 1: properties
holidays.add({
  month: 5, // NOTE: 5 is June for JS Dates 0-11
  firstDay: 15, // earliest date it could be on.
  lastDay: 21,  // latest date it could be on.
})

// method 2: date range array
holidays.add({
  dateRange: [
    // 5 is June for JS Dates 0-11
    // 15 - earliest date it could be on.
    // 21 - latest date it could be on.
    [ 5, 15, 21 ],
  ],
})
```

#### API: 添加( ) - 是( )

这个 `is()` 函数返回指定日期在0至3之间的值。 数值是指:

| 价值 | 含义 |
| --: | :-- |
| 0 个 | 不匹配的节日. |
| 1个 | 是一年中节假日的"主要日期" **无** “观察日期”. |
| 2个 | 是当年节假日的"观察日". |
| 3个 | 是一年中节假日的"主要日期" **与** “观察日期”. |

这个 `is()` 函数对“简单固定日期”是可选的。 可具体说明日期(见上文第一节)和 `is()` 函数将为此创建.

这些论点是: `(date, day, month, year)`第一个论点是 `Date` 对象。 以后的争论是为了方便,所以你不用在 `Date` 以获取它们 `Holidays` 已经叫他们自己 所以它让他们 `is()`) (中文(简体) ).

例如:

```js
// a simple fixed date doesn't need an is().
// it'll be auto-created.
holidays.add({
  month: 1,
  day: 2,
})

// a "fixed date" holiday with a possible "observed date":
holidays.add({
  month: 6,
  firstDay: 3,
  lastDay: 5,
  is: (date, day, month, year) => {
    // this will only be called for dates within the date range specified.
    // so, at this point, we already know the month is `6`,
    // and the day is within the range 3 to 5.
    // so, use the `day` and the "day of the week" to determine return result:
    const weekday = date.getDay()

    switch(day) { // based on the day of the month for the date:
      // 3 for July 3rd which is the observed holiday when it's a Friday
      case 3: return (weekday === 5) ? 2 : 0  // Friday July 3rd is "observed"

      // 4 for July 4th, always a holiday, but is either main, or "main when observed"
      case 4: return (1 <= weekday && weekday <= 5) ? 1 : 3

      // 5 for July 5th which is the observed holiday when it's a Monday
      case 5: return (weekday === 1) ? 2 : 0  // Monday July 5th is "observed"

      // otherwise, not a match for the holiday.
      default: return 0
    }
  },
})

// a variable date holiday:
holidays.add({ // Father's day is third Sunday in June
  dateRange: [
    [ 5, 15, 21 ],
  ],
  is: (date, day, month, year) => {
    // this will only be called for dates within the date range specified.
    // so, at this point, we already know the month is `5`,
    // and the day is within the range 15 to 21.
    // so, all we care about is whether it's Sunday.
    const weekday = date.getDay()
    return (weekday === 0) ? 1 : 0
  },
})
```

### API: 删除假日

删除假日从 a `Holidays` 举个例子.

这个 `Holidays.add()` 函数返回一个“ remover 函数”,当调用时,该函数将删除所添加的假日.

```javascript
const someHolidaySpecification = getIt()

const removerFn = holidays.add(someHolidaySpecification)

removerFn()
```

### API: 清洗( )

何时 `cache:true` 在假日的选项中指定了它会缓存结果以避免调用它 `is()` 函数在同一个日期重复.

每个缓存假日都会创建自己的缓存对象.

通话 `purge()` 编辑 `Holidays` 实例将用新的空对象取代所有缓存对象.

```javascript
// creates all new empty caches.
holidays.purge()
```

## [MIT 许可证](https://npmcn.com/package/%40date/holidays/LICENSE)

## 常见问题

### @date/holidays 是什么？

存储和比较假日日期

### 如何安装 @date/holidays？

在项目目录运行 npm install @date/holidays，或使用 pnpm add / yarn add / bun add。

### @date/holidays 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/date\_\_holidays 是否存在。

### @date/holidays 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @date/holidays 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=8。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @date/holidays 可以商用吗？

@date/holidays 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @date/holidays 的下载量有多少？

根据 npm 官方下载统计，@date/holidays 在 2026/10/12 – 2026/11/10 这 30 天内被下载 12,411 次，日均约 414 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @date/holidays 还在维护吗？

最新版本 0\.4\.2 发布于 2019/07/29（7 年前）；至今共发布 8 个版本，其中过去 12 个月发布了 0 个；首次发布于 2016/06/30。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。