@klweb/utils v1.0.4

@klweb/utils

@klweb/utils 是一个模块化的 JavaScript 工具类库，提供一系列实用的函数和方法，以帮助开发者更高效、更便捷地处理常见的编程任务。

@klweb/utils 涵盖了一系列常用的工具函数，如：

• 字符串处理：用于操作和处理字符串。例如，你可以找到用于切割、连接、搜索和替换字符串的函数。

• 数组操作：对于处理数组，@klweb/utils 提供了一系列有用的函数，例如排序、过滤、映射等。这些函数可以帮助你轻松地处理数组数据。

• 日期和时间处理：可以帮助你方便地处理日期和时间。

• 文件和流处理：对于需要处理文件或流的场景，这个库提供了一些函数和方法，例如读取文件、写入文件、解析流等。

• 错误处理：提供了一些工具用于错误处理，如捕获异常、生成错误等。

模块化的设计思路，更好的 Tree-Shaking 支持，每个工具函数都作为一个独立的模块提供。这种设计使得开发者可以根据自己的需要选择所需的模块，而不是被迫使用整个库。

📑 API 文档

🔸 debounce

防抖函数，在连续执行时只执行最后一次函数。

debounce<T extends (...args: Array<any>) => any>(fn: T, interval?: number): T

在防抖函数中，当连续点击时，会取消之前的等待，重新开始计时。只有在等待时间内没有再次点击，才会执行原函数。

参数

返回值

返回一个新函数

示例

import { debounce } from '@klweb/utils'

const func = debounce((arg1, arg2) => console.log(arg1, arg2), 500);
func('Hello', 'KLWeb-Utils!');
func('Hello', 'KLWeb-Utils!');
func('Hello', 'KLWeb-Utils!');
func('Hello', 'KLWeb-Utils!')

// 连续执行只会执行最后一次
// Expected output: Hello KLWeb-Utils!

🔸 throttle

节流函数，限制函数的执行频率，每经过指定的时间间隔后才执行一次。

throttle<T extends (...args: Array<any>) => any>(fn: T, interval?: number): T

节流函数是一种优化技术，用于限制函数的执行频率。它确保在指定的时间间隔内只执行一次原函数，从而减少频繁调用或连续执行的情况。

参数

返回值

返回一个新函数

示例

import { throttle } from '@klweb/utils'

const func = throttle((arg1, arg2) => console.log(arg1, arg2), 1500);
func('Hello', 'KLWeb-Utils!')

🔸 dateFormatter

基于 moment.js 的日期时间格式器

dateFormatter(date: DateTypes, pattern?: string, locale?: string): string

moment.js 是一个解析、校验、操作、显示日期和时间的 JavaScript 工具库。

参数

返回值

返回格式化后的日期

示例

import { dateFormatter } from '@klweb/utils'

const timestamp = 1692080368718;
console.log(dateFormatter(timestamp))
// Expected output: 2023-08-15 14:19:28

console.log(dateFormatter(timestamp, 'HH:mm:ss'))
// Expected output: 14:19:28

🔸 getCurrentDateTime

获取当前日期时间

getCurrentDateTime(pattern?: string, locale?: string): string

参数

返回值

获取当前日期时间

示例

import { getCurrentDateTime } from '@klweb/utils'

console.log(getCurrentDateTime())
// Expected output: 2023年08月15日 星期二 15:11:50

console.log(getCurrentDateTime('HH:mm:ss'))
// Expected output: 15:13:33

🔸 getUrlParamsRaw

获取浏览器地址栏 URL 所有参数值

getUrlParamsRaw(): Record<string, any>

参数

无

返回值

返回一个对象，如果不存在则返回 {}。

示例

import { getUrlParamsRaw } from '@klweb/utils'

// https://www.klweb.com/index.html?a=1&b=2
const params = getUrlParamsRaw();
console.log(params)
// Expected output: { a: 1, b: 2}

🔸 copyToClipboard

复制到剪贴板

copyToClipboard(text: string): Promise<void>

参数

返回值

返回一个不带有任何参数的 Promise

示例

import { copyToClipboard } from '@klweb/utils'

const text = '这是一段测试文本';
copyToClipboard(text)
    .then(() => {
        console.log('Text successfully written to clipboard')
    })
    .catch(error => {
        console.log('Error writing text to clipboard', error)
    }) 

🔸 htmlToEscape

HTML 转义符（HTML 标签转换为对应的 HTML 实体）。

htmlToEscape(htmlText: string): string

参数

返回值

返回处理后的 HTML 代码文本

示例

import { htmlToEscape } from '@klweb/utils'

const htmlText = `<p>这是一段测试代码</p>`;
console.log(htmlToEscape(htmlText))
// Expected output: "&lt;p&gt;这是一段测试代码&lt;/p&gt;"

🔸 escapeToHtml

HTML 反转义符（HTML 实体转换为对应的 HTML 标签）。

escapeToHtml(htmlText: string): string

参数

返回值

返回处理后的 HTML 代码文本

示例

import { escapeToHtml } from '@klweb/utils'

const htmlText = `<p>这是一段测试代码</p>`;
console.log(escapeToHtml(htmlText))
// Expected output: "<p>这是一段测试代码</p>"

🔸 sumArray

数组求和

sumArray(array: number[]): number

参数

返回值

返回总和值

示例

import { sumArray } from '@klweb/utils'

const array = [2, 4, 5, 23, 100];
const total = sumArray(array);
console.log(total)
// Expected output: 134

🔸 filterArray

根据给定的谓词函数过滤数组元素。filterArray，它是一个泛型函数，可以处理任意类型的数组。

filterArray<T>(array: T[], predicate: (item: T) => boolean): T[]

函数内部调用了数组的 filter 方法，将谓词函数作为参数传入，对数组进行过滤操作。

参数

返回值

返回过滤后的数组

示例

import { filterArray } from '@klweb/utils'

const items = [1, 2, 3, 4, 5]; 
const evenNumbers = filterArray(items, item => item % 2 === 0);
console.log(evenNumbers)
// Expected output: [2, 4]

🔸 mapArray

数组元素映射。mapArray，它是一个泛型函数，可以处理任意类型的数组。

mapArray<T, U>(array: T[], mapper: (item: T) => U): U[]

函数内部调用了数组的 map 方法，将映射函数 mapper 作为参数传入，对数组进行映射操作。

参数

返回值

返回映射后的新数组

示例

import { mapArray } from '@klweb/utils'

const names = ['Alice', 'Bob', 'Charlie']; 
const capitalizedNames = mapArray(names, name => name.toUpperCase());
console.log(capitalizedNames)
// Expected output: ['ALICE', 'BOB', 'CHARLIE']

🔸 findArray

查找数组中符合条件的元素。findArray，它是一个泛型函数，可以处理任意类型的数组。

findArray<T>(array: T[], predicate: (item: T) => boolean): T | undefined

函数内部使用 for...of 循环遍历数组中的每个元素，并调用 predicate 函数进行条件判断。

参数

返回值

返回值是一个类型为 T | undefined 的值，如果找到了符合条件的元素，则返回该元素，否则返回 undefined。

示例

import { findArray } from '@klweb/utils'

const list = [1, 2, 3, 4, 5];  
const foundNumber = findArray(list, number => number === 3);
console.log(foundNumber)
// Expected output: 3

🔸 uniqueArray

去除数组中的重复元素，并返回新的数组。

uniqueArray<T>(array: T[]): T[]

函数内部使用 Set 数据结构来存储去重后的元素（因为 Set 会自动去除重复的键值），最后将 Set 对象转换为数组并返回。

参数

返回值

返回处理后的新数组，不包含重复元素。

示例

import { uniqueArray } from '@klweb/utils'

const items = [1, 2, 2, 3, 4, 4, 5];   
const uniqueItems = uniqueArray(items);
console.log(uniqueItems)
// Expected output: [1, 2, 3, 4, 5]

🔸 uniqueArrayOfObjectByKey

去除数组对象中给定键名存在重复值的对象，并返回新的数组。

uniqueArrayOfObjectByKey<T extends Record<string, any>>(array: T[], key: keyof T): T[]

参数

返回值

返回处理后的新数组

示例

import { uniqueArrayOfObjectByKey } from '@klweb/utils'

const items = [
    { name: '张三', age: 24 },
    { name: '李四', age: 18 },
    { name: '张三', age: 24 },
    { name: '王五', age: 31 }
];   
const uniqueItems = uniqueArrayOfObjectByKey(items, 'name');
console.log(uniqueItems)
// Expected output: 
// [{ name: '张三', age: 24 }, { name: '李四', age: 18 }, { name: '王五', age: 31 }]

🔸 sortArray

数组排序，支持中英文、数字排序。

sortArray(array: Array<any>, order?: Order): Array<any>

参数

返回值

返回处理后的新数组

示例

import { sortArray } from '@klweb/utils'

// 按字母 A-Z 排序
const arr1 = ['b',  'D', 'A', 'c']; 
const sortArr1 = sortArray(arr1);
console.log(sortArr1)
// Expected output: ['A', 'b', 'c', 'D']

// 按数字排序
const arr2 = [3,  2, 1, 4]; 
const sortArr2 = sortArray(arr2);
console.log(sortArr2)
// Expected output: [1,  2, 3, 4]

// 按中文排序
const arr3 = ['白雪',  '阿力', '陈九']; 
const sortArr3 = sortArray(arr3);
console.log(sortArr3)
// Expected output: ['阿力',  '白雪', '陈九']

🔸 sortArrayOfObjectByKey

数组对象按给定键名的值排序，支持中英文、数字。

sortArrayOfObjectByKey<T extends Record<string, any>>(array: Array<T>, key: keyof T, order?: Order): Array<T>

参数

返回值

返回处理后的新数组

示例

import { sortArrayOfObjectByKey } from '@klweb/utils'

// 按字母 A-Z 排序
const arr1 = [
    { letter: 'b'}, 
    { letter: 'D'}, 
    { letter: 'A'}, 
    { letter: 'c'}, 
]; 
const sortArr1 = sortArrayOfObjectByKey(arr1, 'letter');
console.log(sortArr1)
// Expected output: [{ letter: 'A'},  { letter: 'b'},  { letter: 'C'},  { letter: 'D'}]

// 按数字排序
const arr2 = [
    { num: 3}, 
    { num: 2}, 
    { num: 1}, 
    { num: 4}, 
]; 
const sortArr2 = sortArrayOfObjectByKey(arr2, 'num');
console.log(sortArr2)
// Expected output: [{ num: 1 }, { num: 2}, { num: 3}, { num: 4}]

// 按中文排序
const arr3 = [
    { name: '白雪'}, 
    { name: '阿力'}, 
    { name: '陈九'},
]; 
const sortArr3 = sortArrayOfObjectByKey(arr3, 'name');
console.log(sortArr3)
// Expected output: [{ name: '阿力'}, { name: '白雪'}, { name: '陈九'}]

🔸 deepCopy

深拷贝函数。

deepCopy<T>(obj: T): T

该函数实现了深拷贝的功能，可以处理数组和对象的深度复制，避免了在复制过程中出现循环引用的问题。同时，使用类型断言来确保返回值的类型与输入的类型一致。

参数

返回值

返回新数组、对象或原始值

示例

import { deepCopy } from '@klweb/utils'

const obj = {
    a: 1,
    b: 2,
    d: { 
        a: 5, 
        b: 0 
    }
};

const newObj = deepCopy(obj);
console.log(newObj)
// Expected output: { a: 1, b: 2, d: { a: 5, b: 0 } }

🔸 deepMerge

深度合并对象

deepMerge<T extends Record<string, any>>(...objects: Array<T>): T

参数

返回值

返回新对象

示例

import { deepMerge } from '@klweb/utils'

const obj1 = {
    a: 1,
    b: 2,
    d: { 
        a: 5, 
        b: 0 
    }
};

const obj2 = {
    a: 4,
    c: 3,
    d: {
        a: 2,
        b: 1
    }
};

const mergeObj = deepMerge(obj1, obj2);
console.log(mergeObj)
// Expected output: { a: 4, b: 2, c: 3, d: { a: 2, b: 1 } }

🔸 sealMerge

密封一个对象，阻止其扩展并且原有属性不可配置，但属性值仍可写入。

sealMerge<T extends Record<string, any>>(target: T, source: T): void

使用场景：object1 和 object2 两个对象进行合并，object1 中的属性不可配置也不可扩展，只会合并 object2 中的与 object1 具有相同属性名的值，object2 中的其它键值不会合并到 object1 中。

参数

返回值

无返回值

示例

import { sealMerge } from '@klweb/utils'

const obj1 = {
    a: 1,
    b: 2
};

const obj2 = {
    a: 4,
    b: 8,
    c: 3,
    d: 6
};

sealMerge(obj1, obj2);
console.log(obj1)
// Expected output: { a: 4, b: 8 }

🔸 randomHexColor

随机生成 HEX 十六进制颜色值

randomHexColor(): string

参数

无

返回值

返回十六进制色值

示例

import { randomHexColor } from '@klweb/utils'

console.log(randomHexColor())
// Expected output: #ff03cc

console.log(randomHexColor())
// Expected output: #ba0efc

🔸 hexToRgb

HEX 颜色 转 RGB 颜色

hexToRgb(hexColor: string): string

参数

返回值

返回 RGB 颜色

示例

import { hexToRgb } from '@klweb/utils'

const rgb = hexToRgb('#ffffff');
console.log(rgb)
// Expected output: rgb(255, 255, 255)

🔸 rgbToHex

RGB 颜色 转 HEX 颜色

rgbToHex(r: number, g: number, b: number): string

参数

返回值

返回 HEX 颜色

示例

import { rgbToHex } from '@klweb/utils'

const hex = rgbToHex(255, 255, 255);
console.log(hex)
// Expected output: #ffffff

未完待续...