11 KiB

Raw Blame History

name	description
jjb-common-lib-tools	定义 @cqsjjb/jjb-common-lib tools 模块使用规范。在使用 parseJSON、parseObject、tools.router、parseArray 等工具函数时查阅。

tools 模块使用规范

概述

tools 模块是 @cqsjjb/jjb-common-lib 通用工具库中的核心模块，包含大量基础工具函数。开发时应优先使用工具库中的工具，避免重复造轮子。

使用建议

优先查找：在实现功能前，应先查找 tools 模块中是否有对应的工具函数
避免重复：不要重复实现工具库中已有的功能
参考文档：使用前应参考 reference/tools.md 查看完整的 API 文档和使用示例

导入方式

import { tools } from '@cqsjjb/jjb-common-lib';

内置方法详解

JSON/数据解析与序列化

parseJSON(value)

解析 JSON 字符串。

参数：

value (string): JSON 字符串

返回值：

如果不是 JSON 字符串，则返回传入的值；如果是 JSON 字符串，则返回解析后的对象/数组；如果解析失败返回传入的值

示例：

tools.parseJSON('{"a":1}') // => { a: 1 }

parseObject(v)

序列化对象转真对象。

参数：

v (string): JSON 字符串

返回值：

解析后的对象，如果解析失败返回 {}

示例：

tools.parseObject('{"a":1}') // => { a: 1 }

parseArray(v)

序列化数组转真数组。

参数：

v (string): JSON 字符串

返回值：

解析后的数组，如果解析失败返回 []

示例：

tools.parseArray('[1,2,3]') // => [1,2,3]

stringifyObject(v, replacer?, space?)

序列化对象为 JSON 字符串。

参数：

v (any): 对象
replacer (any, 可选): 替换函数
space (number, 可选): 缩进，默认为 2

返回值：

JSON 字符串，如果转换失败返回 '{}'

示例：

tools.stringifyObject({a:1}) // => '{"a":1}'

stringifyArray(v, replacer?, space?)

序列化数组为 JSON 字符串。

参数：

v (any[]): 数组
replacer (any, 可选): 替换函数
space (number, 可选): 缩进，默认为 2

返回值：

JSON 字符串，如果转换失败返回 '[]'

示例：

tools.stringifyArray([1,2]) // => '[1,2]'

数据清洗

cleanArray(v)

清洗数组，移除无效值。

参数：

v (any[]): 数组

返回值：

清洗后的数组

示例：

tools.cleanArray([1,2,null]) // => [1,2,null]

cleanObject(v)

清洗对象，移除 undefined 等无效属性。

参数：

v (object): 对象

返回值：

清洗后的对象

示例：

tools.cleanObject({a:1,b:undefined}) // => {a:1}

类型判断

isEmptyObject(v)

判断是否是空对象。

参数：

v (any): 任意值

返回值：

boolean: 是否是空对象

示例：

tools.isEmptyObject({}) // => true

isEmptyStringObject(v)

判断是否是空字符串对象（字符串 '{}'）。

参数：

v (any): 任意值

返回值：

boolean: 是否是空字符串对象

示例：

tools.isEmptyStringObject('{}') // => true

isEmptyStringArray(v)

判断是否是空字符串数组（字符串 '[]'）。

参数：

v (any): 任意值

返回值：

boolean: 是否是空字符串数组

示例：

tools.isEmptyStringArray('[]') // => true

isNativeEvent(v)

判断是否是 Event 对象。

参数：

v (any): 任意值

返回值：

boolean: 是否是 Event 对象

示例：

tools.isNativeEvent(new Event('click')) // => true

getPrimaryType(v)

获取基础类型字符串。

参数：

v (any): 任意值

返回值：

string: 基础类型字符串（如 'Number'、'String' 等）

示例：

tools.getPrimaryType(1) // => 'Number'

isTrueEnum(v)

判断是否等于 'TRUE'。

参数：

v (any): 任意值

返回值：

boolean: 是否等于 TRUE_ENUM（'TRUE'）

示例：

tools.isTrueEnum('TRUE') // => true

isFalseEnum(v)

判断是否等于 'FALSE'。

参数：

v (any): 任意值

返回值：

boolean: 是否等于 FALSE_ENUM（'FALSE'）

示例：

tools.isFalseEnum('FALSE') // => true

isBoolEnum(v)

判断是否是 'TRUE' 或 'FALSE'。

参数：

v (any): 任意值

返回值：

boolean: 是否是 TRUE_ENUM 或 FALSE_ENUM

示例：

tools.isBoolEnum('TRUE') // => true
tools.isBoolEnum('FALSE') // => true

类型转换

toObject(v)

转换为对象。

参数：

v (any): 任意值

返回值：

对象，如果为空对象则返回 {}

示例：

tools.toObject(null) // => {}

toFunction(v)

转换为函数。

参数：

v (any): 任意值

返回值：

函数，如果不是函数则返回 noop

示例：

tools.toFunction(() => 1) // => () => 1

toArray(v)

转换为数组。

参数：

v (any): 任意值

返回值：

数组，如果不是数组则返回 []

示例：

tools.toArray(1) // => []

toBoolEnum(v)

布尔值转字符串枚举。

参数：

v (boolean): 布尔值

返回值：

'TRUE' | 'FALSE': 转换后的枚举字符串

示例：

tools.toBoolEnum(true) // => 'TRUE'
tools.toBoolEnum(false) // => 'FALSE'

数组处理

uniqueArray(array)

字符串或数字数组去重复。

参数：

array (T[], 可选): 数组，默认为 []

返回值：

去重后的数组

示例：

tools.uniqueArray([1,2,3,1]) // => [1,2,3]

字符串处理

classNames(...args)

绑定 className，支持字符串、数组等多种参数格式。

参数：

...args (any[]): 类名参数，可以是字符串、数组等

返回值：

string: 合并后的类名字符串

示例：

tools.classNames('a', 'b', 'c') // => 'a b c'
tools.classNames('a', ['b', 'c']) // => 'a b c'

toCamelCase(str)

下划线转小驼峰。

参数：

str (string): 下划线格式的字符串

返回值：

string: 小驼峰格式的字符串，如果不是字符串则返回空字符串

示例：

tools.toCamelCase('hello_world') // => 'helloWorld'

toPascalCase(str)

下划线转大驼峰。

参数：

str (string): 下划线格式的字符串

返回值：

string: 大驼峰格式的字符串，如果不是字符串则返回空字符串

示例：

tools.toPascalCase('hello_world') // => 'HelloWorld'

环境检测

inIframe()

判断当前网页是否嵌入 iframe。

返回值：

boolean: 是否在 iframe 中

示例：

tools.inIframe() // => true/false

inWxBrowser()

判断当前网页是否在微信浏览器中。

返回值：

boolean: 是否在微信小程序浏览器中

示例：

tools.inWxBrowser() // => true/false

异步处理

asyncWait(fn, callback, maxCount?)

异步等待，通过检查函数 fn 返回真值时停止等待并执行回调。

参数：

fn (() => any): 检查函数，返回真值时停止等待
callback ((value: any) => void): 回调函数
maxCount (number, 可选): 最大执行次数，默认为 0（无限制）

返回值：

void

示例：

tools.asyncWait(() => 1, (value) => console.log(value), 10)

路由参数管理

router 对象提供完整的路由参数管理能力，基于 qs 模块实现。

router.values()

获取路由参数值数组。

返回值：

string[]: 路由参数值数组

示例：

tools.router.values() // => ['1','2','3']

router.keys()

获取路由参数键数组。

返回值：

string[]: 路由参数键数组

示例：

tools.router.keys() // => ['a','b','c']

router.length

获取路由参数长度（只读）。

返回值：

number: 路由参数长度

示例：

tools.router.length // => 3

router.query

获取/设置路由参数对象。

获取示例：

tools.router.query // => {a:1,b:2,c:3}

设置示例：

tools.router.query = {a:1,b:2,c:3}
tools.router.query.a = 1
delete tools.router.query.a

router.has(name)

判断是否存在指定路由参数。

参数：

name (string): 路由参数名

返回值：

boolean: 是否存在该路由参数

示例：

tools.router.has('a') // => true

router.add(name, value)

添加路由参数。

参数：

name (string): 路由参数名
value (any): 路由参数值

返回值：

void

示例：

tools.router.add('a', 1)

router.delete(name)

删除路由参数。

参数：

name (string): 路由参数名

返回值：

void

示例：

tools.router.delete('a')

router.toString(prefix?)

转为字符串。

参数：

prefix (boolean, 可选): 是否添加前缀 ?，默认为 false

返回值：

string: 路由参数字符串

示例：

tools.router.toString(true) // => '?a=1&b=2&c=3'

文件处理

base64ToFile(base64, fileName)

base64 字符串转 File 对象。

参数：

base64 (string): base64 字符串
fileName (string): 文件名

返回值：

File | undefined: File 对象，转换失败返回 undefined

示例：

tools.base64ToFile('data:image/png;base64,...', '123.png') // => File

fileToBase64(file)

File 对象转 base64 字符串。

参数：

file (File): File 对象

返回值：

Promise<string | undefined>: base64 字符串，转换失败返回 undefined

示例：

tools.fileToBase64(new File([], '123.png')) // => Promise<'base64'>

枚举处理

getEnumLabel(data)

获取枚举标签。

参数：

data (string | { label: string }): 枚举数据，可以是字符串或包含 label 属性的对象

返回值：

string | undefined: 枚举标签

示例：

tools.getEnumLabel({ label: '1' }) // => '1'
tools.getEnumLabel('label') // => 'label'

getEnumValue(data)

获取枚举值。

参数：

data (string | { value: any }): 枚举数据，可以是字符串或包含 value 属性的对象

返回值：

any: 枚举值

示例：

tools.getEnumValue({ value: '1' }) // => '1'
tools.getEnumValue('value') // => 'value'

使用注意事项

错误处理：大部分函数都有容错处理，解析失败或转换失败时会返回默认值（如 {}、[]、undefined 等），使用时应注意处理这些情况
类型安全：虽然工具函数提供了类型转换功能，但在 TypeScript 项目中仍应尽量保证类型安全
性能考虑：对于频繁调用的场景，应注意函数的性能表现
参考文档：详细的使用示例和 API 文档请参考 reference/tools.md

11 KiB Raw Blame History Unescape Escape

tools 模块使用规范

概述

使用建议

导入方式

内置方法详解

JSON/数据解析与序列化

parseJSON(value)

parseObject(v)

parseArray(v)

stringifyObject(v, replacer?, space?)

stringifyArray(v, replacer?, space?)

数据清洗

cleanArray(v)

cleanObject(v)

类型判断

isEmptyObject(v)

isEmptyStringObject(v)

isEmptyStringArray(v)

isNativeEvent(v)

getPrimaryType(v)

isTrueEnum(v)

isFalseEnum(v)

isBoolEnum(v)

类型转换

toObject(v)

toFunction(v)

toArray(v)

toBoolEnum(v)

数组处理

uniqueArray(array)

字符串处理

classNames(...args)

toCamelCase(str)

toPascalCase(str)

环境检测

inIframe()

inWxBrowser()

异步处理

asyncWait(fn, callback, maxCount?)

路由参数管理

router.values()

router.keys()

router.length

router.query

router.has(name)

router.add(name, value)

router.delete(name)

router.toString(prefix?)

文件处理

base64ToFile(base64, fileName)

fileToBase64(file)

枚举处理

getEnumLabel(data)

getEnumValue(data)

使用注意事项

相关模块

11 KiB

Raw Blame History