前言

数组操作是开发中的高频操作，如去重、合并、差集、交集等。@pura/harmony-utils 的 ArrayUtil 封装了丰富的数组操作方法，简化了集合运算。本文将从API说明、代码实战、进阶用法、常见问题等多个维度进行全面讲解，帮助开发者快速掌握并应用到实际项目中。

一、ArrayUtil操作核心API

ArrayUtil 提供了以下集合操作方法：

方法	说明	返回类型	使用场景
distinct(array)	数组去重	T[]	数据清洗
union(arr1, arr2)	并集	T[]	合并去重
intersection(arr1, arr2)	交集	T[]	共同元素
difference(arr1, arr2)	差集	T[]	独有元素
contains(array, value)	是否包含	boolean	存在检查
isEmpty(array)	是否为空	boolean	空值判断

1.1 核心特性

• 简洁易用：封装复杂逻辑为一行调用，降低使用门槛
• 类型安全：完整的TypeScript类型定义，编译期即可发现错误
• 异常处理：内置异常捕获机制，避免运行时崩溃
• 集合运算：支持并集、交集、差集等数学集合运算

1.2 集合运算对照

运算	方法	图示	说明
并集	union	A∪B	合并去重
交集	intersection	A∩B	共同元素
差集	difference	A-B	A中独有

二、完整使用步骤

2.1 安装依赖

ohpm install @pura/harmony-utils

2.2 数组去重

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

Button('数组去重')
  .width('100%')
  .onClick(() => {
    try {
      let arr = [1, 2, 2, 3, 3, 4];
      let distinct = ArrayUtil.distinct(arr);
      this.result = `原数组: [${arr}]\n去重后: [${distinct}]`;
    } catch (e) {
      this.result = '异常: ' + e;
    }
  })

2.3 集合运算

Button('集合运算')
  .width('100%')
  .onClick(() => {
    try {
      let arr1 = [1, 2, 3];
      let arr2 = [2, 3, 4];
      let union = ArrayUtil.union(arr1, arr2);
      let inter = ArrayUtil.intersection(arr1, arr2);
      let diff = ArrayUtil.difference(arr1, arr2);
      this.result = `并集: [${union}]\n交集: [${inter}]\n差集: [${diff}]`;
    } catch (e) {
      this.result = '异常: ' + e;
    }
  })

三、完整页面示例

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

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

  build() {
    Column({ space: 12 }) {
      Button('去重').width('100%').onClick(() => {
        this.result = `去重: [${ArrayUtil.distinct([1, 2, 2, 3])}]`;
      });
      Button('集合运算').width('100%').onClick(() => {
        let a = [1, 2, 3], b = [2, 3, 4];
        this.result = `并集: [${ArrayUtil.union(a, b)}]\n交集: [${ArrayUtil.intersection(a, b)}]`;
      });
      Text(this.result).fontSize(14).fontColor('#333333')
    }
    .padding(16)
  }
}

四、进阶用法

4.1 标签去重

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

function mergeTags(existingTags: string[], newTags: string[]): string[] {
  return ArrayUtil.union(existingTags, newTags);
}

4.2 权限比较

function findNewPermissions(current: string[], required: string[]): string[] {
  return ArrayUtil.difference(required, current);
}

五、注意事项

1. 引用类型：distinct对对象数组可能需要自定义比较
2. 顺序保留：去重后保留首次出现的元素顺序
3. 空数组：方法对空数组安全，不会抛异常
4. 初始化依赖：使用前需确保 AppUtil.init() 已调用
5. 性能考虑：大数组操作时注意性能影响

六、常见问题

Q1: distinct对对象数组有效吗？

默认按引用比较，不同引用的相同内容对象不会被去重。

Q2: union会改变原数组吗？

不会，所有方法返回新数组，原数组不变。

Q3: difference的顺序重要吗？

重要，difference(A, B)返回A中有但B中没有的元素。

Q4: contains和Array.includes有什么区别？

contains增加了null安全检查，对null/undefined数组不会报错。

总结

ArrayUtil 的集合操作方法为数组处理提供了便捷支持。本文详细介绍了核心API、使用步骤、完整示例、进阶用法以及常见问题的解决方案。开发者可以利用这些方法简化去重、集合运算等操作。

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