chinese-workday

🇨🇳 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/chinese-workday@2.0.0/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 年 法定节假日和调休
• ✅ 数据来源：国务院官方公告
• ✅ 每年及时更新

🏆 特点

• 高性能 · 内置 LRU 缓存
• 零依赖
• ESM + CJS 双支持
• 浏览器 CDN 直通
• TypeScript 类型支持
• 简单易用

📄 许可证

MIT License

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