(1.0.57)
Sybz-Components

Appearance

On this page

utils 总览 ​

Hidden Title ​

本页收录 @sybz-components/utils 当前对外导出的全部工具方法，并为每个方法补一个最小示例，方便直接查用法。

以下示例默认已经从 @sybz-components/utils 引入对应方法；依赖 window、document、localStorage 或 Element Plus 的方法，需要在浏览器环境中使用。

全局配置 ​

在应用入口调用一次 configureUtils，即可为支持主题的工具函数设置默认主题。theme 可选值为 'default' | 'chenghua' | 'shijingshan'，默认值为 'default'；单次调用传入的 theme 优先级更高。

ts
import { configureUtils } from '@sybz-components/utils'

configureUtils({
  theme: 'shijingshan',
  http: {
    baseURL: '/api',
    getToken: () => localStorage.getItem('token'),
  },
})
import { configureUtils } from '@sybz-components/utils'

configureUtils({
  theme: 'shijingshan',
  http: {
    baseURL: '/api',
    getToken: () => localStorage.getItem('token'),
  },
})

配置后，confirm 和 $toast 无需重复传入主题：

ts
await confirm({ variant: 'delete', target: '示例数据' })
$toast('删除成功')

// 单次覆盖全局主题
$toast({ message: '使用成华主题', theme: 'chenghua' })
await confirm('使用默认主题', { theme: 'default' })
await confirm({ variant: 'delete', target: '示例数据' })
$toast('删除成功')

// 单次覆盖全局主题
$toast({ message: '使用成华主题', theme: 'chenghua' })
await confirm('使用默认主题', { theme: 'default' })

http 也在这里配置一次，之后直接从 @sybz-components/utils 引入全局客户端：

ts
import { http } from '@sybz-components/utils'

const users = await http.get('/users')
import { http } from '@sybz-components/utils'

const users = await http.get('/users')

导出入口 ​

ts
export * from './base'
export * from './confirmSemantic'
export * from './is'
export * from './format'
export * from './theme'
export * from './http'
export * from './base'
export * from './confirmSemantic'
export * from './is'
export * from './format'
export * from './theme'
export * from './http'

已有独立文档 ​

函数方法（A-Z） ​

$toast ​

用于快速显示消息提示。

ts
$toast('保存成功')
$toast('保存失败', 'e')
$toast.success('创建完成')
$toast('保存成功')
$toast('保存失败', 'e')
$toast.success('创建完成')

clearStorage ​

清理 localStorage / sessionStorage 中的指定项，或按排除项整体清空。

ts
clearStorage('token')

clearStorage(['token', 'userInfo'])

clearStorage({ exclude: ['theme', 'language'] })
clearStorage('token')

clearStorage(['token', 'userInfo'])

clearStorage({ exclude: ['theme', 'language'] })

clone ​

深拷贝对象；如果传入数组，还可以按次数复制数组内容。

ts
const obj = clone({ name: 'andy', extra: { id: 1 } })
const list = clone([1, 2, 3], 2)
const obj = clone({ name: 'andy', extra: { id: 1 } })
const list = clone([1, 2, 3], 2)

confirm ​

基于 ElMessageBox.confirm 的确认框封装。

ts
await confirm('确定删除当前记录吗？', {
  confirmButtonText: '删除',
})
await confirm('确定删除当前记录吗？', {
  confirmButtonText: '删除',
})

copy ​

复制文本到剪贴板，并默认弹出成功提示。

ts
copy('sybz-components')
copy('静默复制', { hideToast: true })
copy('sybz-components')
copy('静默复制', { hideToast: true })

debounce ​

防抖函数，常用于搜索输入、窗口尺寸变化等场景。

ts
const search = debounce((keyword: string) => {
  console.log('search:', keyword)
}, 300)

search('sybz')

const submit = debounce(
  async () => {
    return await saveForm()
  },
  500,
  true,
  (result) => {
    console.log('保存结果:', result)
  },
)

submit.cancel()
const search = debounce((keyword: string) => {
  console.log('search:', keyword)
}, 300)

search('sybz')

const submit = debounce(
  async () => {
    return await saveForm()
  },
  500,
  true,
  (result) => {
    console.log('保存结果:', result)
  },
)

submit.cancel()

formatBytes ​

把字节数格式化成更易读的单位字符串。

ts
formatBytes(1024) // 1.00 KB
formatBytes(1048576, { digit: 1, suffix: '/s' }) // 1.0 MB/s
formatBytes(1024) // 1.00 KB
formatBytes(1048576, { digit: 1, suffix: '/s' }) // 1.0 MB/s

formatBytesConvert ​

把 KB / MB / GB 这类字符串还原成字节数。

ts
formatBytesConvert('1.5GB')
formatBytesConvert('1,024 KB')
formatBytesConvert('1.5GB')
formatBytesConvert('1,024 KB')

formatDurationTime ​

把持续时间时间戳格式化成“天 / 时 / 分 / 秒”文本。

ts
formatDurationTime(1162821) // 19分22秒
formatDurationTime(5 * 60 * 1000, '{i}分{s}秒')
formatDurationTime(1162821) // 19分22秒
formatDurationTime(5 * 60 * 1000, '{i}分{s}秒')

formatTextToHtml ​

将换行和缩进转换为适合直接展示的 HTML 字符串。

ts
formatTextToHtml('第1行\n第2行\n\t缩进内容')
formatTextToHtml('第1行\n第2行\n\t缩进内容')

formatThousands ​

为数字增加千分位分隔符。

ts
formatThousands(1234567)
formatThousands('1234567.89MB')
formatThousands(1234567)
formatThousands('1234567.89MB')

formatTime ​

把时间格式化成指定模板字符串。

ts
formatTime(new Date(), '{y}-{m}-{d} {h}:{i}:{s}')
formatTime(1713926400, '{y}/{m}/{d}')
formatTime(new Date(), '{y}-{m}-{d} {h}:{i}:{s}')
formatTime(1713926400, '{y}/{m}/{d}')

formatToFixed ​

按指定小数位补全数字，也支持前后缀和保留单位。

ts
formatToFixed('22.1', 2) // 22.10
formatToFixed('22 TB', { digit: 2, unit: false, prefix: '$' }) // $22.00
formatToFixed('22.1', 2) // 22.10
formatToFixed('22 TB', { digit: 2, unit: false, prefix: '$' }) // $22.00

getStorage ​

从 localStorage 或 sessionStorage 中读取数据，并自动尝试反序列化。

ts
const token = getStorage('token')

const userInfo = getStorage<{ id: number; name: string }>('userInfo')

const draft = getStorage('formDraft', true)
const token = getStorage('token')

const userInfo = getStorage<{ id: number; name: string }>('userInfo')

const draft = getStorage('formDraft', true)

getType ​

返回更直观的小写类型字符串。

ts
getType([]) // array
getType(new Date()) // date
getType(null) // null
getType([]) // array
getType(new Date()) // date
getType(null) // null

getVariable ​

读取根节点上的 CSS 变量值。

ts
const brandColor = getVariable('--vp-c-brand-1')
const brandColor = getVariable('--vp-c-brand-1')

isArray ​

判断值是否为数组。

ts
isArray([1, 2, 3]) // true
isArray({ length: 3 }) // false
isArray([1, 2, 3]) // true
isArray({ length: 3 }) // false

isBoolean ​

判断值是否为布尔值。

ts
isBoolean(false) // true
isBoolean(0) // false
isBoolean(false) // true
isBoolean(0) // false

isComponent ​

判断对象是否为 Vue 组件配置。

ts
isComponent({
  render() {
    return null
  },
})
isComponent({
  render() {
    return null
  },
})

isDate ​

判断值是否为 Date 对象。

ts
isDate(new Date()) // true
isDate('2026-04-24') // false
isDate(new Date()) // true
isDate('2026-04-24') // false

isEmpty ​

判断值是否为空。当前默认不会把 0 和 false 当成空值。

ts
isEmpty('   ') // true
isEmpty(0) // false
isEmpty(0, false) // true，兼容旧语义
isEmpty('   ') // true
isEmpty(0) // false
isEmpty(0, false) // true，兼容旧语义

isEmptyObject ​

判断值是否为空对象。

ts
isEmptyObject({}) // true
isEmptyObject({ id: 1 }) // false
isEmptyObject({}) // true
isEmptyObject({ id: 1 }) // false

isFunction ​

判断值是否为函数。

ts
isFunction(() => {}) // true
isFunction('fn') // false
isFunction(() => {}) // true
isFunction('fn') // false

isIOS ​

根据 userAgent 判断当前环境是否为 iOS。

ts
if (isIOS()) {
  console.log('当前是 iOS 设备')
}
if (isIOS()) {
  console.log('当前是 iOS 设备')
}

isMap ​

判断值是否为 Map。

ts
isMap(new Map()) // true
isMap({}) // false
isMap(new Map()) // true
isMap({}) // false

isNumber ​

判断值是否为数字类型。

ts
isNumber(12) // true
isNumber('12') // false
isNumber(12) // true
isNumber('12') // false

isObject ​

判断值是否为对象且不为 null。

ts
isObject({ id: 1 }) // true
isObject(null) // false
isObject({ id: 1 }) // true
isObject(null) // false

isPlainObject ​

判断值是否为普通对象。

ts
isPlainObject({ id: 1 }) // true
isPlainObject(new Date()) // false
isPlainObject({ id: 1 }) // true
isPlainObject(new Date()) // false

isPromise ​

判断值是否为 Promise 风格对象。

ts
isPromise(Promise.resolve(1)) // true
isPromise({ then: () => {} }) // false
isPromise(Promise.resolve(1)) // true
isPromise({ then: () => {} }) // false

isRegExp ​

判断值是否为正则对象。

ts
isRegExp(/sybz/i) // true
isRegExp('sybz') // false
isRegExp(/sybz/i) // true
isRegExp('sybz') // false

isSet ​

判断值是否为 Set。

ts
isSet(new Set([1, 2, 3])) // true
isSet([1, 2, 3]) // false
isSet(new Set([1, 2, 3])) // true
isSet([1, 2, 3]) // false

isString ​

判断值是否为字符串。

ts
isString('sybz') // true
isString(123) // false
isString('sybz') // true
isString(123) // false

isStringNumber ​

判断字符串是否可以被转成有效数字。

ts
isStringNumber('12.5') // true
isStringNumber('12px') // false
isStringNumber('12.5') // true
isStringNumber('12px') // false

isSVGElement ​

判断节点是否为 SVGElement。

ts
const svg = document.querySelector('svg')
isSVGElement(svg)
const svg = document.querySelector('svg')
isSVGElement(svg)

isSymbol ​

判断值是否为 Symbol。

ts
isSymbol(Symbol('id')) // true
isSymbol('id') // false
isSymbol(Symbol('id')) // true
isSymbol('id') // false

isUrl ​

判断字符串是否为合法链接。

ts
isUrl('https://sybz-components.com') // true
isUrl('/local/path') // false
isUrl('https://sybz-components.com') // true
isUrl('/local/path') // false

log ​

对 console.log 的简单封装，输出时会额外带上变量名。

ts
const formData = { id: 1, name: 'andy' }
log('formData', formData)
const formData = { id: 1, name: 'andy' }
log('formData', formData)

merge ​

合并两个对象；同名字段都存在时，以第二个对象为准。

ts
merge({ name: '', age: 18, city: 'beijing' }, { name: 'andy', age: 20, city: '' })
merge({ name: '', age: 18, city: 'beijing' }, { name: 'andy', age: 20, city: '' })

objectToString ​

Object.prototype.toString 的直接别名。

ts
objectToString.call([]) // [object Array]
objectToString.call(new Date()) // [object Date]
objectToString.call([]) // [object Array]
objectToString.call(new Date()) // [object Date]

onlyTest ​

测试导出方法。

ts
onlyTest() // test
onlyTest() // test

processWidth ​

把宽度值转换成统一的 CSS 写法。

ts
processWidth(200) // { width: '200px' }
processWidth('50%', true) // 50%
processWidth(200) // { width: '200px' }
processWidth('50%', true) // 50%

random ​

生成指定范围内的随机整数。

ts
random() // 0 ~ 10
random(100, 999) // 100 ~ 999
random() // 0 ~ 10
random(100, 999) // 100 ~ 999

setStorage ​

向 localStorage 或 sessionStorage 写入数据。

ts
setStorage('token', 'abc123')

setStorage('userInfo', { id: 1, name: 'andy' })

setStorage('formDraft', { keyword: '机房', page: 2 }, true)
setStorage('token', 'abc123')

setStorage('userInfo', { id: 1, name: 'andy' })

setStorage('formDraft', { keyword: '机房', page: 2 }, true)

delay ​

创建一个可 await 的延迟。

ts
await delay(500)
await delay(1000, () => console.log('1 秒后执行'))
await delay(500)
await delay(1000, () => console.log('1 秒后执行'))

getUtilsBuildTime ​

返回当前 utils 构建时间。

ts
getUtilsBuildTime()
getUtilsBuildTime()

throttle ​

节流函数，适合滚动、拖拽、窗口变化等高频事件。

ts
const handleResize = throttle(() => {
  console.log('resize')
}, 300)

window.addEventListener('resize', handleResize)

const saveDraft = throttle(
  (content: string) => {
    return content.trim()
  },
  1000,
  { leading: false, trailing: true },
  (result) => {
    console.log('保存草稿:', result)
  },
)

saveDraft('hello')
saveDraft.flush()
saveDraft.cancel()
const handleResize = throttle(() => {
  console.log('resize')
}, 300)

window.addEventListener('resize', handleResize)

const saveDraft = throttle(
  (content: string) => {
    return content.trim()
  },
  1000,
  { leading: false, trailing: true },
  (result) => {
    console.log('保存草稿:', result)
  },
)

saveDraft('hello')
saveDraft.flush()
saveDraft.cancel()

toLine ​

把驼峰字符串转换成连接符形式。

ts
toLine('inputNumber') // input-number
toLine('CompTitle', '_') // comp_title
toLine('inputNumber') // input-number
toLine('CompTitle', '_') // comp_title

toRawType ​

返回更短的原始类型名称。

ts
toRawType(new Map()) // Map
toRawType([]) // Array
toRawType(new Map()) // Map
toRawType([]) // Array

toTypeString ​

返回完整的 Object.prototype.toString 结果。

ts
toTypeString([]) // [object Array]
toTypeString(Promise.resolve()) // [object Promise]
toTypeString([]) // [object Array]
toTypeString(Promise.resolve()) // [object Promise]

tryCatch ​

统一处理 Promise 或任务函数执行结果，返回固定的 { data, error }。

ts
const loadList = async () => ({ list: [] })

const { data, error } = await tryCatch(() => loadList())
if (!error) {
  console.log(data?.list)
}
const loadList = async () => ({ list: [] })

const { data, error } = await tryCatch(() => loadList())
if (!error) {
  console.log(data?.list)
}

mockValue ​

生成随机字符串，也支持手机号、邮箱、时间串、数字等特殊模式。

ts
mockValue() // 普通随机串
mockValue('phone') // 随机手机号
mockValue('number', 6) // 6 位数字
mockValue() // 普通随机串
mockValue('phone') // 随机手机号
mockValue('number', 6) // 6 位数字

validate ​

生成 Element Plus 表单规则，或在 pureValid=true 时直接返回布尔结果。

ts
const mobileRule = validate('mobile')
const selectRule = validate('change') // 默认提示：请选择
const emailRule = validate({ type: 'email', message: '请输入邮箱' })
const isIp = validate('ip', '192.168.1.10', true)
const mobileRule = validate('mobile')
const selectRule = validate('change') // 默认提示：请选择
const emailRule = validate({ type: 'email', message: '请输入邮箱' })
const isIp = validate('ip', '192.168.1.10', true)

validateOnSubmit ​

在 validate 基础上补齐默认空触发时机，只在提交或手动调用表单校验时触发。validate 默认触发时机是 ['blur', 'change']。

ts
const nameRule = validateOnSubmit('required', {
  message: '请输入名称',
})
const nameRule = validateOnSubmit('required', {
  message: '请输入名称',
})

validateForm ​

对 el-form 的 validate 做 Promise 封装，便于直接 await。

ts
await validateForm(formRef)
await validateForm(formRef, {
  message: '请先完善表单信息',
  detail: true,
})
await validateForm(formRef)
await validateForm(formRef, {
  message: '请先完善表单信息',
  detail: true,
})

思云博智私有前端组件库

版权所有 © 2023-2030