collect.js `mapToGroups()` 方法深度解析:将集合元素映射为键值分组对象的实用指南

原创2026-10-14 17:20:291,342 阅读
文章标签:开发工具

collect.js mapToGroups() 方法深度解析:将集合元素映射为键值分组对象的实用指南

导读

本文深入讲解 collect.js 中的 mapToGroups() 方法。该方法会遍历集合中的每一个元素,将其交给回调函数处理,并把回调返回的 <a href="https://link.gitcode.com/i/778bddf084c95595ff286cea40fd990c" target="_blank">key, value] 键值对累积成一个以分组键为属性名的普通 JavaScript 对象(每个键对应的值是一个数组)。读完本文,你将掌握 mapToGroups() 的调用方式、回调约定、源码实现原理,以及它与 groupBy()、mapToDictionary()、mapWithKeys() 等相近方法的区别,并能在实际数据整理场景中正确选用合适的 API。文中全部示例均可直接复制运行,所有结论均有对应的[官方 API 文档、源码实现与单元测试作为依据。

方法速览

mapToGroups() 的核心语义可以概括为三句话:

  • 遍历集合:对集合中的每一项调用你提供的回调;
  • 回调返回键值对:回调必须返回一个形如 [key, value] 的二元数组(长度恰好为 2);
  • 累积成分组对象:具有相同 key 的 value 会被收集进同一个数组,最终得到一个普通对象。

在 index.d.ts 中,该方法的 TypeScript 签名被声明为:

/**
 * The mapToGroups method iterates through the collection and passes each value to the given callback.
 */
mapToGroups(fn: Function): Collection<any>;

也就是说,它接收一个回调函数 fn,并返回一个新的 Collection 实例。这个类型签名中返回值标注为 Collection<any>,说明结果集合的内容完全由你的回调决定——这是这类“映射式”方法共有的特点。

基本用法:从文档示例说起

官方文档示例

官方 API 文档给出的入门示例如下:

const collection = collect([
  { id: 1, name: 'A' },
  { id: 2, name: 'B' },
  { id: 3, name: 'C' },
  { id: 4, name: 'B' },
]);

const groups = collection.mapToGroups((item, key) => [item.name, item.id]);

// {
//   A: [1],
//   B: [2, 4],
//   C: [3],
// }

这里原始集合是 4 个对象元素,回调 (item, key) => [item.name, item.id] 对每个元素做两件事:

  1. 取出 item.name 作为分组键;
  2. 取出 item.id 作为该分组内收集的值。

因此,两个 name 为 'B' 的元素(id 分别为 2 和 4)被归入同一个 B 分组,其值数组为 [2, 4];而 'A' 与 'C' 各自只有一个元素,所以值数组各只有一个成员。最终结果不是数组,而是一个普通对象。

回调的两个参数

从上面的示例可以看到,回调接收两个参数:

参数 含义
item 当前正在处理的集合元素
key 该元素在集合中的下标(数组索引)或键名(对象键)

需要说明的是,虽然文档示例中的回调声明了第二个参数 key,但在绝大多数分组场景下你只会用到第一个参数 item——分组键通常来自元素自身的某个属性或字段。第二个参数在“按元素位置分组”这类特殊需求下才会派上用场。

回调返回值约定

mapToGroups() 对回调返回值有严格约定:必须返回一个长度为 2 的数组,其中第一项作为分组键,第二项作为收集的值。这也是它在实现上与其他“map 系列”方法最大的共同点(详见下文源码分析)。

源码实现与底层原理

完整源码

src/methods/mapToGroups.js 的完整实现非常简洁,去掉空行后不足 15 行:

'use strict';

module.exports = function mapToGroups(fn) {
  const collection = {};

  this.items.forEach((item, key) => {
    const [keyed, value] = fn(item, key);

    if (collection[keyed] === undefined) {
      collection[keyed] = [value];
    } else {
      collection[keyed].push(value);
    }
  });

  return new this.constructor(collection);
};

逐步拆解

  1. 初始化空对象:const collection = {} 用于累积最终的分组结果,它是一个普通对象而非数组。
  2. 遍历集合:通过 this.items.forEach((item, key) => ...) 遍历内部存储的元素。this.items 是 Collection 实例在构造时保存的数据载体(见 src/index.js),可以是数组,也可以是对象。
  3. 解构回调返回值:const [keyed, value] = fn(item, key) 用数组解构语法取出回调返回二元数组的两个成员——keyed 作为分组键,value 作为待收集的值。
  4. 分组累积:如果 collection[keyed] 尚不存在(undefined),则创建只含该值的数组 [value];否则直接把 value push 进已有数组。这一步保证了同一分组下所有值都能被完整保留。
  5. 返回新的集合:return new this.constructor(collection) 把结果对象包装成新的 Collection 实例返回。这里使用 this.constructor 而非硬编码类名,是为了让子类继承时仍能返回正确类型的实例。

方法是如何被挂载的

mapToGroups 并不是一个独立函数,而是被挂载到 Collection 原型上供所有实例调用,见 src/index.js:

Collection.prototype.mapToGroups = require('./methods/mapToGroups');

同时在 dist/index.js(构建产物)中也有完全一致的挂载语句。从构建流程(package.json)看,源码会先经过 Babel 转译到 dist/,再打包为浏览器可用的 build/collect.js 与 build/collect.min.js,因此无论你通过 npm、CDN 还是打包产物使用,mapToGroups() 的行为都是一致的。

时间复杂度与内存特点

从实现可以推断其复杂度特征:

  • 时间:仅对集合做一次 forEach 遍历,每次回调为常数时间操作,因此整体为 O(n),其中 n 是集合元素个数;
  • 空间:额外维护一个分组对象,最坏情况下(每个元素一个分组)为 O(n);
  • 值永不丢失:由于使用“首次创建数组、后续 push”的策略,同一分组下的多个值会全部保留,不会像某些“按键覆盖”的实现那样丢失重复值。

官方单元测试验证

test/methods/mapToGroups_test.js 中提供了该方法的回归测试,与文档示例几乎一一对应:

'use strict';

module.exports = (it, expect, collect) => {
  it('should map a collection to groups', () => {
    const data = collect([
      { id: 1, name: 'A' },
      { id: 2, name: 'B' },
      { id: 3, name: 'C' },
      { id: 4, name: 'B' },
    ]);

    const groups = data.mapToGroups(item => [item.name, item.id]);

    expect(groups.all()).to.eql({
      A: [1],
      B: [2, 4],
      C: [3],
    });
  });
};

这个测试从三个层面锁定了方法的行为契约:

  1. 输入:由 4 个带 id 与 name 字段的对象组成的集合;
  2. 回调:item => [item.name, item.id](注意这里没有使用第二个参数,说明它是可选的);
  3. 断言:通过 groups.all() 取出底层数据(src/methods/all.js 直接返回 this.items),并与期望的普通对象做深比较,确认分组键与值数组完全正确。

整个测试在 npm test(实际执行 mocha test/tests.js,见 package.json)时会被加载运行,确保该方法不会在后续迭代中发生行为回退。

实战场景:让结果更顺手

场景一:分组后直接读取指定组的全部值

const orders = collect([
  { orderId: 1001, region: '华东' },
  { orderId: 1002, region: '华南' },
  { orderId: 1003, region: '华东' },
]);

const byRegion = orders.mapToGroups(item => [item.region, item.orderId]);

byRegion.get('华东');
// => [1001, 1003]

由于返回的是 Collection 实例,你可以继续链式调用 get()、all()、count() 等任意集合方法。

场景二:将对象类型的集合按键名分组

mapToGroups() 同样适用于以对象为载体的集合。例如:

const stats = collect({
  mon: { score: 80 },
  tue: { score: 90 },
  wed: { score: 80 },
});

const groups = stats.mapToGroups((item, key) => [item.score, key]);

groups.all();
// {
//   80: ['mon', 'wed'],
//   90: ['tue'],
// }

此时回调的第二个参数 key 就派上了用场——它对应对象集合中的属性名。这一点与 src/index.js 中构造器对“数组或对象皆可作为 items”的支持保持一致。

场景三:借助 values() 丢弃分组键,只取分组结果

如果你不需要分组键,只想得到所有分组值的扁平数组,可以链式调用 values()(其实现见 src/methods/values.js,内部通过 helpers/values 提取对象的所有值):

const collection = collect([
  { id: 1, name: 'A' },
  { id: 2, name: 'B' },
  { id: 3, name: 'C' },
  { id: 4, name: 'B' },
]);

collection.mapToGroups(item => [item.name, item.id]).values().all();

// [
//   [1],
//   [2, 4],
//   [3],
// ]

与相似方法的区别:何时选谁

collect.js 提供了一组外观相似、语义却不同的“键值映射”方法。理清它们的差异,是正确选型的关键。

mapToGroups() vs groupBy()

这是最容易混淆的一对。groupBy() 的分组结果中,每个分组的值是包含完整原始元素的集合;而 mapToGroups() 中,每个分组的值是你通过回调挑选出来的单个值。

看 groupBy 的官方文档中的示例,groupBy('manufacturer') 得到的结果形如:

// {
//   IKEA: Collection {
//     items: [ { product: 'Chair', manufacturer: 'IKEA' }, { product: 'Desk', manufacturer: 'IKEA' } ],
//   },
//   'Herman Miller': Collection {
//     items: [ { product: 'Chair', manufacturer: 'Herman Miller' } ],
//   },
// }

也就是说 groupBy() 保留的是整条原始记录(完整对象),适合“分组后还要继续对组内完整元素做统计、排序、筛选”的场景;而 mapToGroups() 只保留你指定的字段,适合“分组后只要摘要值(如 id 列表)”的场景。另外从实现上看(src/methods/groupBy.js),groupBy() 还额外支持直接传字符串键名(内部借助 nestedValue 支持点号嵌套取值,例如 'a.b.c'),而 mapToGroups() 只接受回调函数,这是两者在输入形态上的显著差别。官方文档也明确提示:“如果你想按普通对象的键来分组,请使用 mapToGroups”(见 docs/api/groupBy.md)。

mapToGroups() vs mapToDictionary()

从源码看,src/methods/mapToDictionary.js 与 mapToGroups() 的实现几乎一模一样——同样遍历、同样解构二元数组、同样按 undefined 判断后创建数组或 push。两者的行为在当前版本中实质等价,可以视为同一语义的两个命名(前者对应 Laravel 的 mapToDictionary 语义)。其文档示例也给出完全一致的输出:

const groups = collection.mapToDictionary(item => [item.name, item.id]);

// {
//   a: [1],
//   b: [2, 4],
//   c: [3],
// }

mapToGroups() vs mapWithKeys()

mapWithKeys()(源码见 src/methods/mapWithKeys.js)同样接收返回二元数组的回调,但它的语义是按键值重建整个对象:collection<a href="https://link.gitcode.com/i/ccb10cd33448a9b8e38d43ccb57403bb" target="_blank">keyed] = value 是直接赋值覆盖,因此每个键只能保留一个值——若多个元素产生相同的键,后出现的会覆盖先出现的。与之相对,mapToGroups() 会把相同键的多个值累积进数组。此外 mapWithKeys() 在源码层面显式区分了数组与对象两种 items 形态分别遍历,而 mapToGroups() 统一使用 forEach。其官方[文档示例显示 mapWithKeys() 的结果是一一对应的键值对象而非分组数组。

mapToGroups() vs keyBy()

keyBy()(源码见 src/methods/keyBy.js)按指定键(字符串键名或回调)重新索引元素,值仍然是完整元素,且同一键下后出现的元素会覆盖前者(collection[keyValue || ''] = item)。它适合“以 id 为索引快速查表”的场景,与 mapToGroups() 的“值聚合”定位截然不同。

选型对照速查表

方法 回调要求 相同键下的行为 分组值的内容 典型用途
mapToGroups() 返回 [key, value] 二元数组 累积为数组(值不丢失) 回调挑选出的值 分组收集摘要值,如 id 列表
groupBy() 传字符串键名或回调 累积为子 Collection 完整原始元素 分组后继续处理整条记录
mapToDictionary() 返回 [key, value] 二元数组 累积为数组(与 mapToGroups 等价) 回调挑选出的值 同 mapToGroups 的别名用法
mapWithKeys() 返回 [key, value] 二元数组 后者覆盖前者 单个值 按键重建一一对应对象
keyBy() 传字符串键名或回调 后者覆盖前者 完整原始元素 以某键建立索引查表

使用要点与注意事项

  • 回调必须返回二元数组:返回长度不是 2 的数组或返回非数组,会因解构失败导致 keyed/value 不确定,破坏分组结果。这是该方法唯一的“硬性契约”。
  • 分组键会被 JavaScript 自动转成字符串:由于结果对象是普通对象,数字键(如示例中的 1、2)在对象属性名层面会以字符串存储,但通过 groups.get(1) 或 groups.all()[1] 访问时仍能正常工作。
  • 结果的顺序:分组键的出现顺序遵循 JavaScript 对象对整数键与字符串键的固有排序规则(整数键自动升序在前),如果你对键顺序敏感,建议用 keys()、sortKeys() 等方法显式排序,或改用 groupBy() 后按需处理。
  • 返回的是新的 Collection,不修改原集合:与 collect.js 的绝大多数方法一样,mapToGroups() 是纯函数式操作,原集合保持不变,方便链式调用与不可变数据处理。
  • 值为 undefined 的特殊情况:若回调返回的值恰好是 undefined,分组键对应的数组会被创建为 [undefined] 而非跳过该键——因为判断依据是 collection[keyed] === undefined 而非值本身。

小结

mapToGroups() 是 collect.js 中“把集合元素映射为分组对象”的核心工具:它接受一个返回 [key, value] 二元数组的回调,将相同键下的值聚合为数组,并以普通对象的形式返回一个新的 Collection。理解它的源码(src/methods/mapToGroups.js)、测试契约(test/methods/mapToGroups_test.js)以及与 groupBy()、mapToDictionary()、mapWithKeys()、keyBy() 的差异后,你就能在数据整理、报表聚合、前端列表分组等场景中做出正确的 API 选择,写出更简洁、可读、可维护的集合处理代码。

登录后查看全文
collect.js