collect.js `mapToGroups()` 方法深度解析:将集合元素映射为键值分组对象的实用指南
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] 对每个元素做两件事:
- 取出
item.name作为分组键; - 取出
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);
};
逐步拆解
- 初始化空对象:
const collection = {}用于累积最终的分组结果,它是一个普通对象而非数组。 - 遍历集合:通过
this.items.forEach((item, key) => ...)遍历内部存储的元素。this.items是Collection实例在构造时保存的数据载体(见 src/index.js),可以是数组,也可以是对象。 - 解构回调返回值:
const [keyed, value] = fn(item, key)用数组解构语法取出回调返回二元数组的两个成员——keyed作为分组键,value作为待收集的值。 - 分组累积:如果
collection[keyed]尚不存在(undefined),则创建只含该值的数组[value];否则直接把valuepush进已有数组。这一步保证了同一分组下所有值都能被完整保留。 - 返回新的集合:
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],
});
});
};
这个测试从三个层面锁定了方法的行为契约:
- 输入:由 4 个带
id与name字段的对象组成的集合; - 回调:
item => [item.name, item.id](注意这里没有使用第二个参数,说明它是可选的); - 断言:通过
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 选择,写出更简洁、可读、可维护的集合处理代码。