patbear_js_common

PatBear JS Common

一个简单、实用的JavaScript工具库，提供常用的工具函数、验证器和格式化器。

安装

使用npm安装:

npm install patbear_js_common

使用yarn安装:

yarn add patbear_js_common

功能特点

• 轻量化: 体积小，按需引入
• 模块化: 清晰的模块结构，易于使用
• 全面: 涵盖工具函数、验证器和格式化器
• 类型: 完整的TypeScript类型定义

使用方法

工具函数

import { truncate, capitalize, unique, deepMerge, formatDate } from 'patbear_js_common';

// 字符串工具
truncate('这是一个很长的字符串', 5); // '这是一个...'
capitalize('hello'); // 'Hello'

// 数组工具
const arr = [1, 2, 2, 3, 3, 4];
unique(arr); // [1, 2, 3, 4]

// 对象工具
const obj1 = { a: 1, b: { c: 2 } };
const obj2 = { b: { d: 3 }, e: 4 };
deepMerge(obj1, obj2); // { a: 1, b: { c: 2, d: 3 }, e: 4 }

// 日期工具
formatDate(new Date(), 'yyyy-MM-dd'); // '2023-06-01'

验证器

import { isEmpty, isEmail, isInRange, isValidDate } from 'patbear_js_common';

// 字符串验证
isEmpty(''); // true
isEmail('user@example.com'); // true

// 数字验证
isInRange(5, 1, 10); // true

// 日期验证
isValidDate('2023-06-01'); // true

格式化器

import { toCapitalize, toCurrency, formatDate, toRelativeTime } from 'patbear_js_common';

// 字符串格式化
toCapitalize('hello'); // 'Hello'

// 数字格式化
toCurrency(1234.56); // '¥1,234.56'

// 日期格式化
formatDate(new Date(), 'yyyy-MM-dd HH:mm:ss'); // '2023-06-01 12:34:56'
toRelativeTime(new Date(Date.now() - 3600000)); // '1小时前'

项目路径规范

本项目使用路径别名，禁止使用相对路径导入:

// ❌ 错误的导入方式
import { formatDate } from './utils/date';

// ✅ 正确的导入方式
import { formatDate } from '@utils/date';

支持的路径别名:

• @/* - src目录下的文件
• @utils/* - 工具函数
• @validators/* - 验证器函数
• @formatters/* - 格式化器函数

API文档

工具函数

字符串工具

函数	描述	参数	返回值
truncate	截取字符串并添加省略号	str: string, maxLength: number	string
capitalize	将字符串首字母大写	str: string	string
camelToKebab	将驼峰命名转换为短横线命名	str: string	string
kebabToCamel	将短横线命名转换为驼峰命名	str: string	string

数组工具

函数	描述	参数	返回值
unique	数组去重	arr: T[]	T[]
groupBy	数组分组	arr: T[], keyFn: (item: T) => K	Record<K, T[]>
flatten	数组扁平化	arr: any[]	T[]
removeItem	从数组中移除指定项	arr: T[], item: T	boolean

对象工具

函数	描述	参数	返回值
deepMerge	深度合并对象	target: Record<string, any>, source: Record<string, any>	Record<string, any>
get	从对象中获取嵌套属性值	obj: Record<string, any>, path: string, defaultValue?: T	T | undefined
removeEmpty	从对象中移除值为null或undefined的属性	obj: Record<string, any>	Record<string, any>

日期工具

函数	描述	参数	返回值
formatDate	格式化日期	date: Date | number, format?: string	string
daysBetween	获取两个日期之间的天数差	start: Date, end: Date	number
addDays	将日期增加指定天数	date: Date, days: number	Date
isSameDay	判断是否为同一天	date1: Date, date2: Date	boolean

验证器

字符串验证

函数	描述	参数	返回值
isEmpty	判断是否为空字符串	value: string | null | undefined	boolean
isEmail	验证邮箱格式	email: string	boolean
isChinesePhone	验证是否为手机号（中国大陆）	phone: string	boolean
isLengthBetween	验证字符串长度是否在指定范围内	value: string, min: number, max: number	boolean
isUrl	验证URL格式	url: string	boolean

数字验证

函数	描述	参数	返回值
isInRange	验证数字是否在指定范围内	value: number, min: number, max: number	boolean
isInteger	验证是否为整数	value: number	boolean
isPositive	验证是否为正数	value: number	boolean
isNegative	验证是否为负数	value: number	boolean
isNumeric	验证字符串是否可转换为数字	value: string	boolean

日期验证

函数	描述	参数	返回值
isValidDate	验证是否为有效日期	value: any	boolean
isDateInRange	验证日期是否在指定范围内	date: Date, min: Date, max: Date	boolean
isFutureDate	验证日期是否为未来日期	date: Date	boolean
isPastDate	验证日期是否为过去日期	date: Date	boolean
isSameDate	验证是否为相同日期	date1: Date, date2: Date	boolean

格式化器

字符串格式化

函数	描述	参数	返回值
toCapitalize	格式化首字母大写	str: string	string
toKebabCase	格式化为短横线命名	str: string	string
toCamelCase	格式化为驼峰命名	str: string	string
toMasked	格式化为带掩码的字符串	str: string, start?: number, end?: number, mask?: string	string

数字格式化

函数	描述	参数	返回值
toCurrency	格式化为货币	value: number, currency?: string, decimals?: number	string
toPercent	格式化为百分比	value: number, decimals?: number	string
toFixed	格式化为指定小数位数的数字	value: number, decimals?: number	string
toThousands	格式化为带千位分隔符的数字	value: number	string
toFileSize	格式化为指定单位的文件大小	bytes: number, decimals?: number	string

日期格式化

函数	描述	参数	返回值
formatDate	格式化日期为指定格式	date: Date | number, format?: string	string
toRelativeTime	格式化为相对时间	date: Date | number, now?: Date	string
toFriendlyDate	格式化为友好的日期显示	date: Date | number	string

贡献

欢迎提交Issue和Pull Request！

许可证

MIT

编译构建

本项目使用TypeScript开发，需要先编译成JavaScript才能发布。

安装依赖

npm install

或者

yarn

编译构建

npm run build

或者

yarn build

编译后的文件将输出到dist目录。

NPM发布

登录NPM

确保你已经有npm账号并已登录：

npm login

发布包

发布新版本前，请先更新package.json中的版本号，然后运行：

npm publish

发布特定标签版本

发布测试版本：

npm publish --tag beta

更新版本号

可以使用npm命令自动更新版本号：

# 更新补丁版本号 (1.0.0 -> 1.0.1)
npm version patch

# 更新次版本号 (1.0.0 -> 1.1.0)
npm version minor

# 更新主版本号 (1.0.0 -> 2.0.0)
npm version major