@iefe/dateformat 2.0.1

2.0.1 是 v2 的首个修复版：完全兼容旧版 format 调用约定（老代码无需改动即可迁移）， 提供格式化（含中文大写日期）与三个年月信息辅助方法；另提供 datefmt 冻结命名空间与 不可变建造者，避免 format 等高频命名与业务代码冲突（变量污染）。 零框架依赖、可 tree-shaking、自带 TypeScript 类型。

TIP

本版本已冻结存档。最新版 2.1.0 新增了 formatDate（格式化任意日期）、 parseDate / isValid（iOS 兼容解析校验）、fromNow / diff（相对时间与差值）、 isToday 等四个比较函数、isLeapYear，以及 SSS / Q / DDD / ww / x / X 六个扩展 Token 和 [方括号] 字面量转义——见 2.1.0 文档。

一分钟上手

import { format, getDays, getYearofDays, getYearLastDays, datefmt } from '@iefe/dateformat'

// 假设当前时间 2023-03-10 15:00:00（星期五）
format()                    // '2023-03-10 15:00:00'（默认模板）
format('-7', 'YYYY-MM-DD')  // '2023-03-03'（偏移 7 天前）
format('Y年M月D日')         // '二零二三年三月十日'（中文大写）

// 年月信息
getDays('2023-02')          // 28
getYearofDays(2024)         // 366（闰年）
getYearLastDays()           // 296（今年剩余，不含今天）

// 命名空间 + 不可变 Builder（新代码推荐）
datefmt.create('YYYY-MM-DD hh:ii:ss').offset(-7).render()  // '2023-03-03 15:00:00'

功能总览

分类	API	一句话说明
格式化	format	旧版调用约定（偏移字符串 + 模板），完全兼容
年月信息	getDays	指定年月的天数（28/29/30/31）
	getYearofDays	指定年份总天数（365/366）
	getYearLastDays	今年剩余天数（不含今天）
调用方式	datefmt / DateFmt	冻结命名空间 + 不可变链式建造者

所有 API 既可具名导出调用，也可通过 datefmt 命名空间调用，行为完全一致； 全部纯函数、非法入参不抛错（回退默认值）。

核心能力

能力	说明
兼容旧版 format 约定	偏移字符串 + 模板的调用方式与 v1 逐字一致
中文大写日期	Y/M/D 输出中文数字，a 输出时段，EEE/EE 输出星期
年月信息	getDays / getYearofDays / getYearLastDays
datefmt 冻结命名空间	Object.freeze，运行时改写抛 TypeError，导入零污染
不可变 Builder	DateFmt 链式 pattern/offset/base，每步返回新实例
工程友好	零依赖、sideEffects: false、TS 类型、ESM + CJS 双产物

与 v1 的主要差异

差异点	v1（1.0.x）	2.0.1
打包产物	UMD 单文件（~2KB）	ESM + CJS（tsup），不再提供 UMD
两位年 Token	yy（小写）	YY（大写）
不补零月 / 日	mm / dd	无对应 Token（H/i/s 提供不补零时分秒）
中文月 / 日规则	逐位转换（10 月 → 一〇、21 日 → 二一）	按数值转换（10 月 → 十、21 日 → 二十一）
时段 a	仅 上午 / 下午	凌晨 / 早上 / 上午 / 中午 / 下午 / 晚上
API 范围	format + 三个辅助方法	format + 三个辅助方法（修复 v1 缺陷）
命名空间 / Builder	无	datefmt + DateFmt
TypeScript 类型	无	自带 .d.ts

TIP

调用约定兼容 + Token 行为增强：老代码的 format(...) 结果与 v1 一致； 只有 v1 中依赖 mm/dd/yy 这三个 Token 的模板需要按上表调整。

接下来

• 快速开始 — 安装、格式化与年月信息上手、框架中使用
• 格式化 Token — 完整 Token 表、中文数字规则与固定文案处理
• API 参考 — 全部函数、Builder 与类型定义