时间工具 API

提供标准命名导出 format 与 getTimestamp，同时扩展 UTC/时区/毫秒/秒级时间戳等常用方法。

使用指引（做什么、何时用）

• 显示时间：format(seconds) → 页面上以 YYYY-MM-DD HH:mm:ss 展示
• 接口字段：nowSeconds() / getUnixTimestamp() → 与后端 Unix 秒对齐
• 倒计时展示：formatDuration(ms) → HH:mm:ss 或 Xd HH:mm:ss
• 相对时间：relativeTime(from,to) → 2m ago / in 1h，用于消息/动态流
• 当日起止：startOfDay/endOfDay → 计算本地时区当天区间，配合活动/统计
• 天数偏移：addDays(seconds,n) → 从某一天向后/前推算目标日期
• 固定时刻：setTimeOfDay(seconds,h,m,s) → 把任意秒设到某个时刻（本地时区）
• 简化目标：nextAt(offsetDays,h,m=0,s=0) → 今天起第 offsetDays 天的 h:m:s

JS 速用

import { format, getTimestamp, nowSeconds, formatDuration, startOfDay, addDays, relativeTime, setTimeOfDay, nextAt } from 'nex-lib'
format()                                 // 当前格式化
getTimestamp(0)                          // 1970-01-01 毫秒
relativeTime(nowSeconds()-120, nowSeconds())
formatDuration(3700000)
const target = nextAt(3, 18)             // 三天后的 18:00（本地时区）
setTimeOfDay(startOfDay(nowSeconds()), 9, 30) // 今天 09:30:00

Output

2m ago
01:01:40

setTimeOfDay(seconds: number, hour: number, minute?: number, second?: number): number

• 功能：将任意秒时间戳设置到指定时刻（本地时区）

Example

import { setTimeOfDay, startOfDay } from 'nex-lib'
setTimeOfDay(startOfDay(), 18, 0, 0) // 今天 18:00

nextAt(offsetDays: number, hour: number, minute?: number, second?: number): number

• 功能：从今天起偏移 offsetDays 天后的指定时刻（本地时区）

Example

import { nextAt } from 'nex-lib'
nextAt(3, 18) // 三天后 18:00

导入

import { format, getTimestamp } from 'nex-lib';

format(seconds?: number): string

• 功能：格式化为 YYYY-MM-DD HH:mm:ss
• 参数：seconds（可选，单位秒）
• 返回：格式化后的字符串

Example

import { format } from 'nex-lib'
format(0)

Output

1970-01-01 00:00:00

format();            // 当前时间
format(1633072800);  // 指定秒数

getTimestamp(seconds?: number): number

• 功能：返回毫秒时间戳
• 参数：seconds（可选，单位秒）
• 返回：毫秒数

Example

import { getTimestamp } from 'nex-lib'
getTimestamp(0)

Output

0

getTimestamp();            // 当前毫秒时间戳
getTimestamp(1633072800);  // 指定秒数对应的毫秒

formatUTC(seconds?: number): string

• 功能：按 UTC 时区格式化 YYYY-MM-DD HH:mm:ss

formatUTC();       // 当前时间（UTC）
formatUTC(0);      // '1970-01-01 00:00:00'

Example

import { formatUTC } from 'nex-lib'
formatUTC(0)

Output

1970-01-01 00:00:00

getTimezone(): string

• 功能：获取当前 IANA 时区标识，例如 Asia/Shanghai

Example

import { getTimezone } from 'nex-lib'
getTimezone()

Output

Asia/Shanghai // 示例，实际取决于运行环境

nowMs(): number

• 功能：当前毫秒时间戳（与 getTimestamp() 等价，更具语义）

Example

import { nowMs } from 'nex-lib'
nowMs()

Output

1760000000000 // 示例值，实时变化

nowSeconds(): number

• 功能：当前秒级时间戳（Unix 秒），常用于与后端接口对齐

Example

import { nowSeconds } from 'nex-lib'
nowSeconds()

Output

1760000000 // 示例值，实时变化

getUnixTimestamp(seconds?: number): number

• 功能：返回 Unix 秒级时间戳；若传入 seconds 则直接返回该值（取整）

Example

import { getUnixTimestamp } from 'nex-lib'
getUnixTimestamp(123.9)

Output

123

getTimezoneOffsetMinutes(): number

• 功能：获取本地到 UTC 的分钟偏移（正负值），例如东八区为 -480

Example

import { getTimezoneOffsetMinutes } from 'nex-lib'
getTimezoneOffsetMinutes()

Output

-480 // Asia/Shanghai 示例

getISO8601(seconds?: number): string

• 功能：返回 ISO 8601 字符串，如 2025-01-01T08:00:00.000Z

Example

import { getISO8601 } from 'nex-lib'
getISO8601(0)

Output

1970-01-01T00:00:00.000Z

relativeTime(fromSeconds: number, toSeconds?: number): string

• 功能：返回相对时间（英语），如 3d ago / in 2h

Example

import { relativeTime, nowSeconds } from 'nex-lib'
const now = nowSeconds()
relativeTime(now - 120, now)
relativeTime(now + 3600, now)

Output

2m ago
in 1h

formatDuration(ms: number): string

• 功能：格式化时长，返回 HH:mm:ss 或 Xd HH:mm:ss

Example

import { formatDuration } from 'nex-lib'
formatDuration(65000)
formatDuration(3700000)
formatDuration(90000000)

Output

00:01:05
01:01:40
1d 01:00:00

addDays(seconds: number, n: number): number

• 功能：指定时间（秒）向后/前偏移 n 天，返回偏移后的秒级时间戳

startOfDay(seconds?: number): number

• 功能：返回本地时区的该日起始秒（00:00:00）

endOfDay(seconds?: number): number

• 功能：返回本地时区的该日结束秒（23:59:59）