快速开始

安装

历史版本请固定版本号安装：

npm install @iefe/dateformat@2.0.1
# 或
yarn add @iefe/dateformat@2.0.1
# 或
pnpm add @iefe/dateformat@2.0.1

引入

ESM：

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

CommonJS：

const { format, getDays, getYearofDays, datefmt } = require('@iefe/dateformat')

浏览器（本版本起无 UMD 产物，请通过 ESM CDN 或打包工具）：

<script type="module">
  import { format, getDays } from 'https://unpkg.com/@iefe/dateformat@2.0.1/dist/index.js'

  console.log(format())        // 当前时间 'YYYY-MM-DD hh:ii:ss'
  console.log(getDays('2023-02')) // 28
</script>

格式化：format 的三种调用形式

// 假设当前时间 2023-03-10 15:00:00（星期五）
format()                          // '2023-03-10 15:00:00'（默认模板）
format('YYYY-MM-DD')              // '2023-03-10'（单参数视为模板）
format('-7', 'YYYY-MM-DD')        // '2023-03-03'（偏移 + 模板）
format(' +3 ', 'MM-DD')           // '03-13'（偏移字符串允许空格）
format('YYYY-MM-01')              // '2023-03-01'（模板中的固定字符原样保留）

非法输入不抛错：无法识别的参数按模板处理，模板中的非 Token 字符原样保留。

格式化"非今天"的日期

format 的基准恒为"今天 ± N 天"。要格式化一个给定的日期（如后端返回值）， 本版本请借助 Builder 的 .base() 注入基准：

import { datefmt } from '@iefe/dateformat'

// 2024 年 2 月 29 日（注意 Date 构造器的月份是 0 基）
datefmt.create('YYYY-MM-DD').base(new Date(2024, 1, 29)).render()  // '2024-02-29'

datefmt.create('Y年M月D日').base(new Date(2023, 2, 10)).render()   // '二零二三年三月十日'

TIP

2.1.0 起提供更直接的 formatDate('2024-02-29')， 支持日期字符串入参，无需手工构造 Date。

年月信息

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

// 假设今天是 2023-03-10（平年）
getDays()                            // 31（本月）
getDays('2023-02')                   // 28
getDays('2024-02')                   // 29
getYearofDays()                      // 365
getYearofDays(2024)                  // 366
getYearLastDays()                    // 296（今年剩余，不含今天）
getYearofDays() - getYearLastDays()  // 69（今年已过去）

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

TIP

本版本没有独立的 isLeapYear，判断闰年可用 getYearofDays(year) === 366； 2.1.0 起提供 isLeapYear(year)。

命名空间与 Builder（避免变量污染）

format、getDays 是前端最高频的命名之一，按名导入容易与业务代码或 date-fns 等库的同名导出冲突。本版本提供两种零污染用法：

1. 命名空间门面 — 只导入一个标识符

import { datefmt } from '@iefe/dateformat'

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

datefmt 经 Object.freeze 冻结，运行时改写或挂载任何属性都会抛 TypeError。 全部函数都收拢在 datefmt 上，与具名导出同源同行为。

2. 不可变建造者 — 链式配置，无共享可变状态

datefmt.create('YYYY-MM-DD hh:ii:ss') // 工厂方法：以模板创建建造者
  .offset(-7)                         // 偏移 -7 天（可叠加）
  .render()                           // '2023-03-03 15:00:00'

// 每一步都返回新实例，原实例与兄弟实例互不影响：
const today = datefmt.create('YYYY-MM-DD')
const lastWeek = today.offset(-7) // 新实例 → '2023-03-03'
const nextWeek = today.offset(7)  // 新实例 → '2023-03-17'
today.render()                    // '2023-03-10'（原实例未被修改）

• pattern / offset / base 均返回新实例；offset 支持叠加（.offset(-7).offset('+3') 净偏移 -4）
• 非法参数（如 .offset('abc')）忽略不抛错
• render() 延迟求值（调用时才读系统时间），toString() 等价，可直接用于模板字符串 `${builder}`

在框架中使用

Vue 3

<script setup lang="ts">
import { ref } from 'vue'
import { format, getDays, datefmt } from '@iefe/dateformat'

const today = ref(format('YYYY年MM月DD日 a'))
const week = ref(format('今天EE'))
const monthDays = getDays()
const createdAt = datefmt.create('YYYY-MM-DD hh:ii').base(new Date(2024, 0, 1, 9, 30)).render()
</script>

<template>
  <p>{{ today }}（{{ week }}），本月共 {{ monthDays }} 天</p>
  <p>创建于 {{ createdAt }}</p>
</template>

React 18

import { useMemo } from 'react'
import { format, getDays, getYearLastDays } from '@iefe/dateformat'

export function Today() {
  const text = useMemo(() => format('YYYY年MM月DD日 a'), [])
  return (
    <p>
      {text}，本月共 {getDays()} 天，今年还剩 {getYearLastDays()} 天
    </p>
  )
}

已知限制

• hh 是 24 小时制、ii 是分钟 — 与 dayjs/moment 的 HH/mm 语义不同，迁移时注意。
• 本版本不支持 [方括号] 字面量转义 — 模板中的独立字母 a、i、s、H、Y、M、D 都是 Token 会被替换（如模板 'abc' 中的 a 会变成时段），固定文案需拆分模板或字符串拼接 （见格式化 Token）；2.1.0 起支持 [方括号] 转义。
• 没有 formatDate / parseDate / isValid / fromNow / diff / isToday 等比较函数 / isLeapYear——这些在 2.1.0 中提供；本版本格式化任意日期用 Builder 的 .base()。
• 仅使用运行环境本地时区，不做时区转换。
• getDays 只取年月、忽略日部分（'2024-02-31' 也返回 29）；月份越界的输入回退本月。
• 偏移字符串仅平移日期、保留当天时分秒。
• 自迁移到 tsup 后不再提供 UMD 产物；浏览器请通过 ESM（<script type="module"> + CDN）或打包工具使用。