es-toolkit 的 meanBy 函数按取值函数计算数组平均值的完整指南【免费下载链接】es-toolkitA modern JavaScript utility library thats 2-3 times faster and up to 97% smaller, a major upgrade to lodash.项目地址: https://gitcode.com/GitHub_Trending/es/es-toolkitmeanBy是 es-toolkit 数学模块中用于先映射、再求平均的高阶聚合函数它对数组的每个元素应用getValue函数将元素转换为数值再计算这些数值的平均值。当需要从对象数组中提取某个属性求均值、或对元素做变换后再求均值时meanBy比手动reduce更简洁直观。读完本文你将掌握meanBy的调用方式、参数语义、空数组的NaN边界行为、底层实现原理以及它与mean、sumBy和 lodash 兼容版本之间的关系。meanBy 是什么meanBy的定义与mean一脉相承mean直接对数值数组求平均而meanBy允许你传入一个取值函数将任意类型T的数组元素映射为number后再求平均。const average meanBy(items, getValue);它的核心签名如下function meanByT(items: readonly T[], getValue: (element: T) number): number;items任意类型的只读数组元素类型为TgetValue从每个元素中提取数值的回调函数返回值getValue计算出的所有数值的平均值若数组为空则返回NaN。典型的使用场景包括从对象数组中计算某个数值属性的平均值如平均年龄、平均分数对元素做变换后再求平均值如字符串的平均长度在统计、报表、图表数据预处理中批量计算聚合指标。使用方法导入方式与 es-toolkit 其他数学函数一致import { meanBy } from es-toolkit/math;计算对象数组特定属性的平均值// オブジェクト配列から特定のプロパティの平均を計算します const people [{ age: 23 }, { age: 25 }, { age: 27 }]; const averageAge meanBy(people, person person.age); // averageAgeは25になります ((23 25 27) / 3 75 / 3 25)getValue逐个取出person.age得到[23, 25, 27]平均值为25。这一模式等价于people.reduce((sum, p) sum p.age, 0) / people.length但语义更聚焦于求平均本身。计算字符串长度的平均值// 文字列の長さの平均を計算します const words [apple, banana, cherry]; const averageLength meanBy(words, word word.length); // averageLengthは約5.67になります ((5 6 6) / 3 ≈ 5.67)这里元素类型T是stringgetValue将每个单词映射为其长度得到(5 6 6) / 3 ≈ 5.67。空数组返回 NaN// 空の配列の場合はNaNを返します const emptyResult meanBy([], x x); // emptyResultはNaNになりますmeanBy对空数组返回NaN这一点与mean一致而与sumBy不同sumBy对空数组返回0。使用时应先判断数组是否为空或接受NaN作为无数据的信号。参数与返回值项目说明itemsreadonly T[]参与平均计算的数组getValue(element: T) number从每个元素中提取数值的函数返回值number按getValue计算出的所有数值的平均值空数组返回NaN源码实现基于 sumBy 的组合meanBy的实现非常精简完整源码位于 src/math/meanBy.tsimport { sumBy } from ./sumBy; export function meanByT(items: readonly T[], getValue: (element: T) number): number { return sumBy(items, item getValue(item)) / items.length; }从源码结构可以看出两个关键实现事实它建立在sumBy之上先用sumBy对每个元素应用getValue并累加再除以items.length。sumBy的实现位于 src/math/sumBy.ts内部是一个普通for循环累加没有使用reduce从而避免了额外的函数调用开销export function sumByT(items: readonly T[], getValue: (element: T, index: number) number): number { let result 0; for (let i 0; i items.length; i) { result getValue(items[i], i); } return result; }注意sumBy的getValue回调会收到第二个参数index从 0 开始而meanBy在转发时只传了元素本身因此meanBy的getValue仅接收元素一个参数。空数组的NaN源自除以零当items为空时sumBy返回0而0 / 0在 JavaScript 中结果为NaN这与 src/math/mean.ts 中mean的实现sum(nums) / nums.length保持完全一致的行为。也就是说空数组返回NaN并非显式判断而是0 / 0的自然结果。测试用例验证仓库为meanBy提供了单元测试见 src/math/meanBy.spec.tsdescribe(meanBy, () { it(calculates the mean of values extracted from objects, () { const result meanBy([{ a: 1 }, { a: 2 }, { a: 3 }], x x.a); expect(result).toEqual(2); }); it(returns NaN for empty arrays, () { type Person { name: string; age: number }; const people: Person[] []; expect(meanBy(people, x x.age)).toEqual(NaN); }); });两个用例分别验证了对象属性求均值与空数组返回NaN这两个文档承诺的核心行为与官方文档描述一一对应可以作为使用时的行为契约参考。meanBy 与 mean、sumBy 的关系es-toolkit 的数学模块导出清单见 src/math/index.ts中这三个函数形成了清晰的层次函数输入空数组行为定位meanreadonly number[]NaN直接对数值数组求平均meanByreadonly T[] 取值函数NaN映射后再求平均sumByreadonly T[] 取值函数0映射后求和meanBy的底层依赖因此若你的数据已经是数值数组直接用mean即可若需要先提取或变换属性则用meanBy若只需要总和而不需要平均值应选择sumBy空数组时返回0而不是NaN在累加场景中更友好。lodash 兼容版 meanByes-toolkit 还在es-toolkit/compat入口下提供了与 lodash 行为对齐的兼容版本实现位于 src/compat/math/meanBy.ts其iteratee参数支持更丰富的简写形式传入函数从元素中提取数值如x x.a传入字符串键名按属性路径取值如a传入数组[key, value]匹配具有指定键值对的元素传入对象匹配包含指定属性的元素不传iteratee时默认使用identity直接对元素本身求平均此时行为等同于对数值数组求mean。该版本还放宽了输入类型接受ArrayLikeT | null | undefined并对缺失属性做了特殊处理当某个元素的属性缺失或为undefined时按0计入分子但仍计入分母即数组长度例如meanBy([{ a: 1 }, {}], a)的结果是0.5若所有值都为undefined则结果仍为NaN。对应的行为测试见 src/compat/math/meanBy.spec.ts其中还覆盖了类数组对象{ 0: {...}, 1: {}, length: 2 }等边界输入。核心的meanBy非兼容版通过 src/math/index.ts 导出并随es-toolkit/math子路径对外提供兼容版则通过es-toolkit/compat入口提供便于从 lodash 迁移的代码无缝替换。使用建议与注意事项空数组处理meanBy对空数组返回NaN。在统计报表等场景中建议先判断items.length 0再决定展示占位值还是直接展示NaN。回调应返回 numbergetValue的返回值会被直接累加请确保它总是返回数值返回undefined、字符串等类型会得到不符合预期的结果。与sumBy搭配如果你同时需要总和与平均值可以基于一次sumBy的结果自行除以长度避免对同一数组遍历两次。从 lodash 迁移若你的代码原先依赖 lodash 的meanBy简写语法如meanBy(objects, a)应改用es-toolkit/compat的兼容版本标准es-toolkit/math的meanBy只接受函数形式的取值器。延伸阅读meanBy 源码 与 meanBy 单元测试mean 源码数值数组直接求平均sumBy 源码meanBy的底层求和实现数学模块导出清单meanBy所在的完整数学函数集合compat 版 meanBy 源码支持 lodash 简写语法的兼容实现数学模块英文参考文档 与日文参考文档【免费下载链接】es-toolkitA modern JavaScript utility library thats 2-3 times faster and up to 97% smaller, a major upgrade to lodash.项目地址: https://gitcode.com/GitHub_Trending/es/es-toolkit创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考