@shencom/utils-object

对象相关工具方法

Install

pnpm add @shencom/utils

# or

pnpm add @shencom/utils-object

Basic Usage

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, string | number | boolean | undefined>): string
• 参数:
  • obj - 需要转换的对象
• 示例:

  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

• 说明: 对象深拷贝，创建一个对象的完整副本
• 类型: <T>(obj: T): T
• 参数:
  • obj - 需要深拷贝的对象
• 示例:

  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

• 说明: 对象深度合并，合并多个对象为一个新对象
• 类型: <T = Record<string, any>>(...objects: Record<string, any>[]): T
• 参数:
  • ...objects - 要合并的对象列表
• 示例:

  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

• 说明: 对象转换为键值对数组，支持处理嵌套对象和不同的输出格式
• 类型: <T extends Record<string, any>>(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 }>
• 示例:

  // 默认形式 - 返回类似 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

• 说明: 从对象中选择指定的属性
• 类型: <T extends object, K extends keyof T>(obj: T, keys: K[]): Pick<T, K>
• 参数:
  • obj - 原始对象
  • keys - 要选择的属性名数组
• 示例:

  const obj = { a: 1, b: 2, c: 3 };
    
  PickProps(obj, ['a', 'c']);
  // { a: 1, c: 3 }

OmitProps

• 说明: 从对象中排除指定的属性
• 类型: <T extends object, K extends keyof T>(obj: T, keys: K[]): Omit<T, K>
• 参数:
  • obj - 原始对象
  • keys - 要排除的属性名数组
• 示例:

  const obj = { a: 1, b: 2, c: 3 };
    
  OmitProps(obj, ['a', 'c']);
  // { b: 2 }

CleanObject

• 说明: 清理对象中的空值，默认清理 null 和 undefined
• 类型: <T extends object>(obj: T, emptyValues?: (string | null | undefined)[]): Partial<T>
• 参数:
  • obj - 要清理的对象
  • emptyValues - 要清理的值列表，默认为 [null, undefined]
• 示例:

  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

• 说明: 通过路径安全地访问对象的深层属性
• 类型: <T = any>(obj: Record<string, any>, path: string, defaultValue?: T): T | undefined
• 参数:
  • obj - 要访问的对象
  • path - 属性路径，使用点号或方括号表示
  • defaultValue - 路径不存在时返回的默认值（可选）
• 示例:

  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