# tree-selector-wrapper LLMs.txt

> 供 LLM 快速理解 `@flatbiz/antd/tree-selector-wrapper` 的使用方式。

## 模块定位

树选择器包装组件，由于过度封装，部分antd TreeSelect原始功能不支持，不满足情况的请使用antd TreeSelect实现

## 导入方式

```ts
import { TreeSelectorWrapper } from '@flatbiz/antd/tree-selector-wrapper';
// 也可以从主入口导入：import { ... } from '@flatbiz/antd';
```

## 公开导出

- `* from ./selector.jsx`
- `treeSelectorWrapperModel` - 
- `ModelState`
- `TreeSelectorWrapper` - 树选择器包装组件，由于过度封装，部分antd TreeSelect原始功能不支持，不满足情况的请使用antd TreeSelect实现
- `TreeSelectorWrapperProps`
- `getExpandedKeysByValue`
- `getExpandedKeysByValues`

## 依赖的 antd 能力

`Button`、`TreeSelect`、`TreeSelectProps`

## Props / 配置要点

### TreeSelectorServiceConfig

- `params`（可选）：: TPlainObject
- `requiredParamsKeys`（可选）：: string[]
- `onRequest`（可选）：: (params?: TAny) => TAny
- `onRequestResultAdapter`（可选）：: (respData: TAny) => TPlainObject[]；响应数据适配器

### TreeSelectorWrapperProps

- `modelKey`（可选）：: string；设置请求唯一值
- `fieldNames`（可选）：: { list?: string; label?: string; value?: string; children?: string; disabled?: string; }；1. list 为 onRequest 返回数据中列表key值，可多级取值，例如： 'a.b.c' 2. 配置 serviceConfig.onRequestResultAdapter 后此配置失效
- `effectDependencyList`（可选）：: DependencyList；useEffect依赖项数组，用于重新发起获取接口数据
- `serviceConfig`（可选）：: TreeSelectorServiceConfig；请求服务需求的数据，当设置treeSelectorList后无效果
- `treeSelectorList`（可选）：: TreeSelectProps['treeData']；当设置treeSelectorList后，serviceConfig 将失效
- `onTreeSelectorListChange`（可选）：: ( treeSelectorList?: TreeSelectProps['treeData'] ) => void；treeSelectorList发生变更时触发
- `onTreeSelectorRequestError`（可选）：: (error: Error) => void；通过服务获取数据异常回调，当设置treeSelectorList后无效果
- `showAllOption`（可选）：: true | TPlainObject<string | number>；添加全部选项
- `onChange`（可选）：: ( selectedValue?: TreeSelectorWrapperValue, selectedData?: TPlainObject[] | TPlainObject, triggerInfo?: TPlainObject ) => void；1. 当 treeCheckable = true && treeCheckStrictly = true，如果选择的数据中含有父节点，selectedValue、selectedList返回数据包含父节点 2. 当 treeCheckable = true && treeCheckStrictly = false，selectedValue、selectedList返回的数据不包含父节点 3. 当 treeCheckable = f…
- `onTreeItemDataAdapter`（可选）：: (dataItem: TPlainObject) => TPlainObject；tree item 数据适配器，返回的数据会通过fieldNames配置取数据
- `requestMessageConfig`（可选）：: TRequestStatusProps['messageConfig']；自定义异常提示文案
- `value`（可选）：: TreeSelectorWrapperValue；value格式
- `labelInValue`（可选）：: boolean；treeCheckStrictly checkable 状态下节点选择完全受控（父子节点选中状态不再关联）， 会使得 labelInValue 强制为 true
- `selectedParentCheckedAllChildrenList`（可选）：: boolean；treeCheckStrictly = true模式下有效，点击父节点是否选中所有子节点，默认值：true
- `initRootExpand`（可选）：: boolean；有唯一跟节点时，初始化是否展开，默认值：false
- `executeOnChangeInRenderFirstValue`（可选）：: boolean；在第一次渲染value时，主动执行一次onChange

## 使用规则与行为

- 响应数据适配器
- 设置请求唯一值
- 1. list 为 onRequest 返回数据中列表key值，可多级取值，例如： 'a.b.c' 2. 配置 serviceConfig.onRequestResultAdapter 后此配置失效
- useEffect依赖项数组，用于重新发起获取接口数据
- 请求服务需求的数据，当设置treeSelectorList后无效果
- 当设置treeSelectorList后，serviceConfig 将失效
- treeSelectorList发生变更时触发
- 通过服务获取数据异常回调，当设置treeSelectorList后无效果
- 添加全部选项
- 1. 当 treeCheckable = true && treeCheckStrictly = true，如果选择的数据中含有父节点，selectedValue、selectedList返回数据包含父节点 2. 当 treeCheckable = true && treeCheckStrictly = false，selectedValue、selectedList返回的数据不包含父节点 3. 当 treeCheckable = f…

## 基础示例

```tsx
import { TreeSelectorWrapper, type TreeSelectorWrapperProps } from '@flatbiz/antd/tree-selector-wrapper';

const props: TreeSelectorWrapperProps = {
  // 按业务传入必要参数
};

<TreeSelectorWrapper {...props} />;
```

## 源码索引

- `src/tree-selector-wrapper/index.ts`
- `src/tree-selector-wrapper/model.ts`
- `src/tree-selector-wrapper/selector.tsx`
- `src/tree-selector-wrapper/utils.ts`

## 给 LLM 的注意事项

- 优先使用 `@flatbiz/antd/tree-selector-wrapper` 或主入口 `@flatbiz/antd` 的公开导出，不要引用内部实现文件。
- 当 Props 与 antd 原组件同名能力冲突时，以本模块导出的 Props 类型为准。
- 若文档未覆盖某个边缘参数，请读取上方源码索引中的类型定义和 JSDoc。