es-toolkit 兼容层castArray完全指南将任意值安全转换为数组【免费下载链接】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-toolkitcastArray是 es-toolkit 的 Lodash 兼容层es-toolkit/compat提供的数组工具函数用于将任意值转换为数组值本身已是数组时原样返回否则将其包装进一个新数组。本指南基于仓库中日文参考文档 docs/ja/compat/reference/array/castArray.md 展开并结合 源码实现、测试用例 与 性能基准 深入讲解其语义细节、边界行为与在 Lodash 迁移场景下的实战用法。读完本文你将掌握castArray的全部调用形态、其与Array.from()的本质差异以及何时应该用原生写法替代它。castArray是什么保证任何值都是数组castArray的职责可以用一句话概括如果值不是数组就把它转换成一个数组。它常用于统一处理可能是单个值、也可能是数组的入参避免在业务代码里到处写Array.isArray(value) ? value : [value]这样的条件判断。在 es-toolkit 中它属于兼容层函数使用方式与 Lodash 保持一致const result castArray(value);从类型签名看见 castArray.tsexport function castArrayT(value?: T | readonly T[]): T[]入参value的类型为T | readonly T[]可选不传也可以返回类型恒为T[]即调用方可以确信拿到的一定是数组。安装与导入castArray从es-toolkit/compat子路径导入与 Lodash 的调用签名完全一致因此可以直接替换现有代码中的lodash/lodash-es导入而无须改写调用点参见 compat 迁移流程import { castArray } from es-toolkit/compat;该函数通过兼容层总入口导出见 src/compat/compat.ts 中的export { castArray } from ./array/castArray.ts;。使用方式与全部调用形态将非数组值转换为数组数字、字符串、对象等任意非数组值都会被包装进一个新数组import { castArray } from es-toolkit/compat; // 数字 → 数组 castArray(1); // 返回值: [1] // 字符串 → 数组 castArray(hello); // 返回值: [hello] // 对象 → 数组 castArray({ a: 1 }); // 返回值: [{ a: 1 }]已是数组的值原样返回如果入参已经是数组castArray会直接返回该数组本身按引用返回而非拷贝不会产生新数组import { castArray } from es-toolkit/compat; castArray([1, 2, 3]); // 返回值: [1, 2, 3] castArray([a, b]); // 返回值: [a, b]这一行为与 Lodash 完全一致也正因如此它比无论如何都[value]包装的写法更节省内存。null与undefined也会被包装与某些把空值转换成空数组的工具不同castArray会把null和undefined也当作普通值包进数组返回import { castArray } from es-toolkit/compat; castArray(null); // 返回值: [null] castArray(undefined); // 返回值: [undefined]无参数调用返回空数组不带任何参数调用时castArray返回空数组import { castArray } from es-toolkit/compat; castArray(); // 返回值: []这个无参返回[]的行为是castArray区别于普通[value]包装的关键点之一也是它语义略显复杂的原因。参数与返回值项目说明参数valueT \| readonly T[]可选。要转换为数组的值不提供参数时返回空数组。返回值T[]。入参已是数组时返回该数组本身否则返回包含入参值的新数组。值得注意参数类型允许传入readonly T[]只读数组而返回类型收敛为可写的T[]——在 TypeScript 下把只读数组传给castArray后拿到的结果可直接按可变数组使用这在把 readonly 字段归一化为数组的典型场景中非常顺手。源码实现解析castArray的完整实现只有几行见 src/compat/array/castArray.tsexport function castArrayT(value?: T | readonly T[]): T[] { if (arguments.length 0) { return []; } return Array.isArray(value) ? value : ([value] as T[]); }实现逻辑分两步无参检测通过arguments.length 0判断是否传入了参数。这与value undefined的判断有本质区别——显式传入undefined时arguments.length为 1会走包装分支返回[undefined]而真正不传参时才返回[]。正是这一细节使得文档特别提醒该函数因无参数处理和undefined处理而行为复杂。数组检测用原生Array.isArray(value)判断。命中则按引用返回原数组未命中则用数组字面量[value]包装并借助as T[]断言完成类型收敛因为[value]会被推断为(T | readonly T[])[]需要收紧为T[]。整个函数不依赖任何内部工具或副作用完全由arguments、Array.isArray与数组字面量三种原生机制组合而成。测试用例如何验证行为仓库中的 castArray.spec.ts 完整覆盖了上述三类行为且其用例直接对标 Lodash 官方测试文件头注释标明参考自 lodash 的test/castArray.spec.jsit(should wrap non-array items in an array, () { const falsey [false, null, undefined, 0, NaN, ]; const values [...falsey, true, 1, a, { a: 1 }]; const expected values.map(value [value]); const actual values.map(value castArray(value)); expect(actual).toEqual(expected); }); it(should return array values by reference, () { const array [1]; expect(castArray(array)).toBe(array); }); it(should return an empty array when no arguments are given, () { expect(castArray()).toEqual([]); });三个测试用例分别锁定三条契约假值也会被包装false、null、undefined、0、NaN、这些假值全部得到[value]包装不存在被过滤或丢弃的情况数组按引用返回使用toBe严格引用相等断言证明返回的就是原数组对象而不是拷贝无参返回空数组castArray()严格等于[]。此外castArray在兼容层内部也被其他函数复用例如 omitBy.spec.ts 中用它把属性名统一归一化为数组这正是该函数在真实业务中的典型用法。性能对比基准仓库在 benchmarks/performance/castArray.bench.ts 中提供了与 Lodash 的同函数基准对比测试分别用数字、数组和无参三种形态调用双方实现bench(es-toolkit/castArray, () { castArrayToolkit(1); castArrayToolkit([1]); castArrayToolkit(); }); bench(lodash/castArray, () { castArrayLodash(1); castArrayLodash([1]); castArrayLodash(); });由于 es-toolkit 的实现仅包含arguments.length检查与Array.isArray分支没有 Lodash 版本中的额外兼容逻辑因此在基准环境下通常表现更快、打包体积更小——这也是整个es-toolkit/compat层行为一致但更轻更快设计目标的缩影参见 compat 设计原则。官方警告优先使用Array.from()或数组字面量值得特别强调的是官方文档在页面开头就放置了醒目的警告块并不推荐在新代码中优先使用castArray而是建议改用更现代、更明确的原生写法这个castArray函数因无参数处理和undefined处理而行为复杂。建议改用更清晰、更现代的Array.from()或条件式数组创建Array.isArray(value) ? value : [value]。两者对比场景castArray原生替代数字 → 数组castArray(1)→[1]Array.from([1])或[1]字符串 → 数组castArray(hello)→[hello][value]注意Array.from(hello)会拆成字符数组语义不同已是数组原样按引用返回Array.isArray(value) ? value : [value]undefined[undefined]Array.isArray(value) ? value : [value]同样得到[undefined]无参调用[]条件表达式无法处理无参情况需要单独判断核心差异在于无参行为castArray()返回[]而[value]写法在value未定义时会报错或产生[undefined]需要额外的arguments.length判断字符串差异Array.from(hello)会按可迭代对象拆分为[h,e,l,l,o]这与castArray(hello)返回[hello]完全不同——castArray对字符串是整体包装而非拆解可读性显式的Array.isArray(value) ? value : [value]把判断逻辑摊开在调用处意图一目了然。因此官方建议的取舍是在 Lodash 迁移场景中保留castArray以最小化改动而在新写代码时优先使用原生表达式。实战建议何时使用castArray综合文档与源码可以给出如下使用建议Lodash 迁移期如果你的代码库正在从lodash迁移到 es-toolkit且大量调用点使用了castArray直接替换导入路径即可import { castArray } from es-toolkit/compat行为完全一致无需修改调用点归一化入参需要把可能是单值、可能是数组、可能是 undefined的入参统一为数组时castArray一行即可完成尤其适合配合omitBy、pickBy等函数处理动态属性名列表新代码优先按官方警告采用Array.isArray(value) ? value : [value]或Array.from()获得更清晰、可预测的语义。无论选择哪种写法理解castArray在无参返回[]、undefined返回[undefined]、数组按引用返回三条边界上的精确定义都能帮助你避免在真实项目中踩到隐式转换的坑。【免费下载链接】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），仅供参考 
长河君 · 2026/9/16 14:19:45 · 阅读 1.2k es-toolkit 兼容层 `castArray` 完全指南：将任意值安全转换为数组
es-toolkit 兼容层castArray完全指南将任意值安全转换为数组【免费下载链接】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-toolkitcastArray是 es-toolkit 的 Lodash 兼容层es-toolkit/compat提供的数组工具函数用于将任意值转换为数组值本身已是数组时原样返回否则将其包装进一个新数组。本指南基于仓库中日文参考文档 docs/ja/compat/reference/array/castArray.md 展开并结合 源码实现、测试用例 与 性能基准 深入讲解其语义细节、边界行为与在 Lodash 迁移场景下的实战用法。读完本文你将掌握castArray的全部调用形态、其与Array.from()的本质差异以及何时应该用原生写法替代它。castArray是什么保证任何值都是数组castArray的职责可以用一句话概括如果值不是数组就把它转换成一个数组。它常用于统一处理可能是单个值、也可能是数组的入参避免在业务代码里到处写Array.isArray(value) ? value : [value]这样的条件判断。在 es-toolkit 中它属于兼容层函数使用方式与 Lodash 保持一致const result castArray(value);从类型签名看见 castArray.tsexport function castArrayT(value?: T | readonly T[]): T[]入参value的类型为T | readonly T[]可选不传也可以返回类型恒为T[]即调用方可以确信拿到的一定是数组。安装与导入castArray从es-toolkit/compat子路径导入与 Lodash 的调用签名完全一致因此可以直接替换现有代码中的lodash/lodash-es导入而无须改写调用点参见 compat 迁移流程import { castArray } from es-toolkit/compat;该函数通过兼容层总入口导出见 src/compat/compat.ts 中的export { castArray } from ./array/castArray.ts;。使用方式与全部调用形态将非数组值转换为数组数字、字符串、对象等任意非数组值都会被包装进一个新数组import { castArray } from es-toolkit/compat; // 数字 → 数组 castArray(1); // 返回值: [1] // 字符串 → 数组 castArray(hello); // 返回值: [hello] // 对象 → 数组 castArray({ a: 1 }); // 返回值: [{ a: 1 }]已是数组的值原样返回如果入参已经是数组castArray会直接返回该数组本身按引用返回而非拷贝不会产生新数组import { castArray } from es-toolkit/compat; castArray([1, 2, 3]); // 返回值: [1, 2, 3] castArray([a, b]); // 返回值: [a, b]这一行为与 Lodash 完全一致也正因如此它比无论如何都[value]包装的写法更节省内存。null与undefined也会被包装与某些把空值转换成空数组的工具不同castArray会把null和undefined也当作普通值包进数组返回import { castArray } from es-toolkit/compat; castArray(null); // 返回值: [null] castArray(undefined); // 返回值: [undefined]无参数调用返回空数组不带任何参数调用时castArray返回空数组import { castArray } from es-toolkit/compat; castArray(); // 返回值: []这个无参返回[]的行为是castArray区别于普通[value]包装的关键点之一也是它语义略显复杂的原因。参数与返回值项目说明参数valueT \| readonly T[]可选。要转换为数组的值不提供参数时返回空数组。返回值T[]。入参已是数组时返回该数组本身否则返回包含入参值的新数组。值得注意参数类型允许传入readonly T[]只读数组而返回类型收敛为可写的T[]——在 TypeScript 下把只读数组传给castArray后拿到的结果可直接按可变数组使用这在把 readonly 字段归一化为数组的典型场景中非常顺手。源码实现解析castArray的完整实现只有几行见 src/compat/array/castArray.tsexport function castArrayT(value?: T | readonly T[]): T[] { if (arguments.length 0) { return []; } return Array.isArray(value) ? value : ([value] as T[]); }实现逻辑分两步无参检测通过arguments.length 0判断是否传入了参数。这与value undefined的判断有本质区别——显式传入undefined时arguments.length为 1会走包装分支返回[undefined]而真正不传参时才返回[]。正是这一细节使得文档特别提醒该函数因无参数处理和undefined处理而行为复杂。数组检测用原生Array.isArray(value)判断。命中则按引用返回原数组未命中则用数组字面量[value]包装并借助as T[]断言完成类型收敛因为[value]会被推断为(T | readonly T[])[]需要收紧为T[]。整个函数不依赖任何内部工具或副作用完全由arguments、Array.isArray与数组字面量三种原生机制组合而成。测试用例如何验证行为仓库中的 castArray.spec.ts 完整覆盖了上述三类行为且其用例直接对标 Lodash 官方测试文件头注释标明参考自 lodash 的test/castArray.spec.jsit(should wrap non-array items in an array, () { const falsey [false, null, undefined, 0, NaN, ]; const values [...falsey, true, 1, a, { a: 1 }]; const expected values.map(value [value]); const actual values.map(value castArray(value)); expect(actual).toEqual(expected); }); it(should return array values by reference, () { const array [1]; expect(castArray(array)).toBe(array); }); it(should return an empty array when no arguments are given, () { expect(castArray()).toEqual([]); });三个测试用例分别锁定三条契约假值也会被包装false、null、undefined、0、NaN、这些假值全部得到[value]包装不存在被过滤或丢弃的情况数组按引用返回使用toBe严格引用相等断言证明返回的就是原数组对象而不是拷贝无参返回空数组castArray()严格等于[]。此外castArray在兼容层内部也被其他函数复用例如 omitBy.spec.ts 中用它把属性名统一归一化为数组这正是该函数在真实业务中的典型用法。性能对比基准仓库在 benchmarks/performance/castArray.bench.ts 中提供了与 Lodash 的同函数基准对比测试分别用数字、数组和无参三种形态调用双方实现bench(es-toolkit/castArray, () { castArrayToolkit(1); castArrayToolkit([1]); castArrayToolkit(); }); bench(lodash/castArray, () { castArrayLodash(1); castArrayLodash([1]); castArrayLodash(); });由于 es-toolkit 的实现仅包含arguments.length检查与Array.isArray分支没有 Lodash 版本中的额外兼容逻辑因此在基准环境下通常表现更快、打包体积更小——这也是整个es-toolkit/compat层行为一致但更轻更快设计目标的缩影参见 compat 设计原则。官方警告优先使用Array.from()或数组字面量值得特别强调的是官方文档在页面开头就放置了醒目的警告块并不推荐在新代码中优先使用castArray而是建议改用更现代、更明确的原生写法这个castArray函数因无参数处理和undefined处理而行为复杂。建议改用更清晰、更现代的Array.from()或条件式数组创建Array.isArray(value) ? value : [value]。两者对比场景castArray原生替代数字 → 数组castArray(1)→[1]Array.from([1])或[1]字符串 → 数组castArray(hello)→[hello][value]注意Array.from(hello)会拆成字符数组语义不同已是数组原样按引用返回Array.isArray(value) ? value : [value]undefined[undefined]Array.isArray(value) ? value : [value]同样得到[undefined]无参调用[]条件表达式无法处理无参情况需要单独判断核心差异在于无参行为castArray()返回[]而[value]写法在value未定义时会报错或产生[undefined]需要额外的arguments.length判断字符串差异Array.from(hello)会按可迭代对象拆分为[h,e,l,l,o]这与castArray(hello)返回[hello]完全不同——castArray对字符串是整体包装而非拆解可读性显式的Array.isArray(value) ? value : [value]把判断逻辑摊开在调用处意图一目了然。因此官方建议的取舍是在 Lodash 迁移场景中保留castArray以最小化改动而在新写代码时优先使用原生表达式。实战建议何时使用castArray综合文档与源码可以给出如下使用建议Lodash 迁移期如果你的代码库正在从lodash迁移到 es-toolkit且大量调用点使用了castArray直接替换导入路径即可import { castArray } from es-toolkit/compat行为完全一致无需修改调用点归一化入参需要把可能是单值、可能是数组、可能是 undefined的入参统一为数组时castArray一行即可完成尤其适合配合omitBy、pickBy等函数处理动态属性名列表新代码优先按官方警告采用Array.isArray(value) ? value : [value]或Array.from()获得更清晰、可预测的语义。无论选择哪种写法理解castArray在无参返回[]、undefined返回[undefined]、数组按引用返回三条边界上的精确定义都能帮助你避免在真实项目中踩到隐式转换的坑。【免费下载链接】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），仅供参考