Skip to content

@neosjs/utils ​

NeosJS 的前端通用工具函数库,聚合了类型判断、格式化、DOM 操作、颜色处理、文件下载、数组 / 对象 / 字符串工具等日常高频函数。所有函数均从统一入口导出并提供完整 TypeScript 类型,包本身 sideEffects: false,可放心按需引入、tree-shaking。

安装 ​

sh
pnpm add @neosjs/utils
sh
npm i @neosjs/utils
sh
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
wrapperEnvVite 环境变量包装处理wrapperEnv
is类型判断isString、isNumber、isBoolean、isObject、isFunction、isNull、isUndefined、isDate、isRegExp、isWindow、isBrowser、isNumeric
format常用格式化camelize、kebabCase、formatBytes、formatMobile、urlToBlob
domUtilsDOM 操作与事件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
base64ConverBase64 转换dataURLtoBlob、urlToBase64
dayjs日期时间(内置中文语言包,需安装 dayjs)formatToDateTime、formatToDate、handRelativeTime、dateFormat
vendor三方库转导出(需安装 throttle-debounce)throttle、debounce
typesTypeScript 类型定义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)为准。