when-off
Version:
一个用于处理日期、日历、节假日和工作日的 TypeScript 工具库, 并且提供各个国家法定节假日和调休安排信息数据
326 lines (226 loc) • 7.48 kB
Markdown
# 📅 when-off
> 一个用于处理日期、日历、节假日和工作日的 TypeScript 工具库
[](LICENSE) [](https://www.typescriptlang.org/) [](https://nodejs.org/)
## 📖 项目介绍
`when-off` 是一个专注于日期和时间处理的 TypeScript 工具库，提供全球多个国家的法定节假日和调休安排数据，主要功能包括：
- 🎉 节假日识别与处理
- 💼 工作日计算
- 📅 调休安排查询
- 📊 节假日统计信息
- 🌍 多地区数据支持
## 🚀 安装
### 使用 npm
```bash
npm install when-off
```
### 使用 yarn
```bash
yarn add when-off
```
### 使用 pnpm
```bash
pnpm add when-off
```
### 使用 bun
```bash
bun add when-off
```
## 📋 使用方法
### 基本用法
```typescript
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
```
### 浏览器直接使用
```html
<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 参考
### 构造函数
```typescript
constructor(region?: RegionEnum, year?: number)
```
**参数：**
- `region` (可选): 地区代码，默认为 `'CN'`，目前仅支持中国
- `year` (可选): 年份，默认为当前年份
**示例：**
```typescript
const whenOff = new WhenOff(); // 默认中国，当前年份
const whenOff2024 = new WhenOff('CN', 2024); // 中国，2024年
```
### 方法
#### `isHoliday(date: Date, region?: string): boolean`
判断指定日期是否为法定节假日。
**参数：**
- `date`: 要检查的日期
- `region` (可选): 地区代码，默认使用实例创建时的地区
**返回值：**
- `boolean`: 如果是法定节假日返回 `true`，否则返回 `false`
**示例：**
```typescript
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`
**示例：**
```typescript
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`
**示例：**
```typescript
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`
**示例：**
```typescript
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`: 统计信息对象，包含节假日和调休工作日的总数
**示例：**
```typescript
const whenOff = new WhenOff();
const stats = whenOff.getHolidayStats();
console.log(stats);
// 输出: { totalHolidays: 11, totalAlternateWorkdays: 8 }
```
## 🗓️ 支持的数据范围
### 地区支持
- 🇨🇳 **中国 (CN)**: 2015-2025年完整数据
### 年份支持
- **2015-2025年**: 完整的法定节假日和调休数据
## 💡 使用示例
### 1. 基础日期判断
```typescript
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. 批量日期处理
```typescript
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. 统计信息查询
```typescript
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. 克隆项目
```bash
git clone https://github.com/BallerJay/when-off.git
cd when-off
```
### 2. 安装依赖
```bash
# 使用 pnpm (推荐)
pnpm install
# 或使用 npm
npm install
# 或使用 yarn
yarn install
```
### 代码提交
项目使用 [Conventional Commits](https://www.conventionalcommits.org/) 规范和 Commitizen 工具来标准化提交信息。
```bash
# 使用交互式提交工具
pnpm commit
```
## 📄 许可证
本项目基于 [MIT 许可证](LICENSE) 开源。
## 🤝 贡献指南
欢迎贡献代码！请遵循以下步骤：
1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`pnpm commit`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 创建 Pull Request
## 🐛 问题反馈
如果你发现任何问题或有改进建议，请在 [Issues](https://github.com/BallerJay/when-off/issues) 页面提交。
---
⭐ 如果这个项目对你有帮助，请给它一个 Star！