chinese-calendar

零依赖的 ESM npm 包，判断中国大陆指定日期是否需要上班，遵循国务院官方节假日和调休安排，可选支持广西三月三。

English Documentation

安装

npm install @weiensong/chinese-calendar

使用

import { isWorkday, getDayInfo } from "@weiensong/chinese-calendar";

isWorkday(input, options?)

返回 true 表示上班日，false 表示休息日。

isWorkday(new Date(2026, 0, 5));   // true  — 星期一
isWorkday("2026-01-01");           // false — 元旦假期
isWorkday("2026-01-04");           // true  — 元旦调休上班

getDayInfo(input, options?)

返回包含判断依据的详细对象。

getDayInfo("2026-01-04");
// {
//   date: "2026-01-04",
//   isWorkday: true,
//   type: "adjusted-workday",
//   holidayName: "元旦",
//   scheduleYear: 2026,
//   scheduleStatus: "official",
//   sourceUrl: "https://www.gov.cn/..."
// }

| type | 含义 | | ------------------ | ------------ | | regular-workday | 普通工作日 | | weekend | 普通周末 | | holiday | 法定节假日 | | adjusted-workday | 调休上班日 |

选项

interface Options {
  requireOfficialSchedule?: boolean;  // 无年度数据时抛出错误
  enableGuangxiSanyuesan?: boolean;   // 启用广西三月三
}

严格模式

import { isWorkday, ScheduleNotFoundError } from "@weiensong/chinese-calendar";

try {
  isWorkday("2027-01-04", { requireOfficialSchedule: true });
} catch (error) {
  console.log(error instanceof ScheduleNotFoundError); // true
}

广西三月三

默认不启用。启用后，三月三日期区间内的日期全部按广西规则判断，全国调休不覆盖该区间。

isWorkday("2025-03-31");                                   // true  — 全国工作日
isWorkday("2025-03-31", { enableGuangxiSanyuesan: true }); // false — 广西三月三放假

日期输入

接受 Date 对象或字符串。YYYY-MM-DD 格式按本地日历日期解析（无时区偏移），其他字符串通过 new Date() 解析并按运行环境本地时区判断。无效输入抛出 TypeError。

覆盖范围

内置 2014—2026 年国务院节假日安排，包含历史上的后续调整（2015 年抗战胜利纪念日、2019 年劳动节调整、2020 年春节延长）。

缺少年度数据时默认退回普通星期规则，可启用严格模式抛出 ScheduleNotFoundError。

添加新年份

1. 按以下结构创建 data/YYYY.js。
2. 在 data/index.js 中注册。

export default {
  year: 2026,
  source: {
    title: "国务院办公厅关于2026年部分节假日安排的通知",
    documentNumber: "国办发明电〔2025〕7号",
    publishedAt: "2025-11-04",
    url: "https://www.gov.cn/...",
  },
  holidays: [
    { name: "春节", start: "2026-02-15", end: "2026-02-23" },
  ],
  adjustedWorkdays: [
    { date: "2026-02-14", relatedHoliday: "春节" },
  ],
  guangxiSanyuesan: {
    name: "广西三月三",
    daysOff: [],
    adjustedWorkdays: [],
  },
};

guangxiSanyuesan 字段为必填，没有假期时保留空数组。

测试

npm test

使用 Node.js 原生测试运行器，无需安装额外依赖。

许可证

MIT