Date

基于 dayjs 的分层日期工具集，按操作意图分为格式化、运算、边界、比较四个职责层

概述

@skyroc/utils 的日期模块基于 dayjs，注册了 duration 和 relativeTime 插件，对外暴露一组语义明确的命名函数。

所有函数均接受 DateInput 类型作为输入：

type DateInput = string | number | Date | dayjs.Dayjs | null | undefined;

架构

函数按操作意图分文件，不按功能数量分。判断依据是：

调用者拿到结果后，要用它做什么？

dayjs.ts        # 基础层：dayjs 实例 + 插件注册（duration / relativeTime）
constants.ts    # 基础层：DATE_FORMAT 常量 + DateInput 类型
    ↑               ↑
format.ts       # 能力层：格式化（返回 string，给人看）
calc.ts         # 能力层：运算（返回 Dayjs / number，给程序算）
boundary.ts     # 能力层：边界（返回 Dayjs / [Dayjs, Dayjs]，表示时间区间）
compare.ts      # 能力层：比较（返回 boolean，用于条件判断）
    ↑               ↑
index.ts        # 出口层：barrel export，不含任何逻辑

四个能力层互不依赖，只依赖基础层，可以按需单独引入。

DATE_FORMAT 常量

import { DATE_FORMAT } from '@skyroc/utils';

DATE_FORMAT.DATE           // 'YYYY-MM-DD'
DATE_FORMAT.DATE_TIME      // 'YYYY-MM-DD HH:mm:ss'
DATE_FORMAT.DATE_TIME_MINUTE // 'YYYY-MM-DD HH:mm'
DATE_FORMAT.TIME           // 'HH:mm:ss'
DATE_FORMAT.TIME_MINUTE    // 'HH:mm'
DATE_FORMAT.MONTH          // 'YYYY-MM'
DATE_FORMAT.YEAR           // 'YYYY'
DATE_FORMAT.DATE_CN        // 'YYYY年MM月DD日'
DATE_FORMAT.DATE_TIME_CN   // 'YYYY年MM月DD日 HH:mm:ss'

format — 格式化

返回 string，结果直接用于 UI 渲染

import {
  formatDate,
  formatDateTime,
  formatTime,
  fromTimestamp,
  formatDuration,
  humanizeDuration,
} from '@skyroc/utils';

`formatDate(date, format?)`

格式化为日期字符串，默认格式 YYYY-MM-DD。

formatDate(new Date());         // '2026-04-20'
formatDate('2026-1-5');         // '2026-01-05'
formatDate(null);               // ''
formatDate(new Date(), DATE_FORMAT.DATE_CN); // '2026年04月20日'

`formatDateTime(date, format?)`

格式化为日期时间字符串，默认格式 YYYY-MM-DD HH:mm:ss。

formatDateTime(new Date()); // '2026-04-20 14:30:00'

`formatTime(date, format?)`

格式化为时间字符串，默认格式 HH:mm:ss。

formatTime(new Date()); // '14:30:00'

`fromTimestamp(timestamp, format?)`

时间戳转日期字符串，自动识别秒级和毫秒级（< 10000000000 视为秒）。

fromTimestamp(1745000000);       // 秒级，自动转毫秒 → '2025-04-18 ...'
fromTimestamp(1745000000000);    // 毫秒级，直接使用

`formatDuration(milliseconds, format?)`

将毫秒数格式化为持续时长，默认格式 HH:mm:ss。

formatDuration(3661000); // '01:01:01'
formatDuration(90000, 'mm:ss'); // '01:30'

`humanizeDuration(milliseconds)`

将毫秒数转为人性化描述（依赖 relativeTime 插件的语言设置）。

humanizeDuration(86400000); // 'a day'（英文）/ '一天'（中文，需设置 locale）

calc — 运算

返回 Dayjs 或 number，结果用于后续计算

import {
  toTimestamp,
  toUnixTimestamp,
  addDate,
  subtractDate,
  diffDate,
  fromNow,
  toNow,
} from '@skyroc/utils';

`toTimestamp(date)` → `number`

转为毫秒级时间戳。

toTimestamp('2026-04-20'); // 1745000000000
toTimestamp(null);         // 0

`toUnixTimestamp(date)` → `number`

转为秒级 Unix 时间戳。

toUnixTimestamp('2026-04-20'); // 1745000000

`addDate(date, value, unit?)` → `Dayjs`

日期加法，默认单位 'day'。

addDate('2026-04-20', 7).format('YYYY-MM-DD'); // '2026-04-27'
addDate('2026-04-20', 1, 'month').format('YYYY-MM-DD'); // '2026-05-20'

`subtractDate(date, value, unit?)` → `Dayjs`

日期减法，参数同 addDate。

subtractDate('2026-04-20', 30, 'day').format('YYYY-MM-DD'); // '2026-03-21'

`diffDate(date1, date2, unit?)` → `number`

计算两个日期的差值，默认单位 'day'。

diffDate('2026-04-20', '2026-04-01'); // 19（天）
diffDate('2026-04-20', '2026-01-01', 'month'); // 3（月）

`fromNow(date, baseDate?)` → `string`

获取相对当前（或指定基准日期）的时间描述。

fromNow('2026-04-17'); // '3 days ago'
fromNow('2026-04-17', '2026-04-20'); // '3 days ago'

`toNow(date, baseDate?)` → `string`

获取到某个时间的相对描述。

toNow('2026-04-23'); // 'in 3 days'

boundary — 边界

返回 Dayjs 或 [Dayjs, Dayjs]，表示时间区间的起止点

import {
  startOfDay, endOfDay,
  startOfWeek, endOfWeek,
  startOfMonth, endOfMonth,
  startOfYear, endOfYear,
  getTodayRange,
  getYesterdayRange,
  getThisWeekRange,
  getThisMonthRange,
  getThisYearRange,
  getLastDaysRange,
} from '@skyroc/utils';

单点边界

函数	返回
`startOfDay(date)`	当天 00:00:00
`endOfDay(date)`	当天 23:59:59.999
`startOfWeek(date)`	当周第一天 00:00:00
`endOfWeek(date)`	当周最后一天 23:59:59.999
`startOfMonth(date)`	当月第一天 00:00:00
`endOfMonth(date)`	当月最后一天 23:59:59.999
`startOfYear(date)`	当年第一天 00:00:00
`endOfYear(date)`	当年最后一天 23:59:59.999

startOfDay('2026-04-20').format('HH:mm:ss'); // '00:00:00'
endOfDay('2026-04-20').format('HH:mm:ss');   // '23:59:59'

范围快捷函数

函数	返回
`getTodayRange()`	今天的 [start, end]
`getYesterdayRange()`	昨天的 [start, end]
`getThisWeekRange()`	本周的 [start, end]
`getThisMonthRange()`	本月的 [start, end]
`getThisYearRange()`	本年的 [start, end]
`getLastDaysRange(n)`	最近 n 天的 [start, end]（含今天）

const [start, end] = getThisMonthRange();
// 传给日期选择器的 defaultValue

// 查询最近 7 天的数据
const [from, to] = getLastDaysRange(7);
api.fetchLogs({
  startTime: toTimestamp(from),
  endTime: toTimestamp(to),
});

compare — 比较

返回 boolean，用于条件判断

import {
  isValidDate,
  isBefore,
  isAfter,
  isSame,
  isToday,
  isYesterday,
  isTomorrow,
} from '@skyroc/utils';

`isValidDate(date)` → `boolean`

判断是否为合法日期。

isValidDate('2026-04-20'); // true
isValidDate('not-a-date'); // false
isValidDate(null);         // false

`isBefore(date, compareDate)` → `boolean`

isBefore('2026-04-01', '2026-04-20'); // true

`isAfter(date, compareDate)` → `boolean`

isAfter('2026-04-20', '2026-04-01'); // true

`isSame(date1, date2, unit?)` → `boolean`

判断两个日期是否相同，可按 unit 精度比较。

isSame('2026-04-20 10:00', '2026-04-20 15:00');          // false（精确到毫秒）
isSame('2026-04-20 10:00', '2026-04-20 15:00', 'day');   // true（精度为天）

`isToday(date)` / `isYesterday(date)` / `isTomorrow(date)` → `boolean`

isToday(new Date());                          // true
isYesterday(subtractDate(new Date(), 1));     // true
isTomorrow(addDate(new Date(), 1));           // true

Date

On this page