格式化 Token

模板是普通字符串：Token 被替换为对应的日期部分，其余字符原样保留 （如 format('YYYY-MM-01') → '2023-03-01'，其中的 01 就是固定字符）。

Token 总表

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

Token	含义	示例输出
YYYY	四位年	2023
YY	两位年	23
Y	中文大写年（逐位）	二零二三
MM	两位月（补零）	03
M	中文月	三
DD	两位日（补零）	10
D	中文日	十
hh	两位时（24 小时制补零）	15
H	时（不补零，24 小时制）	15
ii	两位分（补零）	00
i	分（不补零）	0
ss	两位秒（补零）	00
s	秒（不补零）	0
a	时段	下午
EEE	星期全称	星期五
EE	星期简称	周五

WARNING

hh 是 24 小时制（不是 12 小时制），ii 是分钟（不是 mm）。 这与 dayjs / moment 风格相反，是为了兼容既有工具的调用约定，不要按常见库理解。

TIP

本版本共 16 个基础 Token。毫秒（SSS）、季度（Q）、年内天数（DDD）、 周数（ww）、时间戳（x / X）六个扩展 Token 与 [方括号] 转义在 2.1.0 中提供。

中文数字规则

• 年（Y） 逐位转换：2 0 2 3 → 二零二三（0零 1一 2二 3三 4四 5五 6六 7七 8八 9九）
• 月（M） 按数值转换：3 → 三、10 → 十、11 → 十一、12 → 十二
• 日（D） 按数值转换：10 → 十、20 → 二十、21 → 二十一、31 → 三十一
• M/D 只输出中文数字本身，"月 / 日"等文字来自模板——format('M月') → '三月'、format('D日') → '十日'

时段（a）划分

按 24 小时制的小时划分：

小时	时段
0 ~ 5	凌晨
6 ~ 8	早上
9 ~ 11	上午
12	中午
13 ~ 17	下午
18 ~ 23	晚上

星期（EEE / EE）

EEE → 星期日 / 星期一 / … / 星期六；EE → 周日 / 周一 / … / 周六。

固定文案的处理

模板里的独立字母 a、i、s、H、Y、M、D 都是 Token，会被替换—— 本版本不支持 [方括号] 转义，含这些字母的固定文案请拆分模板或用字符串拼接：

// 直接写 format('updated at a') 会把文案里的 a、t 前后的 Token 吃掉——错！
// 正确：文案与 Token 分开写
'updated at ' + format('a')     // 'updated at 下午'
format('[EE]')                  // '[周五]'（方括号是普通字符，无转义语义）

// 想输出字面量 'YYYY'，同样靠拼接：
'(YYYY) ' + format('MM-DD')     // '(YYYY) 03-10'

2.1.0 起支持 [方括号] 字面量转义：format('updated [at] a') → 'updated at 下午'， 见 2.1.0 格式化 Token。

组合示例

// 假设当前时间 2023-03-10 15:00:00（星期五）
format('YYYY-MM-DD hh:ii:ss')             // '2023-03-10 15:00:00'
format('YYYY年MM月DD日')                   // '2023年03月10日'
format('Y年M月D日')                        // '二零二三年三月十日'
format('hh:ii:ss a')                      // '15:00:00 下午'
format('今天EEE')                          // '今天星期五'
format('今天EE')                           // '今天周五'
format(' -7 ', 'Y年M月D日 YYYY/MM/DD a')   // '二零二三年三月三日 2023/03/03 下午'

注意事项

• Token 匹配按长度从长到短进行（EEE 先于 EE，YYYY 先于 YY），不会出现短 Token 吃掉长 Token 的情况。
• 模板中的独立字母都是 Token（见上）——固定文案用拼接处理。
• 与 v1 的 Token 行为差异（yy/mm/dd、中文逐位转换、时段档位）见 v1.0.1 API 参考 → 与 v2 的行为差异。