@shencom/utils-object

> 对象相关工具方法

Install

``sh
pnpm add @shencom/utils

or

pnpm add @shencom/utils-object
`

Basic Usage

`ts
import { CleanObject, DeepClone, DeepMerge, GetByPath, ObjectToArray, ObjectToUrlParams, OmitProps, PickProps } from '@shencom/utils';
// import { ObjectToUrlParams, DeepClone, DeepMerge, pickProps, OmitProps, CleanObject, GetByPath, ObjectToArray } from '@shencom/utils-object';
`

Methods

ObjectToUrlParams

- 说明: 对象转 url 参数
- 类型: (obj: Record): string
- 参数:
- obj - 需要转换的对象
- 示例:
`ts
ObjectToUrlParams({ a: 1, b: 2, c: '' }); // 'a=1&b=2&c='
ObjectToUrlParams({ a: 1, b: 2, c: 'aa' }); // 'a=1&b=2&c=aa'
ObjectToUrlParams({ a: 1, b: 2, c: 0 }); // 'a=1&b=2&c=0'
ObjectToUrlParams({ a: 1, b: 2, c: NaN }); // 'a=1&b=2&c=NaN'
ObjectToUrlParams({ a: 1, b: 2, c: true }); // 'a=1&b=2&c=true'
ObjectToUrlParams({ a: 1, b: 2, c: undefined, d: 3 }); // 'a=1&b=2&d=3'
ObjectToUrlParams({ a: 1, b: 2, c: -Infinity }); // 'a=1&b=2&c=-Infinity'
`

DeepClone

- 说明: 对象深拷贝，创建一个对象的完整副本
- 类型: (obj: T): T
- 参数:
- obj - 需要深拷贝的对象
- 示例:
`ts
const obj = { a: 1, b: { c: 2 } };
const cloned = DeepClone(obj);
// cloned = { a: 1, b: { c: 2 } }
// 修改 cloned.b.c 不会影响 obj.b.c

const arr = [1, { a: 2 }];
const clonedArr = DeepClone(arr);
// clonedArr = [1, { a: 2 }]
`

DeepMerge

- 说明: 对象深度合并，合并多个对象为一个新对象
- 类型: >(...objects: Record[]): T
- 参数:
- ...objects - 要合并的对象列表
- 示例:
`ts
const obj1 = { a: 1, b: { c: 2 } };
const obj2 = { b: { d: 3 }, e: 4 };

DeepMerge(obj1, obj2);
// { a: 1, b: { c: 2, d: 3 }, e: 4 }

DeepMerge({ a: 1 }, { b: 2 }, { c: 3 });
// { a: 1, b: 2, c: 3 }
`

ObjectToArray

- 说明: 对象转换为键值对数组，支持处理嵌套对象和不同的输出格式
- 类型: >(obj: T, options?: { nested?: boolean; format?: 'entries' | 'objects' }): Array<[string, any]> | Array<{ key: string; value: any }>
- 参数:
- obj - 要转换的对象
- options - 转换选项（可选）
- nested - 是否递归处理嵌套对象，默认为 false。设置为 true 时，会将嵌套对象展平，使用点号连接的路径表示键名
- format - 输出格式，可选值：
- 'entries' - 返回二维数组格式，类似 Object.entries()，默认值
- 'objects' - 返回对象数组格式，每个元素为 { key, value } 形式
- 返回值: 根据 format 参数返回不同格式的键值对数组
- 当 format 为 'entries' 时，返回 Array<[string, any]>
- 当 format 为 'objects' 时，返回 Array<{ key: string; value: any }>
- 示例:
`ts
// 默认形式 - 返回类似 Object.entries() 的结果
ObjectToArray({ a: 1, b: 2 });
// [['a', 1], ['b', 2]]

// 对象数组形式
ObjectToArray({ a: 1, b: 2 }, { format: 'objects' });
// [{ key: 'a', value: 1 }, { key: 'b', value: 2 }]

// 处理嵌套对象
ObjectToArray({ a: 1, b: { c: 2 } }, { nested: true });
// [['a', 1], ['b.c', 2]]

// 嵌套对象 + 对象数组形式
ObjectToArray({ a: 1, b: { c: 2 } }, { nested: true, format: 'objects' });
// [{ key: 'a', value: 1 }, { key: 'b.c', value: 2 }]
`

PickProps

- 说明: 从对象中选择指定的属性
- 类型: (obj: T, keys: K[]): Pick
- 参数:
- obj - 原始对象
- keys - 要选择的属性名数组
- 示例:
`ts
const obj = { a: 1, b: 2, c: 3 };

PickProps(obj, ['a', 'c']);
// { a: 1, c: 3 }
`

OmitProps

- 说明: 从对象中排除指定的属性
- 类型: (obj: T, keys: K[]): Omit
- 参数:
- obj - 原始对象
- keys - 要排除的属性名数组
- 示例:
`ts
const obj = { a: 1, b: 2, c: 3 };

OmitProps(obj, ['a', 'c']);
// { b: 2 }
`

CleanObject

- 说明: 清理对象中的空值，默认清理 null 和 undefined
- 类型: (obj: T, emptyValues?: (string | null | undefined)[]): Partial
- 参数:
- obj - 要清理的对象
- emptyValues - 要清理的值列表，默认为 [null, undefined]
- 示例:
`ts
const obj = { a: 1, b: null, c: undefined, d: '', e: 0 };

CleanObject(obj);
// { a: 1, d: '', e: 0 }

CleanObject(obj, [null, undefined, '']);
// { a: 1, e: 0 }
`

GetByPath

- 说明: 通过路径安全地访问对象的深层属性
- 类型: (obj: Record, path: string, defaultValue?: T): T | undefined
- 参数:
- obj - 要访问的对象
- path - 属性路径，使用点号或方括号表示
- defaultValue - 路径不存在时返回的默认值（可选）
- 示例:
`ts
const obj = { a: { b: { c: 1 } }, d: [{ e: 2 }] };

GetByPath(obj, 'a.b.c'); // 1
GetByPath(obj, 'd[0].e'); // 2
GetByPath(obj, 'a.b.d', 3); // 3 (默认值)
GetByPath(obj, 'x.y.z'); // undefined
``