es-toolkit flattenObject 完全指南用点号记法将嵌套对象扁平化【免费下载链接】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-toolkitflattenObject是 es-toolkit 提供的一个对象工具函数它能把深层次嵌套的对象包括数组转换为使用点号.等分隔符连接键名的单层扁平对象。本文以官方文档为核心结合仓库中的源码实现与测试用例系统讲解它的基本用法、全部配置参数、边界行为与底层递归原理帮助你掌握配置扁平化、环境变量风格转换等典型实战场景。函数概览flattenObject接收一个嵌套对象与可选配置项返回一个全新的扁平对象其中每个嵌套属性都被转换为由分隔符连接的键const flattened flattenObject(object, options?);从 src/object/index.ts 可以看到该函数通过对象子路径统一导出import { flattenObject } from es-toolkit/object;基本用法扁平化嵌套对象当你需要把深层嵌套的对象或数组按点号记法扁平化时可以使用flattenObject。每个嵌套属性都会成为单层对象中的一个键键名由各级属性名拼接而成// 嵌套对象扁平化 const nestedObject { a: { b: { c: 1, }, }, d: [2, 3], e: simple, }; const flattened flattenObject(nestedObject); console.log(flattened); // { // a.b.c: 1, // d.0: 2, // d.1: 3, // e: simple // }注意数组也会被展开数组元素会使用数字索引如d.0、d.1作为键名的一部分。顶层没有嵌套的普通值如e: simple则保持原样。使用自定义分隔符通过options.delimiter参数可以改用自定义字符如下划线_、斜杠/替代默认的点号.来连接嵌套键// 使用自定义分隔符 / const withCustomDelimiter flattenObject(nestedObject, { delimiter: / }); console.log(withCustomDelimiter); // { // a/b/c: 1, // d/0: 2, // d/1: 3, // e: simple // }该选项在特定序列化场景下非常实用。例如想要生成类似环境变量的下划线风格配置const config { database: { host: localhost, port: 5432, credentials: { username: admin, password: secret, }, }, features: [auth, logging], debug: true, }; // 下划线连接的环境变量风格 const envStyle flattenObject(config, { delimiter: _ }); console.log(envStyle); // { // database_host: localhost, // database_port: 5432, // database_credentials_username: admin, // database_credentials_password: secret, // features_0: auth, // features_1: logging, // debug: true // }使用 preserveArrays 保留数组默认情况下数组会被展开为索引键。如果你希望数组整体作为值保留可以设置options.preserveArrays: true// 数组作为值保留 const preserved flattenObject(config, { preserveArrays: true }); console.log(preserved); // { // database.host: localhost, // database.port: 5432, // database.credentials.username: admin, // database.credentials.password: secret, // features: [auth, logging], // debug: true // }从 flattenObject 源码 可以看到preserveArrays仅在为false时才会对数组进行递归展开为true时数组会像普通值一样直接写入结果。即使数组内部还嵌套着对象如[1, { c: 2 }]在preserveArrays: true下也会整体保留这一行为由 flattenObject.spec.ts 的对应测试 覆盖验证。空对象与特殊值处理flattenObject对空对象、空数组以及null、undefined等特殊值有明确的处理策略它们不会被递归展开而是原样保留在结果中空对象与空数组同样会以键的形式出现// 空对象或空数组 const emptyCase { empty: {}, emptyArray: [], nullValue: null, undefinedValue: undefined, }; const result flattenObject(emptyCase); console.log(result); // { // empty: {}, // emptyArray: [], // nullValue: null, // undefinedValue: undefined // } // 空对象和空数组也作为键出现参数与返回值详解参数objectobject要进行扁平化的对象。optionsFlattenObjectOptions可选扁平化配置项接口定义见 flattenObject.ts。delimiterstring可选连接嵌套键的分隔符默认值为.。preserveArraysboolean可选为true时数组不再扁平化而是作为值保留默认值为false。返回值Recordstring, any所有嵌套属性都被扁平化的全新对象。原对象不会被修改。源码级原理剖析理解实现细节有助于你在特殊场景下准确预判行为。flattenObject的核心实现是一个带前缀的递归函数flattenObjectImplsrc/object/flattenObject.ts关键逻辑如下入口包装对外导出的flattenObject通过解构默认值设置delimiter .、preserveArrays false然后以空字符串作为初始前缀调用内部递归函数src/object/flattenObject.ts。键名前缀拼接递归时用${prefix}${delimiter}${key}拼接当前层级键名顶层键prefix为空保持原名src/object/flattenObject.ts。纯对象递归只有当值满足两个条件——isPlainObject(value)为真且自有键数量大于 0——才会继续递归展开src/object/flattenObject.ts。这解释了空对象{}为何保留为原值因为空对象没有可展开的子键。数组递归当preserveArrays为false且数组长度大于 0 时数组也会被递归展开为索引键src/object/flattenObject.ts空数组因此保留原样。叶子值直接写入其余情况原始值、null、undefined、以及非纯对象直接以拼接后的键写入结果src/object/flattenObject.ts。关于第 3 点中的isPlainObject它来自 src/predicate/isPlainObject.ts用于严格区分纯对象与类实例等其他对象类型。这意味着Date、Buffer、TypedArray、类实例等都不会被误展开而是作为完整值保留。这一点由测试用例明确验证Buffer.from(test)与new Uint8Array([1, 2, 3, 4])在扁平化后都以原值出现flattenObject.spec.ts。边界行为与测试覆盖仓库中的 flattenObject.spec.ts 对实现行为做了相当全面的验证可视为官方文档之外的行为契约基础类型保留字符串、数字、布尔值、null、undefined、Date均原样保留flattenObject.spec.ts。多层嵌套与多分支深层对象与同一层级的多个分支会被正确拼接flattenObject.spec.ts。空对象 / 空数组{}与[]保持为值而非被删除flattenObject.spec.ts。数字 / 混合键名01、a1等键名照常拼接不做数字转换flattenObject.spec.ts。数组与对象数组[1, 2, 3]展开为a.0、a.1、a.2对象数组[1, { b: 2 }, 3, [{ c: 4 }]]会继续深层展开为a.1.b、a.3.0.cflattenObject.spec.ts。自定义分隔符的多种形态斜杠/、连字符-、下划线_、多字符-、空字符串乃至特殊字符#$均可作为分隔符flattenObject.spec.ts。其中空字符串分隔符会把键直接拼接如x.y.z变为xyz适合需要紧凑键名的场景。典型实战场景小结结合官方文档与源码实现flattenObject的核心价值在于三点配置扁平化将嵌套的配置对象转换为点号记法的扁平结构便于统一存取、比较与序列化如文档中database.credentials.username形式的例子。环境变量 / 外部系统适配通过delimiter: _生成符合环境变量命名习惯的键名或通过其他分隔符适配不同系统的键名规范。可控的数组策略需要逐元素处理时保持默认展开索引键需要整体传递时开启preserveArrays: true同时利用isPlainObject的严格判定确保Date、Buffer、TypedArray等特殊对象不被误拆。此外该函数在 src/object/index.ts 中与merge、pick、omit、mapKeys等对象工具一同导出可与其他函数自由组合。若需要把扁平对象还原为嵌套结构可结合es-toolkit/object的其他 API 或自行基于扁平键名做逆操作实现完整的配置转换链路。【免费下载链接】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），仅供参考