@neosjs/utils
NeosJS 的前端通用工具函数库,聚合了类型判断、格式化、DOM 操作、颜色处理、文件下载、数组 / 对象 / 字符串工具等日常高频函数。所有函数均从统一入口导出并提供完整 TypeScript 类型,包本身 sideEffects: false,可放心按需引入、tree-shaking。
安装
sh
pnpm add @neosjs/utilssh
npm i @neosjs/utilssh
yarn add @neosjs/utils可选依赖
@neosjs/utils 将 @vueuse/core、dayjs、throttle-debounce 声明为可选 peerDependencies,只有使用下表中 dayjs、vendor 两个模块的功能时才需要安装对应依赖。
模块总览
所有模块的导出都从 @neosjs/utils 根入口统一暴露:
ts
import { deepMerge, formatBytes, isString } from '@neosjs/utils'| 模块 | 说明 | 代表导出 |
|---|---|---|
base | 基础工具与版本信息 | version、inBrowser、raf / cancelRaf、noop、extend、toString、assert、openWindow、addPreventDefault |
wrapperEnv | Vite 环境变量包装处理 | wrapperEnv |
is | 类型判断 | isString、isNumber、isBoolean、isObject、isFunction、isNull、isUndefined、isDate、isRegExp、isWindow、isBrowser、isNumeric |
format | 常用格式化 | camelize、kebabCase、formatBytes、formatMobile、urlToBlob |
domUtils | DOM 操作与事件 | getBoundingClientRect、hasClass / addClass / removeClass、getViewportOffset、hackCss、on / off / once |
color | 颜色处理 | isHexColor、rgbToHex、hexToRGB、colorIsDark、darken、lighten、calculateBestTextColor |
files | 文件下载与读取 | downloadByUrl、downloadByData、downloadByBase64、downloadByOnlineUrl、readFileAsBase64 |
uuid | 唯一 ID 生成 | buildUUID、buildShortUUID |
object | 对象工具 | deepMerge、deepMergeWithArray、objectMap、objectKeys、objectEntries、objectPick、clearUndefined、isKeyOf、hasOwnProperty |
array | 数组工具 | toArray、flattenArrayable、mergeArrayable、partition、uniq、uniqueBy、last、remove、at、range、move、clampArrayRange |
string | 字符串工具 | slash、ensurePrefix / ensureSuffix、template、randomStr、capitalize、unindent、trim / trimAll |
guards | 类型守卫 | notNullish、noNull、notUndefined、isTruthy |
math | 数值计算 | clamp、sum |
promise | 异步工具 | sleep |
base64Conver | Base64 转换 | dataURLtoBlob、urlToBase64 |
dayjs | 日期时间(内置中文语言包,需安装 dayjs) | formatToDateTime、formatToDate、handRelativeTime、dateFormat |
vendor | 三方库转导出(需安装 throttle-debounce) | throttle、debounce |
types | TypeScript 类型定义 | Recordable、ViteEnv、Nullable、Arrayable、Awaitable、Fn、DeepMerge 等 |
快速上手
类型判断(is)
一组带类型收窄的判断函数,配合 TypeScript 使用时能在判断后自动收窄变量类型:
ts
import { isBrowser, isNumber, isObject, isString } from '@neosjs/utils'
isString('hello') // true
isNumber(123) // true
isObject({ a: 1 }) // true
isObject([]) // false,仅纯对象([object Object])返回 true
isBrowser // 常量:当前运行环境是否为浏览器格式化(format)
ts
import { formatBytes, formatMobile } from '@neosjs/utils'
formatBytes(1024) // '1 KB'
formatBytes(1024 * 1024 * 1.5) // '1.5 MB'
formatMobile('13812345678') // '138 1234 5678'(自动过滤非数字、按 3-4-4 分组)日期时间(dayjs)
dayjs 模块默认启用了中文语言包并定制了相对时间文案(如「3天前」),直接调用即可得到符合中文习惯的输出:
ts
import { formatToDate, formatToDateTime, handRelativeTime } from '@neosjs/utils'
formatToDateTime(new Date()) // '2026-11-20 15:30:00'(默认格式 YYYY-MM-DD HH:mm:ss)
formatToDate(new Date()) // '2026-11-20'(默认格式 YYYY-MM-DD)
formatToDateTime(new Date(), 'YYYY/MM/DD') // '2026/11/20'(自定义格式)
handRelativeTime('2026-11-19') // '1天前'对象深合并(object)
ts
import { deepMerge } from '@neosjs/utils'
const merged = deepMerge({
a: 1,
nested: { x: 1 }
}, {
b: 2,
nested: { y: 2 }
})
// { a: 1, b: 2, nested: { x: 1, y: 2 } }API 说明
@neosjs/utils 仅暴露一个根入口(package.json 中只有 . 导出),不做子路径导出;上表「代表导出」列出的是各模块中最常用的函数,完整导出以包内类型定义(dist/index.d.ts)为准。