@sanguo-dev/calendar 1.0.0 → 1.0.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -21
- package/README.md +229 -229
- package/package.json +68 -68
- package/src/config.ts +198 -198
- package/src/data/Calendar.ts +599 -599
- package/src/data/festival.json +195 -195
- package/src/data/rest.json +74 -74
- package/src/index.ts +317 -317
- package/src/types.ts +146 -146
- package/src/utils/Assert.ts +230 -230
- package/src/utils/LunarFunction.ts +215 -215
- package/src/utils/SetFestival.ts +40 -40
- package/src/utils/SetRest.ts +84 -84
- package/src/utils/SolarFunction.ts +162 -162
package/LICENSE
CHANGED
|
@@ -1,21 +1,21 @@
|
|
|
1
|
-
MIT License
|
|
2
|
-
|
|
3
|
-
Copyright (c) 2016-2025 sanguogege
|
|
4
|
-
|
|
5
|
-
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
-
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
-
in the Software without restriction, including without limitation the rights
|
|
8
|
-
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
-
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
-
furnished to do so, subject to the following conditions:
|
|
11
|
-
|
|
12
|
-
The above copyright notice and this permission notice shall be included in all
|
|
13
|
-
copies or substantial portions of the Software.
|
|
14
|
-
|
|
15
|
-
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
-
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
-
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
-
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
-
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
-
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
-
SOFTWARE.
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2016-2025 sanguogege
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,229 +1,229 @@
|
|
|
1
|
-
# calendar
|
|
2
|
-
|
|
3
|
-
零依赖的公历 / 农历换算库，支持农历、节气、干支、生肖、节日和调休。
|
|
4
|
-
|
|
5
|
-
```bash
|
|
6
|
-
bun add @
|
|
7
|
-
```
|
|
8
|
-
|
|
9
|
-
## 快速开始
|
|
10
|
-
|
|
11
|
-
```ts
|
|
12
|
-
import createCalendar from "@
|
|
13
|
-
|
|
14
|
-
const calendar = createCalendar();
|
|
15
|
-
|
|
16
|
-
const day = calendar.solarToLunar(2026, 10, 1);
|
|
17
|
-
console.log(day.lMonthCn, day.lDayCn, day.gljr, day.xiu);
|
|
18
|
-
```
|
|
19
|
-
|
|
20
|
-
`createCalendar()` 不传参数时使用内置数据。每次调用都会创建一个独立实例，没有全局可变状态。
|
|
21
|
-
|
|
22
|
-
## createCalendar
|
|
23
|
-
|
|
24
|
-
```ts
|
|
25
|
-
const calendar = createCalendar(config?, options?);
|
|
26
|
-
```
|
|
27
|
-
|
|
28
|
-
| 参数 | 类型 | 说明 |
|
|
29
|
-
| ----------------- | --------------- | ----------------------------------------- |
|
|
30
|
-
| `config` | `HolidayConfig` | 节假日 / 调休配置，默认与内置数据合并 |
|
|
31
|
-
| `options.replace` | `boolean` | 为 `true` 时丢弃内置数据，只使用 `config` |
|
|
32
|
-
|
|
33
|
-
```ts
|
|
34
|
-
const company = createCalendar(
|
|
35
|
-
{ setRest: { 2027: { xiu: ["0101", "0102"], ban: ["0104"] } } },
|
|
36
|
-
{ replace: true },
|
|
37
|
-
);
|
|
38
|
-
|
|
39
|
-
company.solarToLunar(2027, 1, 4).ban; // true
|
|
40
|
-
createCalendar().solarToLunar(2027, 1, 4).ban; // false
|
|
41
|
-
```
|
|
42
|
-
|
|
43
|
-
- 配置在创建时校验、深拷贝并冻结；
|
|
44
|
-
- 多个实例互不影响；
|
|
45
|
-
- 修改传入对象不会影响已经创建的实例；
|
|
46
|
-
- 配置错误立即抛 `TypeError`，错误信息带 `createCalendar.…` 字段路径。
|
|
47
|
-
|
|
48
|
-
## 实例方法
|
|
49
|
-
|
|
50
|
-
| 方法 | 说明 |
|
|
51
|
-
| ------------------------------------- | -------------------------------------------------------- |
|
|
52
|
-
| `solarToLunar(y?, m?, d?)` | 公历转农历；不传参数返回今天 |
|
|
53
|
-
| `lunarToSolar(y, m, d, isLeapMonth?)` | 农历转公历，`isLeapMonth` 只接受布尔值 |
|
|
54
|
-
| `getHolidays(options?)` | 当前配置的深拷贝；`{ merged: false }` 只导出你传入的部分 |
|
|
55
|
-
|
|
56
|
-
```ts
|
|
57
|
-
const calendar = createCalendar();
|
|
58
|
-
|
|
59
|
-
calendar.solarToLunar(); // 今天
|
|
60
|
-
calendar.solarToLunar(2026, 10, 1);
|
|
61
|
-
|
|
62
|
-
calendar.lunarToSolar(2024, 1, 1); // 2024-02-10
|
|
63
|
-
calendar.lunarToSolar(2020, 4, 1, true); // 闰四月
|
|
64
|
-
|
|
65
|
-
// 完整配置（内置 + 你注入的）
|
|
66
|
-
const snapshot = calendar.getHolidays();
|
|
67
|
-
|
|
68
|
-
// 只导出你注入的部分，方便存到后端或单独维护
|
|
69
|
-
const own = calendar.getHolidays({ merged: false });
|
|
70
|
-
```
|
|
71
|
-
|
|
72
|
-
## LunarResult
|
|
73
|
-
|
|
74
|
-
`solarToLunar` / `lunarToSolar` 都返回完整结果：
|
|
75
|
-
|
|
76
|
-
| 字段 | 类型 | 说明 |
|
|
77
|
-
| --------------------------- | ------------------- | ---------------------------- |
|
|
78
|
-
| `xiu` | `boolean` | 是否在放假日列表；与周末无关 |
|
|
79
|
-
| `ban` | `boolean` | 是否在补班日列表 |
|
|
80
|
-
| `gljr` | `readonly string[]` | 公历节日 |
|
|
81
|
-
| `nljr` | `readonly string[]` | 农历节日 |
|
|
82
|
-
| `lYear` / `lMonth` / `lDay` | `number` | 农历年 / 月 / 日 |
|
|
83
|
-
| `isLeap` | `boolean` | 是否闰月 |
|
|
84
|
-
| `lMonthCn` / `lDayCn` | `string` | 农历月 / 日中文 |
|
|
85
|
-
| `animal` | `string` | 生肖 |
|
|
86
|
-
| `cYear` / `cMonth` / `cDay` | `number` | 公历年 / 月 / 日 |
|
|
87
|
-
| `gzYear` | `string` | 干支年（立春为界） |
|
|
88
|
-
| `gzYearLunar` | `string` | 干支年（正月初一为界） |
|
|
89
|
-
| `gzMonth` / `gzDay` | `string` | 干支月 / 日 |
|
|
90
|
-
| `gzHour` | `string[]` | 十二时辰干支 |
|
|
91
|
-
| `isToday` | `boolean` | 是否今天 |
|
|
92
|
-
| `nWeek` | `number` | 星期 1-7，周日为 7 |
|
|
93
|
-
| `dayOfWeek` | `number` | 星期 0-6，周日为 0 |
|
|
94
|
-
| `ncWeek` | `string` | 星期中文 |
|
|
95
|
-
| `term` | `string \| null` | 节气名 |
|
|
96
|
-
| `astro` | `string` | 星座 |
|
|
97
|
-
|
|
98
|
-
支持范围：`1900-01-31 ~ 2100-12-31`。越界、非法日期、不存在的闰月都抛 `RangeError`。
|
|
99
|
-
|
|
100
|
-
## 节日与调休
|
|
101
|
-
|
|
102
|
-
### HolidayConfig
|
|
103
|
-
|
|
104
|
-
```ts
|
|
105
|
-
interface HolidayConfig {
|
|
106
|
-
setFestival?: {
|
|
107
|
-
sFtv?: Record<string, string[]>; // 公历节日，MMDD
|
|
108
|
-
lFtv?: Record<string, string[]>; // 农历节日，MMDD
|
|
109
|
-
};
|
|
110
|
-
setRest?: {
|
|
111
|
-
[year: string]: {
|
|
112
|
-
xiu?: string[]; // 放假 MMDD
|
|
113
|
-
ban?: string[]; // 补班 MMDD
|
|
114
|
-
};
|
|
115
|
-
};
|
|
116
|
-
}
|
|
117
|
-
```
|
|
118
|
-
|
|
119
|
-
```ts
|
|
120
|
-
const calendar = createCalendar({
|
|
121
|
-
setFestival: {
|
|
122
|
-
sFtv: { "0419": ["项目上线日"] },
|
|
123
|
-
},
|
|
124
|
-
setRest: {
|
|
125
|
-
2027: { xiu: ["0101", "0102"], ban: ["0104"] },
|
|
126
|
-
},
|
|
127
|
-
});
|
|
128
|
-
|
|
129
|
-
calendar.solarToLunar(2027, 1, 4).ban; // true
|
|
130
|
-
```
|
|
131
|
-
|
|
132
|
-
### xiu / ban
|
|
133
|
-
|
|
134
|
-
`xiu` / `ban` 完全由配置决定，和周末无关：
|
|
135
|
-
|
|
136
|
-
```ts
|
|
137
|
-
day.xiu; // 在放假日列表
|
|
138
|
-
day.ban; // 在补班日列表
|
|
139
|
-
day.dayOfWeek; // 0-6，判断周末用这个
|
|
140
|
-
```
|
|
141
|
-
|
|
142
|
-
内置数据来自国务院办公厅通知：[2026 年](https://www.gov.cn/zhengce/content/202511/content_7047090.htm)、[2027 年](https://www.gov.cn/zhengce/content/202611/content_7085101.htm)：
|
|
143
|
-
|
|
144
|
-
**2026 年**
|
|
145
|
-
|
|
146
|
-
| 假期 | 放假 | 补班 |
|
|
147
|
-
| ------ | ----------- | ----------- |
|
|
148
|
-
| 元旦 | 1/1 - 1/3 | 1/4 |
|
|
149
|
-
| 春节 | 2/15 - 2/23 | 2/14、2/28 |
|
|
150
|
-
| 清明节 | 4/4 - 4/6 | - |
|
|
151
|
-
| 劳动节 | 5/1 - 5/5 | 5/9 |
|
|
152
|
-
| 端午节 | 6/19 - 6/21 | - |
|
|
153
|
-
| 中秋节 | 9/25 - 9/27 | - |
|
|
154
|
-
| 国庆节 | 10/1 - 10/7 | 9/20、10/10 |
|
|
155
|
-
|
|
156
|
-
**2027 年**
|
|
157
|
-
|
|
158
|
-
| 假期 | 放假 | 补班 |
|
|
159
|
-
| ------ | ----------- | ---------- |
|
|
160
|
-
| 元旦 | 1/1 - 1/3 | - |
|
|
161
|
-
| 春节 | 2/5 - 2/13 | 1/31、2/14 |
|
|
162
|
-
| 清明节 | 4/3 - 4/5 | - |
|
|
163
|
-
| 劳动节 | 5/1 - 5/5 | 5/8 |
|
|
164
|
-
| 端午节 | 6/9 | - |
|
|
165
|
-
| 中秋节 | 9/15 | - |
|
|
166
|
-
| 国庆节 | 10/1 - 10/7 | 9/26、10/9 |
|
|
167
|
-
|
|
168
|
-
### 快照
|
|
169
|
-
|
|
170
|
-
```ts
|
|
171
|
-
const snapshot = createCalendar().getHolidays();
|
|
172
|
-
const copy = createCalendar(snapshot);
|
|
173
|
-
```
|
|
174
|
-
|
|
175
|
-
`getHolidays()` 返回深拷贝，不会共享内部数组。
|
|
176
|
-
|
|
177
|
-
注意：`getHolidays()` 返回的是**当前生效的配置**（含内置数据）。如果实例是用 `{ replace: true }` 建的空配置，快照就是空的；再传给 `createCalendar()` 时若不带 `{ replace: true }`，内置数据会重新合并回来。想只导出自己注入的部分用 `getHolidays({ merged: false })`。
|
|
178
|
-
|
|
179
|
-
## 校验规则
|
|
180
|
-
|
|
181
|
-
| 规则 | 说明 |
|
|
182
|
-
| ------------- | ----------------------------------------------------- |
|
|
183
|
-
| 公历 MMDD | 必须真实存在，`0230`、`0431` 这类会直接抛 `TypeError` |
|
|
184
|
-
| 农历 MMDD | 每月最多 30 天（农历任意月都可能是 30 天） |
|
|
185
|
-
| `xiu` / `ban` | 同一天不能既放假又补班，冲突会抛 `TypeError` |
|
|
186
|
-
| 闰月节日 | 闰月不过节：闰五月初五不算端午、闰八月十五不算中秋 |
|
|
187
|
-
| `isLeapMonth` | 只接受布尔值，传 `"true"`、`1` 会抛 `TypeError` |
|
|
188
|
-
| 年份 | `setRest` 的 key 必须在 1900-2100 之间 |
|
|
189
|
-
|
|
190
|
-
## 工具函数
|
|
191
|
-
|
|
192
|
-
`utils` 是具名导出的无状态函数，不读取实例配置：
|
|
193
|
-
|
|
194
|
-
```ts
|
|
195
|
-
import { utils } from "@
|
|
196
|
-
|
|
197
|
-
utils.lYearDays(2026);
|
|
198
|
-
utils.leapMonth(2026);
|
|
199
|
-
utils.leapDays(2026);
|
|
200
|
-
utils.lMonthDays(2026, 3);
|
|
201
|
-
utils.toChinaMonth(3); // "三月"
|
|
202
|
-
utils.toChinaDay(21); // "廿一"
|
|
203
|
-
utils.toChinaNum(3); // "三"
|
|
204
|
-
utils.solarDays(2026, 2); // 28
|
|
205
|
-
utils.solarFirstWeek(2026, 4); // 3
|
|
206
|
-
utils.nthWeekdayOfMonth(2026, 5, 0, 2); // 10
|
|
207
|
-
utils.toAstro(4, 19); // "白羊座"
|
|
208
|
-
utils.getAnimal(2026); // "马"
|
|
209
|
-
utils.getTerm(2026, 3); // 4
|
|
210
|
-
utils.getSolarTerm(0); // "小寒"
|
|
211
|
-
utils.toGanZhi(40); // "甲辰"
|
|
212
|
-
utils.toGanZhiYear(2024); // "甲辰"
|
|
213
|
-
utils.toHourGanZhi(40); // ["甲子", "乙丑", ...]
|
|
214
|
-
```
|
|
215
|
-
|
|
216
|
-
## 错误
|
|
217
|
-
|
|
218
|
-
| 异常 | 场景 |
|
|
219
|
-
| ------------ | -------------------------------------------------- |
|
|
220
|
-
| `RangeError` | 日期越界、日期不存在、闰月不匹配、工具函数参数越界 |
|
|
221
|
-
| `TypeError` | `createCalendar` 的配置结构或类型不合法 |
|
|
222
|
-
|
|
223
|
-
## 2.x 变化
|
|
224
|
-
|
|
225
|
-
- 默认导出改成 `createCalendar` 函数；不再有 `calendar.solarToLunar` 这种默认对象；
|
|
226
|
-
- 删除全局 `setHolidays` / `resetHolidays`，配置只通过 `createCalendar(config)` 传入；
|
|
227
|
-
- `createConverter` 重命名为 `createCalendar`；
|
|
228
|
-
- `utils` 改为具名导出；
|
|
229
|
-
- 每次调用 `createCalendar()` 都是独立实例，没有跨实例状态。
|
|
1
|
+
# calendar
|
|
2
|
+
|
|
3
|
+
零依赖的公历 / 农历换算库，支持农历、节气、干支、生肖、节日和调休。
|
|
4
|
+
|
|
5
|
+
```bash
|
|
6
|
+
bun add @sanguo-dev/calendar
|
|
7
|
+
```
|
|
8
|
+
|
|
9
|
+
## 快速开始
|
|
10
|
+
|
|
11
|
+
```ts
|
|
12
|
+
import createCalendar from "@sanguo-dev/calendar";
|
|
13
|
+
|
|
14
|
+
const calendar = createCalendar();
|
|
15
|
+
|
|
16
|
+
const day = calendar.solarToLunar(2026, 10, 1);
|
|
17
|
+
console.log(day.lMonthCn, day.lDayCn, day.gljr, day.xiu);
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
`createCalendar()` 不传参数时使用内置数据。每次调用都会创建一个独立实例，没有全局可变状态。
|
|
21
|
+
|
|
22
|
+
## createCalendar
|
|
23
|
+
|
|
24
|
+
```ts
|
|
25
|
+
const calendar = createCalendar(config?, options?);
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
| 参数 | 类型 | 说明 |
|
|
29
|
+
| ----------------- | --------------- | ----------------------------------------- |
|
|
30
|
+
| `config` | `HolidayConfig` | 节假日 / 调休配置，默认与内置数据合并 |
|
|
31
|
+
| `options.replace` | `boolean` | 为 `true` 时丢弃内置数据，只使用 `config` |
|
|
32
|
+
|
|
33
|
+
```ts
|
|
34
|
+
const company = createCalendar(
|
|
35
|
+
{ setRest: { 2027: { xiu: ["0101", "0102"], ban: ["0104"] } } },
|
|
36
|
+
{ replace: true },
|
|
37
|
+
);
|
|
38
|
+
|
|
39
|
+
company.solarToLunar(2027, 1, 4).ban; // true
|
|
40
|
+
createCalendar().solarToLunar(2027, 1, 4).ban; // false
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
- 配置在创建时校验、深拷贝并冻结；
|
|
44
|
+
- 多个实例互不影响；
|
|
45
|
+
- 修改传入对象不会影响已经创建的实例；
|
|
46
|
+
- 配置错误立即抛 `TypeError`，错误信息带 `createCalendar.…` 字段路径。
|
|
47
|
+
|
|
48
|
+
## 实例方法
|
|
49
|
+
|
|
50
|
+
| 方法 | 说明 |
|
|
51
|
+
| ------------------------------------- | -------------------------------------------------------- |
|
|
52
|
+
| `solarToLunar(y?, m?, d?)` | 公历转农历；不传参数返回今天 |
|
|
53
|
+
| `lunarToSolar(y, m, d, isLeapMonth?)` | 农历转公历，`isLeapMonth` 只接受布尔值 |
|
|
54
|
+
| `getHolidays(options?)` | 当前配置的深拷贝；`{ merged: false }` 只导出你传入的部分 |
|
|
55
|
+
|
|
56
|
+
```ts
|
|
57
|
+
const calendar = createCalendar();
|
|
58
|
+
|
|
59
|
+
calendar.solarToLunar(); // 今天
|
|
60
|
+
calendar.solarToLunar(2026, 10, 1);
|
|
61
|
+
|
|
62
|
+
calendar.lunarToSolar(2024, 1, 1); // 2024-02-10
|
|
63
|
+
calendar.lunarToSolar(2020, 4, 1, true); // 闰四月
|
|
64
|
+
|
|
65
|
+
// 完整配置（内置 + 你注入的）
|
|
66
|
+
const snapshot = calendar.getHolidays();
|
|
67
|
+
|
|
68
|
+
// 只导出你注入的部分，方便存到后端或单独维护
|
|
69
|
+
const own = calendar.getHolidays({ merged: false });
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
## LunarResult
|
|
73
|
+
|
|
74
|
+
`solarToLunar` / `lunarToSolar` 都返回完整结果：
|
|
75
|
+
|
|
76
|
+
| 字段 | 类型 | 说明 |
|
|
77
|
+
| --------------------------- | ------------------- | ---------------------------- |
|
|
78
|
+
| `xiu` | `boolean` | 是否在放假日列表；与周末无关 |
|
|
79
|
+
| `ban` | `boolean` | 是否在补班日列表 |
|
|
80
|
+
| `gljr` | `readonly string[]` | 公历节日 |
|
|
81
|
+
| `nljr` | `readonly string[]` | 农历节日 |
|
|
82
|
+
| `lYear` / `lMonth` / `lDay` | `number` | 农历年 / 月 / 日 |
|
|
83
|
+
| `isLeap` | `boolean` | 是否闰月 |
|
|
84
|
+
| `lMonthCn` / `lDayCn` | `string` | 农历月 / 日中文 |
|
|
85
|
+
| `animal` | `string` | 生肖 |
|
|
86
|
+
| `cYear` / `cMonth` / `cDay` | `number` | 公历年 / 月 / 日 |
|
|
87
|
+
| `gzYear` | `string` | 干支年（立春为界） |
|
|
88
|
+
| `gzYearLunar` | `string` | 干支年（正月初一为界） |
|
|
89
|
+
| `gzMonth` / `gzDay` | `string` | 干支月 / 日 |
|
|
90
|
+
| `gzHour` | `string[]` | 十二时辰干支 |
|
|
91
|
+
| `isToday` | `boolean` | 是否今天 |
|
|
92
|
+
| `nWeek` | `number` | 星期 1-7，周日为 7 |
|
|
93
|
+
| `dayOfWeek` | `number` | 星期 0-6，周日为 0 |
|
|
94
|
+
| `ncWeek` | `string` | 星期中文 |
|
|
95
|
+
| `term` | `string \| null` | 节气名 |
|
|
96
|
+
| `astro` | `string` | 星座 |
|
|
97
|
+
|
|
98
|
+
支持范围：`1900-01-31 ~ 2100-12-31`。越界、非法日期、不存在的闰月都抛 `RangeError`。
|
|
99
|
+
|
|
100
|
+
## 节日与调休
|
|
101
|
+
|
|
102
|
+
### HolidayConfig
|
|
103
|
+
|
|
104
|
+
```ts
|
|
105
|
+
interface HolidayConfig {
|
|
106
|
+
setFestival?: {
|
|
107
|
+
sFtv?: Record<string, string[]>; // 公历节日，MMDD
|
|
108
|
+
lFtv?: Record<string, string[]>; // 农历节日，MMDD
|
|
109
|
+
};
|
|
110
|
+
setRest?: {
|
|
111
|
+
[year: string]: {
|
|
112
|
+
xiu?: string[]; // 放假 MMDD
|
|
113
|
+
ban?: string[]; // 补班 MMDD
|
|
114
|
+
};
|
|
115
|
+
};
|
|
116
|
+
}
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
```ts
|
|
120
|
+
const calendar = createCalendar({
|
|
121
|
+
setFestival: {
|
|
122
|
+
sFtv: { "0419": ["项目上线日"] },
|
|
123
|
+
},
|
|
124
|
+
setRest: {
|
|
125
|
+
2027: { xiu: ["0101", "0102"], ban: ["0104"] },
|
|
126
|
+
},
|
|
127
|
+
});
|
|
128
|
+
|
|
129
|
+
calendar.solarToLunar(2027, 1, 4).ban; // true
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
### xiu / ban
|
|
133
|
+
|
|
134
|
+
`xiu` / `ban` 完全由配置决定，和周末无关：
|
|
135
|
+
|
|
136
|
+
```ts
|
|
137
|
+
day.xiu; // 在放假日列表
|
|
138
|
+
day.ban; // 在补班日列表
|
|
139
|
+
day.dayOfWeek; // 0-6，判断周末用这个
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
内置数据来自国务院办公厅通知：[2026 年](https://www.gov.cn/zhengce/content/202511/content_7047090.htm)、[2027 年](https://www.gov.cn/zhengce/content/202611/content_7085101.htm)：
|
|
143
|
+
|
|
144
|
+
**2026 年**
|
|
145
|
+
|
|
146
|
+
| 假期 | 放假 | 补班 |
|
|
147
|
+
| ------ | ----------- | ----------- |
|
|
148
|
+
| 元旦 | 1/1 - 1/3 | 1/4 |
|
|
149
|
+
| 春节 | 2/15 - 2/23 | 2/14、2/28 |
|
|
150
|
+
| 清明节 | 4/4 - 4/6 | - |
|
|
151
|
+
| 劳动节 | 5/1 - 5/5 | 5/9 |
|
|
152
|
+
| 端午节 | 6/19 - 6/21 | - |
|
|
153
|
+
| 中秋节 | 9/25 - 9/27 | - |
|
|
154
|
+
| 国庆节 | 10/1 - 10/7 | 9/20、10/10 |
|
|
155
|
+
|
|
156
|
+
**2027 年**
|
|
157
|
+
|
|
158
|
+
| 假期 | 放假 | 补班 |
|
|
159
|
+
| ------ | ----------- | ---------- |
|
|
160
|
+
| 元旦 | 1/1 - 1/3 | - |
|
|
161
|
+
| 春节 | 2/5 - 2/13 | 1/31、2/14 |
|
|
162
|
+
| 清明节 | 4/3 - 4/5 | - |
|
|
163
|
+
| 劳动节 | 5/1 - 5/5 | 5/8 |
|
|
164
|
+
| 端午节 | 6/9 | - |
|
|
165
|
+
| 中秋节 | 9/15 | - |
|
|
166
|
+
| 国庆节 | 10/1 - 10/7 | 9/26、10/9 |
|
|
167
|
+
|
|
168
|
+
### 快照
|
|
169
|
+
|
|
170
|
+
```ts
|
|
171
|
+
const snapshot = createCalendar().getHolidays();
|
|
172
|
+
const copy = createCalendar(snapshot);
|
|
173
|
+
```
|
|
174
|
+
|
|
175
|
+
`getHolidays()` 返回深拷贝，不会共享内部数组。
|
|
176
|
+
|
|
177
|
+
注意：`getHolidays()` 返回的是**当前生效的配置**（含内置数据）。如果实例是用 `{ replace: true }` 建的空配置，快照就是空的；再传给 `createCalendar()` 时若不带 `{ replace: true }`，内置数据会重新合并回来。想只导出自己注入的部分用 `getHolidays({ merged: false })`。
|
|
178
|
+
|
|
179
|
+
## 校验规则
|
|
180
|
+
|
|
181
|
+
| 规则 | 说明 |
|
|
182
|
+
| ------------- | ----------------------------------------------------- |
|
|
183
|
+
| 公历 MMDD | 必须真实存在，`0230`、`0431` 这类会直接抛 `TypeError` |
|
|
184
|
+
| 农历 MMDD | 每月最多 30 天（农历任意月都可能是 30 天） |
|
|
185
|
+
| `xiu` / `ban` | 同一天不能既放假又补班，冲突会抛 `TypeError` |
|
|
186
|
+
| 闰月节日 | 闰月不过节：闰五月初五不算端午、闰八月十五不算中秋 |
|
|
187
|
+
| `isLeapMonth` | 只接受布尔值，传 `"true"`、`1` 会抛 `TypeError` |
|
|
188
|
+
| 年份 | `setRest` 的 key 必须在 1900-2100 之间 |
|
|
189
|
+
|
|
190
|
+
## 工具函数
|
|
191
|
+
|
|
192
|
+
`utils` 是具名导出的无状态函数，不读取实例配置：
|
|
193
|
+
|
|
194
|
+
```ts
|
|
195
|
+
import { utils } from "@sanguo-dev/calendar";
|
|
196
|
+
|
|
197
|
+
utils.lYearDays(2026);
|
|
198
|
+
utils.leapMonth(2026);
|
|
199
|
+
utils.leapDays(2026);
|
|
200
|
+
utils.lMonthDays(2026, 3);
|
|
201
|
+
utils.toChinaMonth(3); // "三月"
|
|
202
|
+
utils.toChinaDay(21); // "廿一"
|
|
203
|
+
utils.toChinaNum(3); // "三"
|
|
204
|
+
utils.solarDays(2026, 2); // 28
|
|
205
|
+
utils.solarFirstWeek(2026, 4); // 3
|
|
206
|
+
utils.nthWeekdayOfMonth(2026, 5, 0, 2); // 10
|
|
207
|
+
utils.toAstro(4, 19); // "白羊座"
|
|
208
|
+
utils.getAnimal(2026); // "马"
|
|
209
|
+
utils.getTerm(2026, 3); // 4
|
|
210
|
+
utils.getSolarTerm(0); // "小寒"
|
|
211
|
+
utils.toGanZhi(40); // "甲辰"
|
|
212
|
+
utils.toGanZhiYear(2024); // "甲辰"
|
|
213
|
+
utils.toHourGanZhi(40); // ["甲子", "乙丑", ...]
|
|
214
|
+
```
|
|
215
|
+
|
|
216
|
+
## 错误
|
|
217
|
+
|
|
218
|
+
| 异常 | 场景 |
|
|
219
|
+
| ------------ | -------------------------------------------------- |
|
|
220
|
+
| `RangeError` | 日期越界、日期不存在、闰月不匹配、工具函数参数越界 |
|
|
221
|
+
| `TypeError` | `createCalendar` 的配置结构或类型不合法 |
|
|
222
|
+
|
|
223
|
+
## 2.x 变化
|
|
224
|
+
|
|
225
|
+
- 默认导出改成 `createCalendar` 函数；不再有 `calendar.solarToLunar` 这种默认对象；
|
|
226
|
+
- 删除全局 `setHolidays` / `resetHolidays`，配置只通过 `createCalendar(config)` 传入；
|
|
227
|
+
- `createConverter` 重命名为 `createCalendar`；
|
|
228
|
+
- `utils` 改为具名导出；
|
|
229
|
+
- 每次调用 `createCalendar()` 都是独立实例，没有跨实例状态。
|
package/package.json
CHANGED
|
@@ -1,68 +1,68 @@
|
|
|
1
|
-
{
|
|
2
|
-
"name": "@sanguo-dev/calendar",
|
|
3
|
-
"version": "1.0.
|
|
4
|
-
"description": "ts版本的日历生成器 LTS",
|
|
5
|
-
"keywords": [
|
|
6
|
-
"calendar",
|
|
7
|
-
"lunar",
|
|
8
|
-
"农历",
|
|
9
|
-
"日历",
|
|
10
|
-
"阳历"
|
|
11
|
-
],
|
|
12
|
-
"homepage": "https://github.com/sanguo-dev/calendar#readme",
|
|
13
|
-
"bugs": {
|
|
14
|
-
"url": "https://github.com/sanguo-dev/calendar/issues"
|
|
15
|
-
},
|
|
16
|
-
"license": "MIT",
|
|
17
|
-
"author": "sanguogege@outlook.com",
|
|
18
|
-
"repository": {
|
|
19
|
-
"type": "git",
|
|
20
|
-
"url": "git+https://github.com/sanguo-dev/calendar.git",
|
|
21
|
-
"directory": "packages/calendar"
|
|
22
|
-
},
|
|
23
|
-
"files": [
|
|
24
|
-
"dist",
|
|
25
|
-
"src"
|
|
26
|
-
],
|
|
27
|
-
"type": "module",
|
|
28
|
-
"sideEffects": false,
|
|
29
|
-
"main": "./dist/index.cjs",
|
|
30
|
-
"module": "./dist/index.mjs",
|
|
31
|
-
"types": "./dist/index.d.cts",
|
|
32
|
-
"unpkg": "./dist/index.iife.js",
|
|
33
|
-
"jsdelivr": "./dist/index.iife.js",
|
|
34
|
-
"exports": {
|
|
35
|
-
".": {
|
|
36
|
-
"development": {
|
|
37
|
-
"types": "./src/index.ts",
|
|
38
|
-
"default": "./src/index.ts"
|
|
39
|
-
},
|
|
40
|
-
"import": {
|
|
41
|
-
"types": "./dist/index.d.mts",
|
|
42
|
-
"default": "./dist/index.mjs"
|
|
43
|
-
},
|
|
44
|
-
"require": {
|
|
45
|
-
"types": "./dist/index.d.cts",
|
|
46
|
-
"default": "./dist/index.cjs"
|
|
47
|
-
}
|
|
48
|
-
},
|
|
49
|
-
"./package.json": "./package.json"
|
|
50
|
-
},
|
|
51
|
-
"publishConfig": {
|
|
52
|
-
"access": "public",
|
|
53
|
-
"registry": "https://registry.npmjs.org"
|
|
54
|
-
},
|
|
55
|
-
"scripts": {
|
|
56
|
-
"build": "vp pack",
|
|
57
|
-
"dev": "vp pack --watch",
|
|
58
|
-
"test": "vp test",
|
|
59
|
-
"check": "vp check",
|
|
60
|
-
"prepublishOnly": "vp run build"
|
|
61
|
-
},
|
|
62
|
-
"devDependencies": {
|
|
63
|
-
"@types/node": "catalog:",
|
|
64
|
-
"typescript": "catalog:",
|
|
65
|
-
"vite": "catalog:",
|
|
66
|
-
"vite-plus": "catalog:"
|
|
67
|
-
}
|
|
68
|
-
}
|
|
1
|
+
{
|
|
2
|
+
"name": "@sanguo-dev/calendar",
|
|
3
|
+
"version": "1.0.1",
|
|
4
|
+
"description": "ts版本的日历生成器 LTS",
|
|
5
|
+
"keywords": [
|
|
6
|
+
"calendar",
|
|
7
|
+
"lunar",
|
|
8
|
+
"农历",
|
|
9
|
+
"日历",
|
|
10
|
+
"阳历"
|
|
11
|
+
],
|
|
12
|
+
"homepage": "https://github.com/sanguo-dev/calendar#readme",
|
|
13
|
+
"bugs": {
|
|
14
|
+
"url": "https://github.com/sanguo-dev/calendar/issues"
|
|
15
|
+
},
|
|
16
|
+
"license": "MIT",
|
|
17
|
+
"author": "sanguogege@outlook.com",
|
|
18
|
+
"repository": {
|
|
19
|
+
"type": "git",
|
|
20
|
+
"url": "git+https://github.com/sanguo-dev/calendar.git",
|
|
21
|
+
"directory": "packages/calendar"
|
|
22
|
+
},
|
|
23
|
+
"files": [
|
|
24
|
+
"dist",
|
|
25
|
+
"src"
|
|
26
|
+
],
|
|
27
|
+
"type": "module",
|
|
28
|
+
"sideEffects": false,
|
|
29
|
+
"main": "./dist/index.cjs",
|
|
30
|
+
"module": "./dist/index.mjs",
|
|
31
|
+
"types": "./dist/index.d.cts",
|
|
32
|
+
"unpkg": "./dist/index.iife.js",
|
|
33
|
+
"jsdelivr": "./dist/index.iife.js",
|
|
34
|
+
"exports": {
|
|
35
|
+
".": {
|
|
36
|
+
"development": {
|
|
37
|
+
"types": "./src/index.ts",
|
|
38
|
+
"default": "./src/index.ts"
|
|
39
|
+
},
|
|
40
|
+
"import": {
|
|
41
|
+
"types": "./dist/index.d.mts",
|
|
42
|
+
"default": "./dist/index.mjs"
|
|
43
|
+
},
|
|
44
|
+
"require": {
|
|
45
|
+
"types": "./dist/index.d.cts",
|
|
46
|
+
"default": "./dist/index.cjs"
|
|
47
|
+
}
|
|
48
|
+
},
|
|
49
|
+
"./package.json": "./package.json"
|
|
50
|
+
},
|
|
51
|
+
"publishConfig": {
|
|
52
|
+
"access": "public",
|
|
53
|
+
"registry": "https://registry.npmjs.org"
|
|
54
|
+
},
|
|
55
|
+
"scripts": {
|
|
56
|
+
"build": "vp pack",
|
|
57
|
+
"dev": "vp pack --watch",
|
|
58
|
+
"test": "vp test",
|
|
59
|
+
"check": "vp check",
|
|
60
|
+
"prepublishOnly": "vp run build"
|
|
61
|
+
},
|
|
62
|
+
"devDependencies": {
|
|
63
|
+
"@types/node": "catalog:",
|
|
64
|
+
"typescript": "catalog:",
|
|
65
|
+
"vite": "catalog:",
|
|
66
|
+
"vite-plus": "catalog:"
|
|
67
|
+
}
|
|
68
|
+
}
|