@caolib/time-util

一个轻量级的JavaScript日期时间工具库，提供简单易用的日期格式化、相对时间计算等功能。

特性

• 🚀 零依赖，轻量级
• 📦 支持ES模块和CommonJS
• 🎯 简单易用的API
• 🌍 中文友好的相对时间描述
• ⚡ 高性能日期处理

安装

npm install @caolib/time-util

快速开始

ES模块

import { formatDate, getCurrentDate } from '@caolib/time-util';

// 或者使用默认导入
import timeUtil from '@caolib/time-util';

CommonJS

const { formatDate, getCurrentDate } = require('@caolib/time-util');

API文档

formatDate(input)

格式化时间戳或日期字符串为相对时间或绝对时间。

参数

• input {number|string} - 时间戳（毫秒）或日期字符串

返回值

• {string} 格式化后的时间字符串

示例

formatDate(Date.now() - 60000); // "1分钟前"
formatDate('2023-10-26'); // "2023-10-26"（如果超过一个月）
formatDate('2023-01-01T12:00:00'); // "2023-01-01 12:00:00"

getCurrentDate()

获取当前日期，格式为 YYYY.MM.DD。

返回值

• {string} 当前日期字符串

示例

getCurrentDate(); // "2024.05.12"

formatDateCustom(date, format)

自定义格式化日期。

参数

• date {Date|string|number} - 日期对象、日期字符串或时间戳
• format {string} - 格式字符串，默认为 'yyyy-MM-dd HH:mm:ss'

返回值

• {string} 格式化后的日期字符串

示例

formatDateCustom(new Date(), 'yyyy年MM月dd日'); // "2024年05月12日"
formatDateCustom('2023-10-26', 'MM/dd/yyyy'); // "10/26/2023"

getRelativeTime(start, end)

获取两个日期之间的相对时间描述。

参数

• start {Date|string|number} - 开始日期
• end {Date|string|number} - 结束日期（默认为当前时间）

返回值

• {string} 相对时间描述

示例

getRelativeTime('2023-01-01', '2024-01-01'); // "1年"
getRelativeTime(Date.now() - 3600000); // "1小时"

isToday(date)

检查日期是否为今天。

参数

• date {Date|string|number} - 要检查的日期

返回值

• {boolean} 是否为今天

示例

isToday(new Date()); // true
isToday('2023-10-26'); // false

getDaysInMonth(year, month)

获取指定月份的天数。

参数

• year {number} - 年份
• month {number} - 月份（1-12）

返回值

• {number} 该月的天数

示例

getDaysInMonth(2024, 2); // 29（2024年是闰年）
getDaysInMonth(2023, 11); // 30

getTimestamp(date)

获取时间戳（毫秒）。

参数

• date {Date|string|number} - 日期对象、日期字符串或时间戳（默认为当前时间）

返回值

• {number} 时间戳（毫秒）

示例

getTimestamp(); // 当前时间戳
getTimestamp('2023-10-26'); // 指定日期的时间戳

使用示例

基本使用

import { 
    formatDate, 
    getCurrentDate, 
    formatDateCustom, 
    getRelativeTime 
} from '@caolib/time-util';

// 格式化相对时间
console.log(formatDate(Date.now() - 5 * 60 * 1000)); // "5分钟前"

// 获取当前日期
console.log(getCurrentDate()); // "2024.05.12"

// 自定义格式化
console.log(formatDateCustom(new Date(), 'yyyy-MM-dd HH:mm')); // "2024-05-12 15:30"

// 计算相对时间
console.log(getRelativeTime('2023-01-01', new Date())); // "1年"

高级用法

import { 
    isToday, 
    getDaysInMonth, 
    getTimestamp 
} from '@caolib/time-util';

// 检查是否为今天
if (isToday('2024-05-12')) {
    console.log('就是今天！');
}

// 获取某月天数
const daysInFeb = getDaysInMonth(2024, 2); // 29

// 获取时间戳
const timestamp = getTimestamp('2024-05-12 15:30:00');

TypeScript支持

本库包含完整的TypeScript类型定义，无需额外安装类型包。

浏览器兼容性

• Chrome 61+
• Firefox 60+
• Safari 10.1+
• Edge 16+

Node.js兼容性

• Node.js 14.0.0+

许可证

MIT License

贡献

欢迎提交Issue和Pull Request！

更新日志

v1.0.0

• ✨ 初始版本发布
• 🎉 支持日期格式化、相对时间计算、自定义格式等功能
• 📦 支持ES模块和CommonJS
• 🚀 零依赖，轻量级