es-toolkit 深度指南：使用 toPascalCaseKeys 递归转换对象与数组键名为 PascalCase-平芜编程栈

es-toolkit 深度指南：使用 toPascalCaseKeys 递归转换对象与数组键名为 PascalCase

【免费下载链接】es-toolkitA modern JavaScript utility library that's 2-3 times faster and up to 97% smaller, a major upgrade to lodash.项目地址: https://gitcode.com/GitHub_Trending/es/es-toolkit

toPascalCaseKeys是 es-toolkit 提供的一个对象工具函数，它接收对象、数组或原始值，返回一个所有键都被转换为 PascalCase（帕斯卡命名法）的新对象，并支持嵌套对象与数组内对象的递归转换。本文以 docs/ja/reference/object/toPascalCaseKeys.md 为核心，结合源码实现、类型定义与测试用例，完整讲解其用法、转换规则、底层原理与边界行为，帮助你在对接后端响应、规范数据模型等场景中直接落地使用。

什么是 PascalCase，以及为什么需要它

PascalCase（帕斯卡命名法）是一种命名约定：标识符中的每个单词首字母大写，单词之间不使用任何分隔符拼接，例如PascalCase、UserId、ContactInfo。

在实际开发中，数据源（如后端 API、数据库字段、第三方 SDK）往往使用snake_case（user_id）、camelCase（userId）或全大写常量（FIRST_NAME）等不同风格。当需要将这些数据统一为 PascalCase 以匹配前端类模型、序列化协议或团队规范时，toPascalCaseKeys可以一次性完成转换，无需手写遍历逻辑。

函数签名非常简单：

const pascalCased = toPascalCaseKeys(obj);

它不会修改原对象，而是返回一个键被转换后的新对象（具体见下文"返回新对象而非原地修改"的实现细节）。

安装与导入

toPascalCaseKeys位于es-toolkit/object子路径下，安装 es-toolkit 后即可按需导入：

import { toPascalCaseKeys } from 'es-toolkit/object';

该函数同时通过 src/object/index.ts 汇出，也可以从顶层入口或其他聚合入口引用。es-toolkit 支持按子路径导入，便于摇树优化（tree-shaking）以减小打包体积。

核心用法与转换规则

基本对象转换

最常见的用法是将一个对象的全部键转换为 PascalCase：

import { toPascalCaseKeys } from 'es-toolkit/object'; // 基本的オブジェクト変換 const obj = { user_id: 1, first_name: 'John', last_name: 'Doe' }; const result = toPascalCaseKeys(obj); // result 是 { UserId: 1, FirstName: 'John', LastName: 'Doe' }

三种键风格的转换结果

根据文档，键的转换遵循以下规则（文档中的示例均可在测试用例中得到验证）：

输入风格	转换规则	示例
`snake_case`	下划线分隔的单词各自首字母大写后拼接	`user_id`→`UserId`
`camelCase`	首字母大写，其余保持	`userId`→`UserId`
`UPPERCASE_KEYS`	整体小写后再按首字母大写处理	`FIRST_NAME`→`FirstName`、`LAST`→`Last`

// camelCase 与全大写键同样会被转换 const raw = { userId: 1, FIRST_NAME: 'JinHo', LAST: 'Yeom' }; const converted = toPascalCaseKeys(raw); // converted 是 { UserId: 1, FirstName: 'JinHo', Last: 'Yeom' }

从源码结构看，这一规则同时作用于运行时与类型层面：运行时由pascalCase字符串函数实现，类型层面则由ToPascalCaseKeys<T>中的条件类型（见下文"类型系统"一节）保证编译期推导，测试 toPascalCaseKeys.spec.ts 对as const字面量输入同时断言了运行结果与类型结果。

递归转换：嵌套对象与数组

toPascalCaseKeys的显著特点是递归处理：对象内部嵌套的对象、数组，以及数组内的对象元素，都会被逐层转换。

数组内对象的转换

// 数组内的对象同样会被转换 const users = [ { user_id: 1, first_name: 'John' }, { user_id: 2, first_name: 'Jane' }, ]; const convertedUsers = toPascalCaseKeys(users); // convertedUsers 是 [{ UserId: 1, FirstName: 'John' }, { UserId: 2, FirstName: 'Jane' }]

多层嵌套对象的转换

// 嵌套对象会被完整转换 const nested = { user_data: { user_id: 1, contact_info: { email_address: 'john@example.com', phone_number: '123-456-7890', }, }, }; const nestedResult = toPascalCaseKeys(nested); // nestedResult 是： // { // UserData: { // UserId: 1, // ContactInfo: { // EmailAddress: 'john@example.com', // PhoneNumber: '123-456-7890' // } // } // }

对象内部嵌套数组的场景同样受支持，测试 toPascalCaseKeys.spec.ts 验证了{ userList: [...] }会被转换为{ UserList: [...] }，数组元素内部的键也一并转换。

源码实现原理

toPascalCaseKeys的实现非常精简，核心逻辑位于 src/object/toPascalCaseKeys.ts，可分为三个分支：

export function toPascalCaseKeys<T>(obj: T): ToPascalCaseKeys<T> { // 1. 数组：逐元素递归 if (isArray(obj)) { return obj.map(item => toPascalCaseKeys(item)) as unknown as ToPascalCaseKeys<T>; } // 2. 普通对象：遍历键并递归转换值 if (isPlainObject(obj)) { const result = {} as ToPascalCaseKeys<T>; const keys = Object.keys(obj as Record<PropertyKey, any>); for (let i = 0; i < keys.length; i++) { const key = keys[i]; const pascalKey = pascalCase(key) as keyof typeof result; const convertedValue = toPascalCaseKeys((obj as Record<PropertyKey, any>)[key]); result[pascalKey] = convertedValue as ToPascalCaseKeys<T>[keyof ToPascalCaseKeys<T>]; } return result; } // 3. 其他值（原始值、Date、Map 等）：原样返回 return obj as ToPascalCaseKeys<T>; }

关键设计点：

数组分支：通过isArray判断后使用map对每个元素递归调用自身，保证数组中每个对象（以及对象内再次嵌套的结构）都被转换。
普通对象分支：通过isPlainObject判断（实现见 src/compat/predicate/isPlainObject.ts），仅对"纯对象"做键转换，避免误伤Date、Map、RegExp等内置类实例；使用Object.keys收集自有可枚举键，用pascalCase生成新键，并对值递归转换。
兜底分支：原始值（数字、字符串、布尔值、null、undefined）以及非纯对象直接原样返回。测试 toPascalCaseKeys.spec.ts 明确验证了123、'string'、null、undefined、true等输入均不被修改。
返回新对象而非原地修改：实现中显式创建了新的result对象并逐键填充，原对象不被改写；且新对象不继承原对象的原型，仅包含转换后的自有键。

pascalCase 的底层实现

键的转换最终由字符串函数pascalCase完成，位于 src/string/pascalCase.ts：

export function pascalCase(str: string): string { const words = getWords(str); return words.map(word => capitalize(word)).join(''); }

其流程分为两步：

分词：调用 src/string/words.ts 中的words函数，通过正则CASE_SPLIT_PATTERN（定义于 src/string/words.ts）将字符串拆分为单词。该正则使用 Unicode 属性转义，能识别小写序列、数字序列、连续大写字母（如缩写HTTP）、emoji 以及其他 Unicode 字符，因此camelCase、snake_case、kebab-case、HTTPRequest等混合风格都能被正确分词。
首字母大写拼接：对每个单词调用 src/string/capitalize.ts 将首字母转为大写、其余转为小写，最后用空字符串拼接。例如HTTPRequest会先被分为['HTTP', 'Request']，再转为HttpRequest。

这也解释了文档中UPPERCASE_KEYS（如FIRST_NAME）为何会变为FirstName：分词后得到['FIRST', 'NAME']，capitalize会将FIRST规整为First、NAME规整为Name。

类型系统：ToPascalCaseKeys<T>

toPascalCaseKeys的返回值类型是ToPascalCaseKeys<T>，定义于 src/types/ToPascalCaseKeys.ts。它是一个递归条件类型，与运行时行为严格对应：

非纯对象（NonPlainObject，如Date、Map、函数）：原样透传；
数组：映射为Array<ToPascalCaseKeys<T[number]>>，即对元素类型递归转换；
普通对象：对每个键应用AnyToPascal键转换，并对值类型递归转换；
其余类型：原样保留。

键的类型转换由三个条件类型协作完成（src/types/ToPascalCaseKeys.ts）：

SnakeToPascal<S>：递归处理snake_case，将下划线分隔的各段小写并首字母大写，如user_id→UserId；
CamelToPascal<S>：仅将首字母大写，处理camelCase→PascalCase；
AnyToPascal<S>：先判断是否包含下划线（走SnakeToPascal），否则判断是否为全大写（走Capitalize<Lowercase<S>>，即FIRST_NAME→FirstName），最后才走CamelToPascal。

测试 toPascalCaseKeys.spec.ts 使用expectTypeOf对嵌套对象、对象数组、混合复杂结构（如users: [{ userId, settings: { isActive } }]）以及包含Date/RegExp/Map的非纯对象做了类型断言，确保类型推导与运行结果一致。这意味着你在 TypeScript 中写完转换后，后续代码访问result.UserId时能够获得完整的类型提示。

边界行为与注意事项

以下是官方测试 toPascalCaseKeys.spec.ts 覆盖的边界情况，可作为使用时的重要参考：

原始值原样返回：数字、字符串、布尔值、null、undefined均不被修改（第 61-67 行）。
空对象与空数组：{}返回{}，[]返回[]，不会报错（第 69-72 行）。
原型方法：当对象键包含toString等特殊键时，转换后对应键（ToString）的值被保留，原函数引用不变（第 74-80 行）。
非纯对象不深入：Date、RegExp、Map等实例作为值或输入时不会被当作普通对象遍历其内部结构（第 127-134 行的类型测试佐证）。
对象键碰撞：由于snake_case、camelCase可能映射到同一个 PascalCase 键（如user_id与userId都变成UserId），若原对象同时存在这类键，后遍历到的键会覆盖先遍历到的值。实现采用Object.keys顺序遍历，遇到此类场景时需要自行确认业务上不会出现冲突。

与同类函数的搭配使用

es-toolkit 在object目录下提供了同一系列的键转换函数，可互相参照：toCamelCaseKeys（源码）、toSnakeCaseKeys（源码）、toKebabCaseKeys（源码）。它们与toPascalCaseKeys共享"递归转换 + 类型推导"的设计模式，区别仅在于目标命名风格。当对接不同规范的数据源时，可以根据目标格式选择合适的函数，例如：数据库字段转前端模型用toCamelCaseKeys，序列化到服务端用toSnakeCaseKeys，而类名或枚举风格的统一则适合toPascalCaseKeys。

总结

toPascalCaseKeys以极简的实现提供了三项核心能力：全键 PascalCase 转换、对嵌套对象与数组的递归处理、以及运行时可验证的完整类型推导。理解其背后的isArray/isPlainObject分支判断与pascalCase（分词 + 首字母大写）流程，能帮助你预测任意输入结构的转换结果；而官方测试覆盖的边界行为，则为在真实项目（如 API 响应规范化、多端数据模型对齐）中安全使用提供了充分依据。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考