@xfe-repo/web-components 1.8.0 → 1.8.2

package/skills/xfe-web-components/references/EffectLabelSelect.md

@@ -1,222 +0,0 @@
-# EffectLabelSelect
-
-> 标签维度双选择器，左侧选择搜索维度（如商户号/商户名），右侧根据选中维度远程搜索并选择具体值。
-
-## 导入
-
-```tsx
-import { EffectLabelSelect } from '@xfe-repo/web-components'
-import type { SelectOptionItem, LabelDic } from '@xfe-repo/web-components'
-// 工具函数
-import { getStrValue, getSelectValue, getInitialValue, getFirstValue, getSecondValue } from '@xfe-repo/web-components'
-```
-
-## 基本用法
-
-### 标准三件套模式
-
-业务中最常见的使用方式 — 同时使用 `customLabelInValue` + `optionsDisplayType` + `labelDic`：
-
-```tsx
-<Form.Item name="merchantStr" noStyle>
-  <EffectLabelSelect customLabelInValue optionsDisplayType="labelAndValue" labelDic={{ phone: '手机号', name: '商户名称' }} />
-</Form.Item>
-```
-
-> 💡 三件套的含义：
->
-> - `customLabelInValue`：value 格式为分号分隔字符串（`displayType;value;label;labelDicKey`）
-> - `optionsDisplayType`：下拉选项展示格式（`labelAndValue` 显示为 `value - label`）
-> - `labelDic`：自定义 label 字典，根据 `labelDicKey` 动态切换显示文案
-
-### 独立受控模式
-
-使用默认的商户号/商户名维度搜索商户列表：
-
-```tsx
-import { EffectLabelSelect } from '@xfe-repo/web-components'
-
-function MyForm() {
-  const [value, setValue] = useState<string>()
-
-  return (
-    <EffectLabelSelect
-      value={value}
-      onChange={(val, option) => {
-        setValue(val)
-        console.log('选中项：', option) // { label, value, customFields }
-      }}
-    />
-  )
-}
-```
-
-## 进阶用法
-
-### 自定义搜索维度
-
-通过 `labelDic` 自定义左侧维度选项：
-
-```tsx
-const customLabelDic: LabelDic = {
-  phone: '手机号',
-  email: '邮箱',
-  name: '姓名',
-}
-
-<EffectLabelSelect
-  labelDic={customLabelDic}
-  defaultLabel="phone"
-  onFetchData={mySearchApi}
-  onTransformData={({ phone, email, name, ...rest }) => ({
-    label: name,
-    value: phone,
-    customFields: rest,
-  })}
-  onChange={(value) => console.log(value)}
-/>
-```
-
-### customLabelInValue 模式
-
-当 `customLabelInValue` 为 `true` 时，value 会编码为 `展示类型;ID;名称;labelDicKey` 格式的字符串：
-
-```tsx
-<EffectLabelSelect
-  customLabelInValue
-  onChange={(value) => {
-    // value 格式如 "label;123;某某商户;businessNo"
-    console.log(value)
-  }}
-/>
-```
-
-### 显示 ID + 名称
-
-```tsx
-<EffectLabelSelect optionsDisplayType="labelAndValue" />
-// 选项显示为 "123456 - 某某商户"
-```
-
-### 自定义 labelDic 文案
-
-通过前缀区分不同场景的同类搜索：
-
-```tsx
-// 买家商户搜索
-<EffectLabelSelect
-  customLabelInValue
-  optionsDisplayType="labelAndValue"
-  labelDic={{ phone: '买家手机号', name: '买家商户名' }}
-/>
-
-// 卖家商户搜索
-<EffectLabelSelect
-  customLabelInValue
-  optionsDisplayType="labelAndValue"
-  labelDic={{ phone: '卖家手机号', name: '卖家商户名' }}
-/>
-```
-
-## Props
-
-```typescript
-interface EffectLabelSelectProps extends Omit<SelectProps, 'onChange'> {
-  onChange?: (value?: string, selectedOptionItem?: SelectOptionItem) => void
-  defaultLabel?: string
-  labelDic?: LabelDic
-  value?: string
-  customLabelInValue?: boolean
-  onFetchData?: (params: any, config: any) => Promise<any>
-  onTransformData?: (params: Record<string, string>) => SelectOptionItem
-  fetchParams?: Object
-  optionsDisplayType?: 'labelAndValue'
-}
-```
-
-| 属性               | 类型                                    | 必填 | 默认值                                     | 说明                                                      |
-| ------------------ | --------------------------------------- | ---- | ------------------------------------------ | --------------------------------------------------------- |
-| value              | `string`                                | 否   | -                                          | 受控值                                                    |
-| onChange           | `(value?, selectedOptionItem?) => void` | 否   | -                                          | 值变化回调                                                |
-| defaultLabel       | `string`                                | 否   | `labelDic` 第一个 key                      | 默认选中的搜索维度 key                                    |
-| labelDic           | `LabelDic`                              | 否   | `{ businessNo: '商户号', name: '商户名' }` | 搜索维度配置，key 为请求参数名，value 为显示文案          |
-| customLabelInValue | `boolean`                               | 否   | `false`                                    | 是否将 value 编码为 `展示类型;ID;名称;labelDicKey` 格式   |
-| onFetchData        | `(params, config) => Promise`           | 否   | `apiService.merchantList`                  | 自定义数据请求函数                                        |
-| onTransformData    | `(params) => SelectOptionItem`          | 否   | 默认转换函数                               | 将接口返回的列表项转换为 `{ label, value, customFields }` |
-| fetchParams        | `Object`                                | 否   | `{}`                                       | 额外请求参数，会合并到请求中                              |
-| optionsDisplayType | `'labelAndValue'`                       | 否   | -                                          | 选项显示格式，设置后显示 `value - label`                  |
-| disabled           | `boolean`                               | 否   | -                                          | 禁用状态                                                  |
-| className          | `string`                                | 否   | -                                          | 右侧 Select 的自定义样式类名                              |
-| style              | `React.CSSProperties`                   | 否   | -                                          | 自定义行内样式                                            |
-
-## 导出类型
-
-```typescript
-// 选项数据结构
-export type SelectOptionItem = {
-  value: string
-  label: string
-  customFields?: Object | null
-}
-
-// 搜索维度配置
-export type LabelDic = Record<string, string>
-```
-
-## 导出工具函数
-
-```typescript
-// 编码 customLabelInValue 的值
-export const getStrValue = (displayType: 'label' | 'value', value?: string, label?: string, labelDicKey?: string) => string | undefined
-
-// 解码 customLabelInValue 的值
-export const getSelectValue = (str?: string | null | number, returnType?: 'label' | 'value' | 'labelDicKey' | 'labelAndValue') =>
-  string | undefined
-
-// 拼接 "value - label" 显示文本
-export const getInitialValue = (label?: string, value?: string) => string
-
-// 从 "value - label" 格式中取 value
-export const getFirstValue = (str?: string) => string
-
-// 从 "value - label" 格式中取 label
-export const getSecondValue = (str?: string) => string
-```
-
-## API 数据源
-
-- **内部 Hook**：`useReqData`（基于 `useAsyncFn` + `useDebounce`，600ms 防抖）
-- **默认接口**：`apiService.merchantList`
-- **请求参数**：`{ page: 1, pageSize: 20, [curSelectLabel]: curSearchValue, ...fetchParams }`
-- **可覆盖**：通过 `onFetchData` prop 传入自定义请求函数，或通过 `<ConfigProvider apiService={{ merchantList: customFn }}>` 替换默认实现
-
-## 常见陷阱
-
-- ❌ 切换左侧维度后期望保留右侧已选值：
-  ```tsx
-  // 切换维度时组件会自动清空右侧选择值和搜索结果
-  ```
-- ✅ 在 `onChange` 中处理值可能为 `undefined` 的情况
-
-- ❌ 使用 `customLabelInValue` 模式时直接展示 value：
-  ```tsx
-  // value 格式为 "label;123;某某商户;businessNo"，不可直接展示
-  ```
-- ✅ 使用 `getSelectValue` 解析所需字段：
-
-  ```tsx
-  const displayText = getSelectValue(value, 'label') // "某某商户"
-  const id = getSelectValue(value, 'value') // "123"
-  ```
-
-- ❌ 忘记提供 `onTransformData` 而使用非商户接口
-- ✅ 当自定义 `onFetchData` 时，务必同时提供 `onTransformData` 确保数据格式正确
-
-- ⚠️ 使用 `customLabelInValue` 时，初始值必须是分号分隔格式字符串（`displayType;value;label;labelDicKey`），不能直接传普通字符串或数字。
-
-## 相关组件
-
-| 场景         | 组件                | 说明                                    |
-| ------------ | ------------------- | --------------------------------------- |
-| 简单下拉搜索 | `EffectStaffSelect` | 单维度员工选择器                        |
-| API 配置     | `ConfigProvider`    | 提供 `apiService.merchantList` 接口实现 |