@iefe/dateformat v2
v2 是框架无关的轻量日期工具：完全兼容旧版 format 调用约定（老代码无需改动即可迁移）， 并按功能提供五组 API——格式化（含中文大写日期）、解析与校验（iOS 兼容）、相对时间与差值、 日期比较、年月信息。另提供 datefmt 冻结命名空间与不可变建造者，避免 format 等高频命名 与业务代码冲突（变量污染）。零框架依赖、可 tree-shaking、自带 TypeScript 类型。
一分钟上手
js
import { format, formatDate, fromNow, diff, isToday, datefmt, getDays } from '@iefe/dateformat'
// 假设当前时间 2023-03-10 15:00:00（星期五）
format() // '2023-03-10 15:00:00'
format('-7', 'YYYY-MM-DD') // '2023-03-03'
format('Y年M月D日') // '二零二三年三月十日'
formatDate('2024-02-29') // '2024-02-29 00:00:00'（格式化任意日期）
fromNow('2023-03-10 14:30') // '30 分钟前'
diff('2024-03-01', '2024-01-01') // 60（天）
isToday('2023-03-10 23:59') // true
// 命名空间 + 不可变 Builder（新代码推荐）
datefmt.create('YYYY-MM-DD hh:ii:ss').offset(-7).render() // '2023-03-03 15:00:00'
// 年月信息
getDays('2023-02') // 28功能分类总览
| 分类 | API | 一句话说明 |
|---|---|---|
| 格式化 | format | 旧版调用约定（偏移字符串 + 模板），完全兼容 |
formatDate | 格式化任意日期（字符串或 Date，不限"今天 ± N 天"） | |
| 解析与校验 | parseDate | 日期字符串 → Date（iOS Safari 兼容 + 回写校验） |
isValid | 输入是否为可解析的合法日期 | |
| 相对时间与差值 | fromNow | '3 分钟前' / '2 天后' 中文相对时间 |
diff | 两日期差值 a - b，支持 7 种单位 | |
| 日期比较 | isToday / isSameDay | 日粒度判断（忽略时分秒） |
isBefore / isAfter | 时刻粒度比较（精确到毫秒） | |
| 年月信息 | getDays / getYearofDays / getYearLastDays | 年月天数与年度进度查询 |
isLeapYear | 是否闰年 | |
| 调用方式 | datefmt / DateFmt | 冻结命名空间 + 不可变链式建造者 |
所有 API 既可具名导出调用，也可通过 datefmt 命名空间调用，行为完全一致； 全部纯函数、非法入参不抛错。
v2 的核心能力
| 能力 | 说明 |
|---|---|
兼容旧版 format 约定 | 偏移字符串 + 模板的调用方式与 v1 逐字一致 |
| 中文大写日期 | Y/M/D 输出中文数字，a 输出时段，EEE/EE 输出星期 |
| 格式化任意日期 | formatDate 接受字符串或 Date，补齐"今天 ± N 天"之外的场景 |
| iOS 兼容解析与校验 | parseDate / isValid 组件式构造 + 回写校验，Safari 不再 Invalid Date |
| 相对时间与差值 | fromNow 中文口语描述、diff 支持 7 种单位（含日历月/年差） |
| 日期比较 | isToday / isSameDay 日粒度，isBefore / isAfter 时刻粒度 |
| 年月信息 | getDays / getYearofDays / getYearLastDays / isLeapYear |
datefmt 冻结命名空间 | Object.freeze，运行时改写抛 TypeError，导入零污染 |
| 不可变 Builder | DateFmt 链式 pattern/offset/base，每步返回新实例 |
| 工程友好 | 零依赖、sideEffects: false、TS 类型、ESM + CJS 双产物 |
与 v1 的主要差异
| 差异点 | v1（1.0.1） | v2（2.1.0） |
|---|---|---|
| 打包产物 | UMD 单文件（~2KB） | ESM + CJS（tsup），不再提供 UMD |
| 两位年 Token | yy（小写） | YY（大写） |
| 不补零月 / 日 | mm / dd | 无对应 Token（H/i/s 提供不补零时分秒） |
| 中文月 / 日规则 | 逐位转换（10 月 → 一〇、21 日 → 二一） | 按数值转换（10 月 → 十、21 日 → 二十一） |
时段 a | 仅 上午 / 下午 | 凌晨 / 早上 / 上午 / 中午 / 下午 / 晚上 |
| API 范围 | format + 三个辅助方法 | 五组功能 15 个函数（见上方功能分类总览） |
| 命名空间 / Builder | 无 | datefmt + DateFmt |
| TypeScript 类型 | 无 | 自带 .d.ts |
TIP
调用约定兼容 + Token 行为增强：老代码的 format(...) 结果与 v1 一致； 只有 v1 中依赖 mm/dd/yy 这三个 Token 的模板需要按上表调整。