前言

对象拷贝和合并是开发中的常见操作，深拷贝避免引用共享，对象合并实现配置叠加。@pura/harmony-utils 的 ObjectUtil 封装了对象拷贝和合并方法。本文将从API说明、代码实战、进阶用法、常见问题等多个维度进行全面讲解，帮助开发者快速掌握并应用到实际项目中。

一、ObjectUtil拷贝合并核心API

ObjectUtil 提供了以下拷贝合并方法：

方法	说明	返回类型	使用场景
deepClone(obj)	深拷贝	T	避免引用共享
shallowClone(obj)	浅拷贝	T	浅层复制
merge(target, ...sources)	合并对象	Object	配置叠加
isEmpty(obj)	对象是否为空	boolean	空值判断
isEqual(obj1, obj2)	对象是否相等	boolean	值比较

1.1 核心特性

• 简洁易用：封装复杂逻辑为一行调用，降低使用门槛
• 类型安全：完整的TypeScript类型定义，编译期即可发现错误
• 异常处理：内置异常捕获机制，避免运行时崩溃
• 深拷贝：递归拷贝所有层级，避免引用共享

1.2 深拷贝与浅拷贝对比

特性	深拷贝	浅拷贝
嵌套对象	独立副本	共享引用
性能	较慢	较快
修改影响	互不影响	嵌套对象互相影响
适用场景	数据隔离	简单复制

二、完整使用步骤

2.1 安装依赖

ohpm install @pura/harmony-utils

2.2 深拷贝

import { ObjectUtil } from '@pura/harmony-utils';

Button('深拷贝')
  .width('100%')
  .onClick(() => {
    try {
      let original = { name: '张三', scores: [90, 85, 92] };
      let cloned = ObjectUtil.deepClone(original);
      cloned.scores[0] = 100;
      this.result = `原对象scores[0]: ${original.scores[0]}\n拷贝scores[0]: ${cloned.scores[0]}\n✅ 深拷贝互不影响`;
    } catch (e) {
      this.result = '异常: ' + e;
    }
  })

2.3 对象合并

Button('对象合并')
  .width('100%')
  .onClick(() => {
    try {
      let defaults = { theme: 'light', fontSize: 14, lang: 'zh' };
      let user = { theme: 'dark', fontSize: 16 };
      let merged = ObjectUtil.merge(defaults, user);
      this.result = `默认: ${JSON.stringify(defaults)}\n用户: ${JSON.stringify(user)}\n合并: ${JSON.stringify(merged)}`;
    } catch (e) {
      this.result = '异常: ' + e;
    }
  })

三、完整页面示例

import { ObjectUtil } from '@pura/harmony-utils';

@Entry
@Component
struct CloneDemo {
  @State result: string = '';

  build() {
    Column({ space: 12 }) {
      Button('深拷贝').width('100%').onClick(() => {
        let obj = { name: '张三', scores: [90, 85] };
        let clone = ObjectUtil.deepClone(obj);
        clone.scores[0] = 100;
        this.result = `原: ${obj.scores[0]}, 拷贝: ${clone.scores[0]}`;
      });
      Button('对象合并').width('100%').onClick(() => {
        let a = { x: 1, y: 2 };
        let b = { y: 3, z: 4 };
        this.result = JSON.stringify(ObjectUtil.merge(a, b));
      });
      Text(this.result).fontSize(14).fontColor('#333333')
    }
    .padding(16)
  }
}

四、进阶用法

4.1 配置管理

import { ObjectUtil } from '@pura/harmony-utils';

const DEFAULT_CONFIG = {
  theme: 'light',
  fontSize: 14,
  language: 'zh-CN',
  notifications: true,
};

function loadConfig(userConfig: Partial<typeof DEFAULT_CONFIG>): typeof DEFAULT_CONFIG {
  return ObjectUtil.deepClone(ObjectUtil.merge(DEFAULT_CONFIG, userConfig));
}

4.2 表单数据重置

function resetForm(original: FormData): FormData {
  return ObjectUtil.deepClone(original);
}

五、注意事项

1. 循环引用：深拷贝包含循环引用的对象可能栈溢出
2. 特殊对象：Date、RegExp等特殊对象的深拷贝行为需注意
3. 函数属性：函数通常不会被深拷贝
4. 初始化依赖：使用前需确保 AppUtil.init() 已调用
5. 性能考虑：大对象深拷贝可能较慢

六、常见问题

Q1: 深拷贝对Date对象有效吗？

取决于实现，部分深拷贝会将Date转为字符串。

Q2: merge是深合并还是浅合并？

取决于实现，通常第一层是深合并，嵌套层可能只替换。

Q3: isEqual对数组有效吗？

有效，isEqual会递归比较数组的每个元素。

Q4: deepClone对Map和Set有效吗？

标准JSON深拷贝不支持Map/Set，需要特殊处理。

总结

ObjectUtil 的拷贝和合并方法为对象操作提供了便捷支持。本文详细介绍了核心API、使用步骤、完整示例、进阶用法以及常见问题的解决方案。开发者可以利用这些方法实现数据隔离、配置管理等功能。

本文基于 @pura/harmony-utils 工具库，更多功能请参考官方文档与后续系列文章。