📅 when-off

一个用于处理日期、日历、节假日和工作日的 TypeScript 工具库

📖 项目介绍

when-off 是一个专注于日期和时间处理的 TypeScript 工具库，提供全球多个国家的法定节假日和调休安排数据，主要功能包括：

• 🎉 节假日识别与处理
• 💼 工作日计算
• 📅 调休安排查询
• 📊 节假日统计信息
• 🌍 多地区数据支持

🚀 安装

使用 npm

npm install when-off

使用 yarn

yarn add when-off

使用 pnpm

pnpm add when-off

使用 bun

bun add when-off

📋 使用方法

基本用法

import WhenOff from 'when-off';

// 创建实例，默认为中国地区当前年份
const whenOff = new WhenOff();

// 指定地区和年份
const whenOff2025 = new WhenOff('CN', 2025);

数据访问

原始 JSON 文件可通过以下方式访问：

1. unpkg：

https://unpkg.com/when-off/json/CN/2025.json

2. jsDelivr CDN：

https://cdn.jsdelivr.net/npm/when-off/json/CN/2025.json

浏览器直接使用

<script src="https://unpkg.com/when-off"></script>
<!-- <script src="https://cdn.jsdelivr.net/npm/when-off" ></script> -->
<script>
  const whenOff = new WhenOff();
  console.log(whenOff.isHoliday(new Date('2024-01-01')));
</script>

📚 API 参考

构造函数

constructor(region?: RegionEnum, year?: number)

参数：

• region (可选): 地区代码，默认为 'CN'，目前仅支持中国
• year (可选): 年份，默认为当前年份

示例：

const whenOff = new WhenOff(); // 默认中国，当前年份
const whenOff2024 = new WhenOff('CN', 2024); // 中国，2024年

方法

isHoliday(date: Date, region?: string): boolean

判断指定日期是否为法定节假日。

参数：

• date: 要检查的日期
• region (可选): 地区代码，默认使用实例创建时的地区

返回值：

• boolean: 如果是法定节假日返回 true，否则返回 false

示例：

const whenOff = new WhenOff();

// 检查2024年1月1日是否为节假日
console.log(whenOff.isHoliday(new Date('2024-01-01'))); // true

// 检查2024年1月2日是否为节假日
console.log(whenOff.isHoliday(new Date('2024-01-02'))); // false

isWorkingDay(date: Date): boolean

判断指定日期是否为工作日。

参数：

• date: 要检查的日期

返回值：

• boolean: 如果是工作日返回 true，否则返回 false

示例：

const whenOff = new WhenOff();

// 检查2024年1月2日是否为工作日
console.log(whenOff.isWorkingDay(new Date('2024-01-02'))); // true

// 检查2024年1月1日是否为工作日（元旦）
console.log(whenOff.isWorkingDay(new Date('2024-01-01'))); // false

isAlternateWorkDay(date: Date, region?: string): boolean

判断指定日期是否为调休工作日。

参数：

• date: 要检查的日期
• region (可选): 地区代码，默认使用实例创建时的地区

返回值：

• boolean: 如果是调休工作日返回 true，否则返回 false

示例：

const whenOff = new WhenOff();

// 检查某个周末是否为调休工作日
console.log(whenOff.isAlternateWorkDay(new Date('2024-02-04'))); // true (春节调休)

getDateInfo(date: Date, region?: string): HolidayInfo | undefined

获取指定日期的节假日相关信息。

参数：

• date: 要查询的日期
• region (可选): 地区代码，默认使用实例创建时的地区

返回值：

• HolidayInfo | undefined: 节假日信息对象，如果该日期没有特殊信息则返回 undefined

示例：

const whenOff = new WhenOff();

const info = whenOff.getDateInfo(new Date('2024-01-01'));
console.log(info);
// 输出: { date: '2024-01-01', type: 'public_holiday', name: '元旦' }

getHolidayStats(region?: string): HolidayStats | undefined

获取指定年份的节假日统计信息。

参数：

• region (可选): 地区代码，默认使用实例创建时的地区

返回值：

• HolidayStats | undefined: 统计信息对象，包含节假日和调休工作日的总数

示例：

const whenOff = new WhenOff();

const stats = whenOff.getHolidayStats();
console.log(stats);
// 输出: { totalHolidays: 11, totalAlternateWorkdays: 8 }

🗓️ 支持的数据范围

地区支持

• 🇨🇳 中国 (CN): 2015-2025年完整数据

年份支持

• 2015-2025年: 完整的法定节假日和调休数据

💡 使用示例

1. 基础日期判断

import WhenOff from 'when-off';

const whenOff = new WhenOff();

// 判断今天是否为节假日
const today = new Date();
if (whenOff.isHoliday(today)) {
  console.log('🎉 今天是节假日，好好休息！');
} else if (whenOff.isWorkingDay(today)) {
  console.log('💼 今天是工作日，加油工作！');
}

2. 批量日期处理

import WhenOff from 'when-off';

const whenOff = new WhenOff();

// 检查一周内的日期
const dates = [
  new Date('2024-01-01'),
  new Date('2024-01-02'),
  new Date('2024-01-03'),
];

dates.forEach(date => {
  const dateStr = date.toISOString().split('T')[0];
  if (whenOff.isHoliday(date)) {
    console.log(`📅 ${dateStr} 是节假日`);
  } else if (whenOff.isAlternateWorkDay(date)) {
    console.log(`🔄 ${dateStr} 是调休工作日`);
  } else if (whenOff.isWorkingDay(date)) {
    console.log(`💼 ${dateStr} 是工作日`);
  } else {
    console.log(`🌟 ${dateStr} 是周末`);
  }
});

3. 统计信息查询

import WhenOff from 'when-off';

const whenOff = new WhenOff('CN', 2024);

// 获取2024年节假日统计
const stats = whenOff.getHolidayStats();
console.log(`📊 2024年统计：`);
console.log(`🎉 法定节假日: ${stats.totalHolidays} 天`);
console.log(`🔄 调休工作日: ${stats.totalAlternateWorkdays} 天`);

📦 环境要求

• Node.js >= 20.15.0
• pnpm >= 8.0.0 (推荐使用 pnpm 作为包管理器)

🚀 快速开始

1. 克隆项目

git clone https://github.com/BallerJay/when-off.git
cd when-off

2. 安装依赖

# 使用 pnpm (推荐)
pnpm install

# 或使用 npm
npm install

# 或使用 yarn
yarn install

代码提交

项目使用 Conventional Commits 规范和 Commitizen 工具来标准化提交信息。

# 使用交互式提交工具
pnpm commit

📄 许可证

本项目基于 MIT 许可证 开源。

🤝 贡献指南

欢迎贡献代码！请遵循以下步骤：

1. Fork 本仓库
2. 创建特性分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (pnpm commit)
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 创建 Pull Request

🐛 问题反馈

如果你发现任何问题或有改进建议，请在 Issues 页面提交。

---

⭐ 如果这个项目对你有帮助，请给它一个 Star！