格式化 Token

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

Token 总表

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

基础 Token

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	星期简称	周五

扩展 Token

Token	含义	示例输出	说明
SSS	三位毫秒（补零）	007 / 123
Q	季度	1 ~ 4	3 月 → 1，12 月 → 4
DDD	年内第几天（三位补零）	069	3 月 10 日（平年）= 31 + 28 + 10
ww	ISO 8601 年内周数（两位补零）	10	周一为一周开始，含当年首个周四的周为第 1 周；跨年边界周序号可能属于相邻年份（如 2023-01-01 → 52）
x	Unix 时间戳（毫秒）	1678431600000	不受时区影响
X	Unix 时间戳（秒）	1678431600	不受时区影响

WARNING

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

中文数字规则

• 年（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、Q、x、X、Y、M、D 都是 Token，会被替换。 模板中的固定文案请用 [方括号] 转义——方括号内的内容不作为 Token，脱去括号原样输出：

format('[abc]')        // 'abc'（而非 '上午bc'）
format('off[s]et[-7]') // 'offset-7'（s 与 -7 都不再被当作 Token）
format('[今天是]EE')    // '今天是周五'
format('[YYYY]年')     // 'YYYY年'（想输出字面量 YYYY 的话）
formatDate('2023-03-10', '[第]Q季度 DDD')  // '第1季度 069'

未闭合的方括号（如 '[EE'）不转义，维持原行为：括号原样保留、内部 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 的情况。
• 模板中的独立字母 a、i、s、H、Q、x、X、Y、M、D 都是 Token，会被替换——固定文案请用 [方括号] 转义。
• ww 为 ISO 8601 周数：年末/年初的周序号可能属于相邻年份（2023-01-01 → 52、2024-12-30 → 01），与同一模板中 YYYY 的年份可能相差 1。
• 与 v1 的 Token 行为差异（yy/mm/dd、中文逐位转换、时段档位）见 v1 API 参考 → 与 v2 的行为差异。