API 参考

以下内容基于 1.0.1 实际发布产物逐项验证（而非 README 声明），含真实行为与已知缺陷。

format(offset?, pattern?)

参数	类型	说明
offset	string（可选）	偏移字符串（'-7'、'+3'，允许首尾空格）；仅在同时传入第二个参数时生效
pattern	string	格式化模板

返回：格式化后的字符串。

调用	行为（实测）
format()	⚠️ 抛 TypeError（无参调用未处理）
format(pattern)	当前时间按模板格式化
format(offset, pattern)	偏移 N 天后（保留时分秒）按模板格式化
format('-7')	⚠️ 单参偏移字符串被当模板，原样返回 '-7'

转义：Token 前加反斜杠可阻止替换（如 \a 输出 a）。

Token 表（v1 实际行为）

以 2023-03-10 15:00:00（星期五）为例：

Token	含义	示例输出	说明
YYYY	四位年	2023
yy	两位年（小写）	23	v2 中改为大写 YY
Y	中文年（逐位）	二零二三	与 v2 一致
MM	两位月（补零）	03
mm	不补零月	3	v1 独有，v2 无此 Token
M	中文月（逐位）	三；10 月 → 一零	v2 改为按数值：10 → 十
DD	两位日（补零）	10
dd	不补零日	10	v1 独有，v2 无此 Token
D	中文日（逐位）	一零；25 日 → 二五	v2 改为按数值：25 → 二十五
hh	两位时（24 小时制补零）	15	与 v2 一致；不是 12 小时制
ii	两位分（补零）	00	不是 mm
ss	两位秒（补零）	00
a	时段	下午	仅两档：小时 > 12 → 下午，否则 上午；v2 为六档
EEE	星期全称	星期五
EE	星期简称	周五

辅助方法

函数	参数	返回	实测行为
getDays(date?)	'YYYY-MM' 等	number	传参正常（'2023-02' → 28、'2024-02' → 29）；⚠️ 无参恒返回 31
getYearofDays(year?)	number | string	number	正常：闰年 366、平年 365；省略参数回退今年
getYearLastDays()	无	number	按当前时刻到年底 23:59:59 取整（下午调用会比 v2 的"不含今天"少 1）

已知缺陷（1.0.1 实测）

1. format() 无参调用抛 TypeError —— 需要默认格式请显式传 format('YYYY-MM-DD hh:ii:ss')。
2. 同一 Token 出现两次时替换错乱 —— 每个模板 Token 只替换第一次，第二次起会与其它 Token 交叠出乱码（实测 format('YYYY-MM-DD YYYY-MM-DD') → '2026-10-25 二零二六YYY-一零M-二五D'）。
3. getDays() 无参恒返回 31 —— 实现以 new Date(null)（1970-01-01）为基准， 并非"本月天数"。
4. 单参偏移字符串不生效 —— format('-7') 原样返回 '-7'，偏移必须写在双参形式里。
5. <script> 引入直接挂全局 —— 无命名空间，format 等高频命名污染 window。

以上问题在 v2 中均已修复。

与 v2 的行为差异

差异点	v1（1.0.x）	v2（2.0.x）
format() 无参	抛 TypeError	返回默认模板的当前时间
两位年	yy（小写）	YY（大写）
不补零月 / 日	mm / dd	无对应 Token
中文月 M	逐位（10 → 一零）	按数值（10 → 十）
中文日 D	逐位（25 → 二五）	按数值（25 → 二十五）
时段 a	上午 / 下午（>12 分界）	凌晨 / 早上 / 上午 / 中午 / 下午 / 晚上
重复 Token	替换错乱	正常（全部替换）
getDays() 无参	恒 31	本月天数
打包	UMD（<script> 可用）	ESM + CJS，无 UMD
TypeScript 类型	无	自带 .d.ts
命名空间 / Builder	无	datefmt + DateFmt