API 参考

功能总览

本版本共 4 个函数 + 2 种调用方式，均为纯函数、非法入参回退默认值而非抛异常、 sideEffects: false 可 tree-shaking：

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

所有函数既可具名导出调用，也可通过 datefmt 命名空间调用（如 datefmt.getDays），行为完全一致。

---

一、格式化

format(a?, b?)

格式化日期时间，完全兼容旧工具调用约定。

参数	类型	说明
a	string（可选）	偏移字符串或格式化模板
b	string（可选）	格式化模板（与 a 同时传入时，a 只按偏移解析）

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

调用形式：

调用	语义
format()	当前时间，默认模板 'YYYY-MM-DD hh:ii:ss'
format(pattern)	当前时间按模板格式化
format(offset, pattern)	相对今天偏移 N 天后按模板格式化

偏移字符串规则：/^\s*[+-]?\d+\s*$/，如 '-7'、'0'、'+3'、' -7 '； 仅平移日期、保留当天时分秒。非法输入不抛错：无法识别的参数按模板处理。

完整 Token 表见格式化 Token。本版本共 16 个基础 Token， 不含毫秒 / 季度 / 周数 / 时间戳等扩展 Token，也不支持 [方括号] 转义。

---

二、年月信息

函数	参数	返回	说明
getYearLastDays()	无	number	今年剩余天数（不含今天；今天 12-31 时返回 0）
getYearofDays(year?)	number | string	number	指定年份总天数（闰年 366，平年 365）；省略或非法时回退今年
getDays(date?)	string | Date	number	指定年月的天数；支持 'YYYY-MM'、'YYYY-MM-DD' 及斜杠变体与 Date，只取年月；省略或非法时回退本月

三个方法均不抛错：无参时一律以"今天"为基准；非法入参回退默认值。

getYearLastDays()

今年剩余天数（不含今天）。即"今年 12 月 31 日零点"与"今天零点"的日序号差：

// 假设今天是 2023-03-10
getYearLastDays()                     // 296
getYearofDays() - getYearLastDays()   // 69（今年已过去）

getYearofDays(year?)

指定年份的总天数（365 / 366）。year 支持 number（如 2024）或纯数字字符串（如 '2024'）：

// 假设今年是 2023
getYearofDays()        // 365
getYearofDays('2022')  // 365
getYearofDays(2024)    // 366
getYearofDays('abc')   // 365（回退今年，不抛错）

getDays(date?)

指定日期所在月份的天数（28 / 29 / 30 / 31）。date 支持 'YYYY-MM'、'YYYY-MM-DD'、'YYYY/MM'、'YYYY/MM/DD' 与 Date 对象，只取年月、忽略日部分：

// 假设本月是 2023-03
getDays()              // 31（本月）
getDays('2023-02')     // 28
getDays('2024-02-15')  // 29（只取年月）
getDays('2023/02')     // 28（斜杠兼容）
getDays('abc')         // 31（回退本月，不抛错）

TIP

本版本没有 isLeapYear，判断闰年可用 getYearofDays(year) === 366。

---

datefmt 命名空间（Facade）

import { datefmt } from '@iefe/dateformat'

本版本全部函数都收拢在 datefmt 上，与具名导出同源同行为：

成员	说明
datefmt.format(a?, b?)	同 format
datefmt.getDays(date?)	同 getDays
datefmt.getYearofDays(year?)	同 getYearofDays
datefmt.getYearLastDays()	同 getYearLastDays
datefmt.create(pattern?)	创建不可变建造者 DateFmt

datefmt.format('-7', 'YYYY-MM-DD')   // '2023-03-03'
datefmt.getDays('2024-02')           // 29

datefmt 经 Object.freeze 冻结：运行时（ESM 恒为严格模式）改写任何属性都会抛 TypeError，杜绝被下游挂载/篡改。

DateFmt 建造者（Builder）

不可变实现：所有配置存于私有快照，链式方法每步返回新实例，实例间无状态串扰。

declare class DateFmt {
  static create(pattern?: string): DateFmt
  pattern(pattern: string): DateFmt
  offset(days: number | string): DateFmt
  base(date?: Date): DateFmt
  render(): string
  toString(): string
}

方法	说明
DateFmt.create(pattern?)	工厂方法；pattern 默认 'YYYY-MM-DD hh:ii:ss'
.pattern(pattern)	换模板，返回新实例
.offset(days)	偏移天数（可叠加：.offset(-7).offset('+3') 净偏移 -4）；仅平移日期、保留时分秒；非法参数忽略不抛错
.base(date?)	注入基准时间；本版本格式化"非今天"日期的唯一途径；非法值回退当前时间
.render()	产出字符串；延迟求值，调用时才读系统时间
.toString()	render() 的别名，可用于模板字符串 `${builder}`

// 假设当前时间 2023-03-10 15:00:00
datefmt.create('YYYY-MM-DD hh:ii:ss').offset(-7).render()
// '2023-03-03 15:00:00'

// 格式化给定日期（本版本无 formatDate）
datefmt.create('YYYY-MM-DD').base(new Date(2024, 1, 29)).render()
// '2024-02-29'

公共类型

/** 年份入参：支持数字或纯数字字符串（如 2024 / '2024'） */
type YearInput = number | string

/** 日期入参：支持 'YYYY-MM'、'YYYY-MM-DD' 及斜杠变体（允许带时间部分）或 Date 对象 */
type DateInput = string | Date

错误处理约定

本库为纯函数风格，公开 API 不抛异常：非法入参一律回退默认值 （当前时间 / 本月 / 今年），保证总有返回值。

唯一会抛错的是对 datefmt 冻结命名空间的改写（TypeError）。

模块产物

产物	路径	说明
ESM	dist/index.js	import 引入
CJS	dist/index.cjs	require 引入
类型	dist/index.d.ts	TypeScript

sideEffects: false，支持 tree-shaking；无 UMD 产物。

---

TIP

2.1.0 新增 formatDate、parseDate / isValid、fromNow / diff、 isToday 等比较函数、isLeapYear 与六个扩展 Token，见 2.1.0 API 参考。