@wanglei/fkit

现代化前端工具包 - 专注于时间处理的实用工具集

一个轻量级、类型安全的前端工具包，专注于提供高质量的时间处理功能。采用 TypeScript 编写，支持 ESM 和 CommonJS 模块格式。

✨ 特性

• 🚀 轻量级: 零依赖，体积小巧
• 📦 TypeScript: 完整的类型定义支持
• 🌍 国际化: 支持多语言相对时间显示
• 🔧 灵活: 支持多种日期格式和自定义格式
• ⚡ 高性能: 优化的算法实现
• 📱 现代化: 支持 ESM 和 CommonJS

📦 安装

# npm
npm install @wanglei/fkit

# yarn
yarn add @wanglei/fkit

# pnpm
pnpm add @wanglei/fkit

🚀 快速开始

import { formatDate, timeAgo, addTime } from '@wanglei/fkit';

// 格式化日期
const now = new Date();
console.log(formatDate(now, 'YYYY-MM-DD HH:mm:ss')); // 2024-01-15 14:30:45

// 相对时间
const oneHourAgo = new Date(Date.now() - 60 * 60 * 1000);
console.log(timeAgo(oneHourAgo)); // 1小时前

// 时间计算
const tomorrow = addTime(now, 1, 'day');
console.log(formatDate(tomorrow, 'YYYY-MM-DD')); // 2024-01-16

📖 API 文档

日期格式化

formatDate(date, format?, options?)

格式化日期为指定格式的字符串。

import { formatDate, FORMAT_PRESETS } from '@wanglei/fkit';

const date = new Date('2024-01-15 14:30:45.123');

// 基础格式化
formatDate(date); // '2024-01-15 14:30:45'
formatDate(date, 'YYYY-MM-DD'); // '2024-01-15'
formatDate(date, 'DD/MM/YYYY'); // '15/01/2024'

// 时间格式
formatDate(date, 'HH:mm:ss'); // '14:30:45'
formatDate(date, 'h:mm A'); // '2:30 PM'
formatDate(date, 'HH:mm:ss.SSS'); // '14:30:45.123'

// 使用预设格式
formatDate(date, FORMAT_PRESETS.CHINESE_DATE); // '2024年01月15日'
formatDate(date, FORMAT_PRESETS.US_DATE); // '01/15/2024'

支持的格式标记：

| 标记 | 描述 | 示例 | |------|------|------| | YYYY | 四位年份 | 2024 | | YY | 两位年份 | 24 | | MM | 两位月份 | 01-12 | | M | 月份 | 1-12 | | DD | 两位日期 | 01-31 | | D | 日期 | 1-31 | | HH | 24小时制小时 | 00-23 | | H | 24小时制小时 | 0-23 | | hh | 12小时制小时 | 01-12 | | h | 12小时制小时 | 1-12 | | mm | 分钟 | 00-59 | | m | 分钟 | 0-59 | | ss | 秒 | 00-59 | | s | 秒 | 0-59 | | SSS | 毫秒 | 000-999 | | A | 上午/下午 | AM/PM | | a | 上午/下午 | am/pm |

formatTimestamp(timestamp, format?, options?)

格式化时间戳。

const timestamp = Date.now();
formatTimestamp(timestamp, 'YYYY-MM-DD HH:mm:ss');

now(format?)

获取当前时间的格式化字符串。

now(); // '2024-01-15 14:30:45'
now('YYYY-MM-DD'); // '2024-01-15'

日期解析

parseDate(input)

解析各种格式的日期输入。

import { parseDate } from '@wanglei/fkit';

parseDate('2024-01-15'); // Date object
parseDate(1705312245000); // Date object
parseDate(new Date()); // Date object (copy)

parseDateString(str)

解析日期字符串。

parseDateString('2024-01-15'); // Date object
parseDateString('2024/01/15'); // Date object

日期验证

isValidDate(value)

检查值是否为有效的 Date 对象。

import { isValidDate } from '@wanglei/fkit';

isValidDate(new Date()); // true
isValidDate(new Date('invalid')); // false
isValidDate('2024-01-15'); // false

isLeapYear(year)

检查是否为闰年。

import { isLeapYear } from '@wanglei/fkit';

isLeapYear(2024); // true
isLeapYear(2023); // false

getDaysInMonth(year, month)

获取指定年月的天数。

import { getDaysInMonth } from '@wanglei/fkit';

getDaysInMonth(2024, 2); // 29 (闰年二月)
getDaysInMonth(2023, 2); // 28

时间计算

addTime(date, amount, unit)

在日期上添加指定时间。

import { addTime } from '@wanglei/fkit';

const date = new Date('2024-01-15');

addTime(date, 1, 'year'); // 2025-01-15
addTime(date, 1, 'month'); // 2024-02-15
addTime(date, 1, 'day'); // 2024-01-16
addTime(date, 1, 'hour'); // 2024-01-15 01:00:00

subtractTime(date, amount, unit)

从日期中减去指定时间。

import { subtractTime } from '@wanglei/fkit';

const date = new Date('2024-01-15');
subtractTime(date, 1, 'day'); // 2024-01-14

diffTime(date1, date2, unit?)

计算两个日期之间的时间差。

import { diffTime } from '@wanglei/fkit';

const date1 = new Date('2024-01-16');
const date2 = new Date('2024-01-15');

diffTime(date1, date2, 'day'); // 1
diffTime(date1, date2, 'hour'); // 24

相对时间

timeAgo(date, options?)

获取相对于当前时间的描述。

import { timeAgo } from '@wanglei/fkit';

const oneHourAgo = new Date(Date.now() - 60 * 60 * 1000);

timeAgo(oneHourAgo); // '1小时前'
timeAgo(oneHourAgo, { locale: 'en' }); // '1 hour ago'

timeUntil(date, options?)

获取距离指定时间的描述。

import { timeUntil } from '@wanglei/fkit';

const oneHourLater = new Date(Date.now() + 60 * 60 * 1000);

timeUntil(oneHourLater); // '1小时后'
timeUntil(oneHourLater, { locale: 'en' }); // 'in 1 hour'

日期比较

isSameDay(date1, date2)

检查两个日期是否为同一天。

import { isSameDay } from '@wanglei/fkit';

const date1 = new Date('2024-01-15 10:00:00');
const date2 = new Date('2024-01-15 20:00:00');

isSameDay(date1, date2); // true

isBefore(date1, date2) / isAfter(date1, date2)

比较日期先后。

import { isBefore, isAfter } from '@wanglei/fkit';

const date1 = new Date('2024-01-15');
const date2 = new Date('2024-01-16');

isBefore(date1, date2); // true
isAfter(date2, date1); // true

isBetween(date, start, end)

检查日期是否在指定范围内。

import { isBetween } from '@wanglei/fkit';

const date = new Date('2024-01-15');
const start = new Date('2024-01-10');
const end = new Date('2024-01-20');

isBetween(date, start, end); // true

日期操作

获取时间边界

import { 
  startOfDay, endOfDay,
  startOfWeek, endOfWeek,
  startOfMonth, endOfMonth 
} from '@wanglei/fkit';

const date = new Date('2024-01-15 14:30:45');

startOfDay(date); // 2024-01-15 00:00:00.000
endOfDay(date); // 2024-01-15 23:59:59.999

startOfWeek(date); // 本周开始
endOfWeek(date); // 本周结束

startOfMonth(date); // 2024-01-01 00:00:00.000
endOfMonth(date); // 2024-01-31 23:59:59.999

🔧 开发

# 克隆项目
git clone https://github.com/wanglei/fkit.git
cd fkit

# 安装依赖
npm install

# 运行测试
npm test

# 代码检查
npm run lint

# 格式化代码
npm run format

# 构建
npm run build

📄 许可证

MIT License - 详见 LICENSE 文件。

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📞 联系

如有问题或建议，请通过以下方式联系：

• GitHub Issues: https://github.com/LA-Star/fkit/issues
• Email: [email protected]