🇨🇳 Chinese Workday

高性能中国工作日判断库 · 今天要上班吗？

解决开发者痛点：准确判断中国工作日、节假日、调休日，支持 2011-2026年 完整数据。

🚀 快速开始

Node.js / npm

npm install chinese-workday

// CommonJS
const { isWorkday, isHoliday, getFestival } = require('chinese-workday')

// ES Module
import { isWorkday, isHoliday, getFestival } from 'chinese-workday'

console.log(isWorkday('2024-10-01')) // false (国庆节)
console.log(isHoliday('2024-10-01')) // true
console.log(getFestival('2024-10-01')) // "国庆节"

浏览器 / CDN

<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/chinese-workday.min.js"></script>
<script>
  const { isWorkday } = window.chineseWorkday
  console.log(isWorkday('2024-10-01')) // false
</script>

📁 项目结构

chinese-workday/
├── src/              # 源码
├── dist/             # 构建产物
│   ├── .cjs.js       # CommonJS
│   ├── .esm.js       # ES Module
│   └── .min.js       # 浏览器/CDN
├── __tests__/        # 测试
└── bench/            # 性能测试

⚡ 性能优势

| 特性 | chinese-workday | 竞品平均 | | -------------- | --------------- | -------- | | 缓存命中率 | 98.40% | ~70% | | 单次查询 | ~40% 更快 | 基准 | | 批量查询 | ~60% 更快 | 基准 | | 内存占用 | ~30% 更少 | 基准 |

批量查询（推荐多日期场景）

import { isWorkdayBatch, getFestivalBatch } from 'chinese-workday'

const dates = ['2024-10-01', '2024-10-02', '2024-10-03']
const workdayResults = isWorkdayBatch(dates) // [false, false, false]
const festivalResults = getFestivalBatch(dates) // ["国庆节", "国庆节", "国庆节"]

📊 API

基础查询

| 方法 | 说明 | | -------------------------- | -------------------------- | | isWorkday(date) | 判断是否为工作日（含调休） | | isHoliday(date) | 判断是否为节假日 | | getFestival(date) | 获取节日名称 | | isAddtionalWorkday(date) | 判断是否为调休工作日 | | isWeekend(date) | 判断是否为周末 |

批量查询

| 方法 | 说明 | | ------------------------- | ---------------- | | isWorkdayBatch(dates) | 批量判断工作日 | | isHolidayBatch(dates) | 批量判断节假日 | | getFestivalBatch(dates) | 批量获取节日名称 |

高级功能

| 方法 | 说明 | | ------------------------------------------ | -------------------- | | countWorkdays(start, end) | 计算工作日数量 | | getWorkdaysInRange(start, end) | 获取所有工作日 | | getHolidaysInRange(start, end) | 获取所有节假日 | | nextWorkday(date) | 获取下一个工作日 | | previousWorkday(date) | 获取上一个工作日 | | getWorkdaysInterval(start, end) | 计算两日期间工作日数 | | addWorkdays(date, n) | 增减工作日 | | getWorkdaySequence(start, end, interval) | 获取工作日序列 | | getAnnualStats(year) | 年度统计 |

节假日提醒功能

| 方法 | 说明 | | ---------------------------------------- | ------------------ | | getNextHoliday(date) | 获取下一个节假日 | | daysUntilHoliday(date) | 距下个节假日天数 | | isHolidayApproaching(date, daysBefore) | 节假日是否临近 | | getConsecutiveHolidays(date) | 获取连续节假日天数 |

自定义工作日安排

| 方法 | 说明 | | ------------------------------- | ---------------------- | | setWorkSchedule(id, schedule) | 设置自定义安排 | | getWorkSchedule(id) | 获取自定义安排 | | isWorkdayCustom(date, id) | 按自定义安排判断工作日 | | isHolidayCustom(date, id) | 按自定义安排判断节假日 | | clearWorkSchedule(id) | 清除自定义安排 | | getAvailableSchedules() | 获取可用安排列表 |

高级统计功能

| 方法 | 说明 | | ----------------------------------- | ---------------- | | getMonthlyStats(year, month) | 月度统计 | | getWorkdayRatio(start, end) | 工作日比例 | | getMostCommonHoliday(year) | 最常见节假日 | | getHolidaysByFestival(start, end) | 按节日分组节假日 |

工作时间相关功能

| 方法 | 说明 | | --------------------------------------------- | ---------------- | | getTotalDays(start, end) | 获取总天数 | | calculateWorkHours(start, end, hoursPerDay) | 计算工作小时 | | getWeekRange(date, startDay) | 获取周范围 | | getMonthRange(date) | 获取月范围 | | isWithinOfficeHours(date, options) | 是否在办公时间内 |

其他

| 方法 | 说明 | | ----------------- | ------------ | | getCacheStats() | 获取缓存统计 | | clearCache() | 清除缓存 |

新功能使用示例

import {
  getNextHoliday,
  getWorkdayRatio,
  setWorkSchedule,
  isWithinOfficeHours,
  setLeaveBalance,
  applyLeave,
  generateCalendar,
  isWorkdayInTimezone,
  scheduleEventNextWorkday
} from 'chinese-workday'

// 节假日临近提醒
const nextHoliday = getNextHoliday('2024-09-25')
console.log(nextHoliday) // { date: '2024-10-01', festival: '国庆节', daysUntil: 6 }

// 工作日比例统计
const ratio = getWorkdayRatio('2024-01-01', '2024-12-31')
console.log(ratio.workdayPercentage) // 全年工作日占比

// 自定义工作安排
setWorkSchedule('my_company', {
  workdays: [1, 2, 3, 4, 5], // 周一到周五
  holidays: ['2024-01-01', '2024-12-25'], // 特殊假期
  workdaysOnWeekends: ['2024-02-04', '2024-02-11'] // 调休工作日
})

// 办公时间判断
const now = new Date()
const inOffice = isWithinOfficeHours(now, {
  startHour: 9,
  endHour: 18,
  startDay: 1,
  endDay: 6 // 周一到周六
})

// 假期余额管理
setLeaveBalance('employee_001', {
  annual: 15, // 年假15天
  sick: 10, // 病假10天
  personal: 3 // 事假3天
})

const leaveResult = applyLeave('employee_001', 'annual', '2024-06-03', '2024-06-07') // 申请5天年假
console.log(leaveResult) // { success: true, message: "5 days of annual leave applied...", remainingBalance: {...} }

// 工作日历生成
const january2024 = generateCalendar(2024, 1, { includeFestival: true, includeLunar: true })
console.log('January 2024 calendar:', january2024[0]) // First week of January

// 跨时区工作日判断
const isWorkdayInNY = isWorkdayInTimezone('2024-05-06 10:00:00', 'America/New_York') // 中国标准时间下的工作日，在纽约时区是否为工作日
const isWorkdayInUTC = isWorkdayInTimezone(Date.now(), 'UTC') // 当前时间在UTC时区是否为工作日

// 工作日事件调度
const eventId = scheduleEventNextWorkday(
  'monthly_report',
  (date) => {
    console.log(`Run monthly report on next workday: ${date}`)
  },
  '2024-05-01'
) // Schedule from May 1st

// 或者安排在特定工作日执行
scheduleEventOnWorkday(
  'quarterly_meeting',
  (date) => {
    console.log(`Quarterly meeting scheduled for: ${date}`)
  },
  '2024-06-15'
) // Assuming June 15th is a workday

支持的输入格式

isWorkday('2024-10-01') // 字符串
isWorkday(new Date()) // Date 对象
isWorkday(1727712000000) // 时间戳

🎯 使用场景

• 考勤系统 · 工资计算 · 项目排期
• API 服务 · 数据分析 · 前端应用

📅 数据覆盖

• ✅ 完整支持 2011-2026 年 法定节假日和调休
• ✅ 数据来源：国务院官方公告
• ✅ 每年及时更新

🏆 特点

1. 高性能 · 内置 LRU 缓存
2. 零依赖
3. ESM + CJS 双支持
4. 浏览器 CDN 直通
5. TypeScript 类型支持
6. 简单易用

📄 许可证

MIT License

数据覆盖 2011-2026 年 · 定期更新国务院最新节假日安排