rsuite 数据项类型详解：读懂 `Option` 接口与 valueKey / labelKey / childrenKey 映射机制

• 前端
• UI组件

本文以 rsuite 官方文档中统一定义的ts:Option类型为骨架，深入拆解 rsuite 所有选择器（Picker）类组件共享的数据项（Data Item）结构。读完你将掌握Option各字段的真实语义、它们与valueKey/labelKey/childrenKey三个配置项的映射关系，以及树形组件、分组组件、级联懒加载组件在数据建模上的差异，从而能正确地为自己项目中的 SelectPicker、Cascader、CheckTreePicker 等组件设计数据。

为什么需要一个统一的Option类型

rsuite 拥有大量基于"数据驱动"的选择类组件：SelectPicker、CheckPicker、InputPicker、TagPicker、Cascader、MultiCascader、TreePicker、CheckTreePicker、CascadeTree、AutoComplete、SegmentedControl 等。这些组件虽然交互形态各不相同，但都接收一个data数组作为选项来源。

为了让这套体系保持一致，rsuite 在文档的公共类型章节中定义了一个统一的Option接口，并在 docs/pages/_common/types/item-data-type.md 中集中维护。该类型片段会被 20 个组件文档通过<!--{include:(_common/types/item-data-type.md)}-->方式自动引入（例如 Cascader 文档），保证所有组件对"选项长什么样"的描述口径一致。换句话说：只要搞清楚这一个接口，就拿到了所有 Picker 组件数据的通用"说明书"。

Option接口字段逐项解读

原文档给出的核心定义如下：

interface Option<V> { /** The value of the option corresponds to the `valueKey` in the data. **/ value: V; /** The content displayed by the option corresponds to the `labelKey` in the data. **/ label: ReactNode; /** * The data of the child option corresponds to the `childrenKey` in the data. * Properties owned by tree structure components, such as TreePicker, Cascader. */ children?: Option<V>[]; /** * Properties of grouping functional components, such as CheckPicker, InputPicker */ groupBy?: string; /** * The children under the current node are loading. * Used for components that have cascading relationships and lazy loading of children. E.g. Cascader, MultiCascader */ loading?: boolean; }

五个字段逐一说明：

• value: V：选项的值。它对应数据对象中的valueKey字段（默认键名为value）。组件选中某项后，onChange回调拿到的就是该值；value/defaultValue/disabledItemValues等受控属性也都基于它进行匹配。
• label: ReactNode：选项的展示内容，对应数据中的labelKey（默认键名为label）。类型为ReactNode，意味着它不局限于字符串——可以是数字，也可以是任意 React 元素（例如带图标的自定义节点）。源码 Picker/utils.ts) 中的shouldDisplay函数会同时兼容字符串、数字与 React 元素的搜索匹配场景。
• children?: Option<V>[]：子选项数组，对应数据中的childrenKey（默认键名为children）。它只对树形结构的组件有意义，例如 TreePicker、CheckTreePicker、Cascader、MultiCascader。当某个节点存在children时，该节点会被渲染为可展开的父节点。
• groupBy?: string：分组标识，是分组类组件的专属字段，典型场景是 CheckPicker、InputPicker。它的值是一个分组名称字符串，组件会据此把选项归入不同的分组渲染（配合renderOptionGroup可自定义分组标题的展示）。
• loading?: boolean：当前节点的子节点是否处于异步加载中。它服务于"级联关系 + 子节点懒加载"的组件，典型如 Cascader、MultiCascader——配合getChildren回调，在展开节点时异步拉取子数据，拉取期间该节点显示加载状态。

需要特别说明的是，Option是一个"按需取用"的开放结构：非树形组件忽略children，非分组组件忽略groupBy，同步数据场景完全不需要loading。它描述的是能力上限，而不是每个选项都必须填满的必填模板。

字段与valueKey/labelKey/childrenKey的映射原理

Option接口中的注释反复出现一个关键词——"corresponds to thevalueKey/labelKey/childrenKeyin the data"。这意味着Option是对规范化数据形态的抽象描述，而真实业务数据往往字段名不同（例如用id/name/list），需要借助三个映射配置来完成"方言翻译"。

在源码 src/internals/types/picker.ts 中，DataProps接口给出了这三个配置项的权威定义：

export interface DataProps<TData> { data: TData[]; /** The key to use for setting the option value in the data. @default value */ valueKey?: string; /** The key to use for displaying the options in the data. @default label */ labelKey?: string; /** The key to use for setting the children in the data. @default children */ childrenKey?: string; }

对应的默认值与含义总结如下表：

这一套默认键名在运行时同样有落实：Picker 内部工具函数 src/internals/Picker/utils.ts 中定义了defaultNodeKeys = { valueKey: 'value', childrenKey: 'children' }，createConcatChildrenFunction正是通过node[childrenKey] = children把异步加载到的子节点写回原节点，完成数据的原地合并。

而在真实业务中，你可以这样让"方言"对齐：

// 业务字段是 id / name / list，通过三个 key 映射到 Option 语义 <SelectPicker data={[{ id: 1, name: 'React' }, { id: 2, name: 'Vue' }]} valueKey="id" labelKey="name" onChange={value => console.log(value)} // 输出 1 或 2 />

各组件如何差异化消费Option字段

Option各字段并非所有组件全量使用，理解"哪些组件读哪些字段"是正确建模数据的关键。结合 rsuite 组件文档与源码，可以归纳为四类：

1. 扁平列表组件：只用value与label

SelectPicker、CheckPicker、AutoComplete、TagPicker、SegmentedControl 等组件的数据是扁平数组，只消费value与label两个字段。例如 CheckPicker 文档 中同样引入了本类型片段，其数据形如：

const data = [ { value: 'a', label: 'Option A' }, { value: 'b', label: 'Option B' } ];

2. 分组组件：额外读取groupBy

CheckPicker、InputPicker 支持分组。此时在选项上提供groupBy字符串即可自动成组：

const data = [ { value: 'html', label: 'HTML', groupBy: '语言' }, { value: 'css', label: 'CSS', groupBy: '语言' }, { value: 'webpack', label: 'Webpack', groupBy: '工具' } ];

组件会按groupBy的值将选项聚合到"语言""工具"两个分组下渲染。

3. 树形组件：递归消费children

TreePicker、CheckTreePicker、CascadeTree、Cascader、MultiCascader 等通过children表达层级。以 Cascader 文档 为例，其 props 表中的childrenKey（默认'children'）、labelKey（默认'label'）、valueKey（默认'value'）正是对Option.children三个字段的映射，数据形如：

const data = [ { value: '浙江省', label: '浙江省', children: [ { value: '杭州市', label: '杭州市' }, { value: '宁波市', label: '宁波市' } ] } ];

4. 级联懒加载组件：运行时出现loading

同样是 Cascader、MultiCascader，当采用异步加载时，loading字段才真正派上用场：节点展开时若尚未加载子数据，组件将其标记为加载中；加载完成后由getChildren返回的子数组被写入该节点的childrenKey字段（对应源码 Picker/utils.ts 中的createConcatChildrenFunction逻辑），随后loading复位。Cascader 文档也明确说明：getChildren与"节点 children 字段长度为 0"是触发异步加载的两种方式（见 Cascader 文档 Async Data 一节）。

源码视角：Option的真实形态

文档中的Option<V>是面向读者的"教学版"，而代码中的实际定义在 src/internals/types/picker.ts：

export interface Option<T = number | string> extends Record<string, any> { label?: string | ReactNode; value?: T; groupBy?: string; parent?: Option<T>; children?: Option<T>[]; loading?: boolean; }

两相对照可以发现三处值得注意的差异：

• 实际类型泛型默认是number | string，与OptionValue = number | string | null（同文件 L26）呼应，说明常规场景下选项值以数字或字符串为主；
• 实际定义继承了Record<string, any>，允许选项携带任意自定义字段（例如禁用的额外判断条件、自定义渲染所需的数据），文档只是圈定了公共约定字段；
• 实际定义额外包含parent?: Option<T>字段，用于在级联场景中向上回溯父节点，例如 MultiCascadeTree 的工具函数getNodeParents(node, parentKey = 'parent', valueKey?)就是基于该字段计算节点祖先链（见 src/MultiCascadeTree/utils.ts）。

此外，Option还通过FormControlPickerProps与表单体系打通：该接口同时继承DataProps<D>与FormControlBaseProps<T>（见 src/internals/types/picker.ts），这意味着所有 Picker 组件的数据模型都能无缝嵌入 Form / FormControl 的受控表单流程。

为你的业务数据建模：一张快速对照表

综合以上分析，在设计数据时可以直接对照这张速查表：

记住三条核心规则即可：

1. 字段名可换：业务数据字段不必叫value/label/children，用valueKey/labelKey/childrenKey映射即可；
2. 字段按需使用：只有对应交互形态的组件才消费对应字段，扁平数据无需补children；
3. 类型来源统一：无论是写文档、写类型标注还是构造 mock 数据，都应以 docs/pages/_common/types/item-data-type.md 的Option定义为基准，它与源码 src/internals/types/picker.ts 保持同一语义，从而保证整个 rsuite 数据体系的一致性与可迁移性。

• 前端
• UI组件