@xfe-repo/web-components 1.6.2 → 1.7.1

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

@@ -0,0 +1,348 @@
+# EffectFileUpload
+
+> 文件上传组件，支持通过 Ref 手动触发上传、批量上传管理（Group 子组件），数据通过 `apiService.uploadUploadFile` 上传。
+
+## 导入
+
+```tsx
+import { EffectFileUpload, transformUploadFile2SimpleFile, transformSimpleFile2UploadFile } from '@xfe-repo/web-components'
+import type { SimpleFileData, UploadResult, EffectFileUploadRef } from '@xfe-repo/web-components'
+```
+
+## 基本用法
+
+在 Form.Item 中使用，value/onChange 由 Form 自动注入：
+
+```tsx
+import { useRef } from 'react'
+import { Form, Button, message } from 'antd'
+import { EffectFileUpload } from '@xfe-repo/web-components'
+import type { EffectFileUploadRef } from '@xfe-repo/web-components'
+
+function ProductForm() {
+  const [form] = Form.useForm()
+  const uploadRef = useRef<EffectFileUploadRef>(null)
+
+  const handleSubmit = async () => {
+    // 1. 先触发文件上传
+    const uploadResult = await uploadRef.current!.handleUpload()
+    if (!uploadResult.result) {
+      message.error(uploadResult.msg)
+      return
+    }
+    // 2. 再校验并提交表单
+    const values = await form.validateFields()
+    await saveProduct(values)
+  }
+
+  return (
+    <Form form={form}>
+      <Form.Item name="images" label="商品图片" rules={[{ required: true }]}>
+        <EffectFileUpload ref={uploadRef} max={5} accept="image/*" />
+      </Form.Item>
+      <Button type="primary" onClick={handleSubmit}>
+        提交
+      </Button>
+    </Form>
+  )
+}
+```
+
+## 进阶用法
+
+### 独立受控模式
+
+不依赖 Form，通过 `useState` 手动管理文件列表：
+
+```tsx
+import { useRef } from 'react'
+import { EffectFileUpload } from '@xfe-repo/web-components'
+import type { EffectFileUploadRef, SimpleFileData } from '@xfe-repo/web-components'
+
+function MyUploader() {
+  const uploadRef = useRef<EffectFileUploadRef>(null)
+  const [files, setFiles] = useState<SimpleFileData[]>([])
+
+  const handleSave = async () => {
+    const result = await uploadRef.current!.handleUpload()
+    if (result.result) {
+      console.log('上传成功：', result.data)
+    }
+  }
+
+  return (
+    <div>
+      <EffectFileUpload ref={uploadRef} max={5} accept="image/*" value={files} onChange={setFiles} />
+      <button onClick={handleSave}>上传</button>
+    </div>
+  )
+}
+```
+
+### 选择后自动上传
+
+设置 `uploadOnAdd` 后，文件添加时自动触发上传，无需手动调用 `handleUpload`。
+
+```tsx
+<EffectFileUpload
+  uploadOnAdd
+  onChange={(files) => {
+    console.log('已上传文件：', files)
+  }}
+  onUploadDone={(result) => {
+    if (result.result) {
+      message.success('上传成功')
+    }
+  }}
+/>
+```
+
+### 附加表单数据
+
+上传时携带额外字段：
+
+```tsx
+<EffectFileUpload ref={uploadRef} extFormData={{ type: 'avatar', userId: '123' }} />
+```
+
+### 批量上传管理（Group）
+
+使用 `EffectFileUpload.Group` 管理多个上传实例，统一触发上传：
+
+```tsx
+import { useState } from 'react'
+import { EffectFileUpload } from '@xfe-repo/web-components'
+import type { UploadResult } from '@xfe-repo/web-components'
+
+function MultiUploader() {
+  const [needSave, setNeedSave] = useState(false)
+
+  const handleUploadDone = (results: Record<string, UploadResult>) => {
+    // results 的 key 是每个 EffectFileUpload 的 name
+    console.log('正面照：', results['front'])
+    console.log('背面照：', results['back'])
+  }
+
+  return (
+    <EffectFileUpload.Group needSave={needSave} onUploadDone={handleUploadDone}>
+      <EffectFileUpload name="front" accept="image/*" />
+      <EffectFileUpload name="back" accept="image/*" />
+      <button onClick={() => setNeedSave(true)}>全部上传</button>
+    </EffectFileUpload.Group>
+  )
+}
+```
+
+### 多 Ref 并行上传
+
+多个上传字段时，使用 Promise.all 并行提交：
+
+```tsx
+const imgRef = useRef<EffectFileUploadRef>(null)
+const docRef = useRef<EffectFileUploadRef>(null)
+
+const handleSubmit = async () => {
+  const values = await form.validateFields()
+  const [imgResult, docResult] = await Promise.all([
+    imgRef.current!.handleUpload(),
+    docRef.current!.handleUpload(),
+  ])
+  await submitOrder({ ...values, images: imgResult.data, documents: docResult.data })
+}
+
+<Form.Item label="商品图片">
+  <EffectFileUpload ref={imgRef} accept="image/*" />
+</Form.Item>
+<Form.Item label="相关文档">
+  <EffectFileUpload ref={docRef} accept=".pdf,.doc,.docx" />
+</Form.Item>
+```
+
+### 文件校验拦截
+
+通过 onFileChange 返回 false 拦截不符合条件的文件：
+
+```tsx
+<EffectFileUpload
+  onFileChange={(file) => {
+    if (file.size > 10 * 1024 * 1024) {
+      message.error('文件大小不能超过 10MB')
+      return false
+    }
+    return true
+  }}
+/>
+```
+
+## 使用提示
+
+> 💡 `Group`、`extFormData`、`needSave` 在实际业务中使用率极低，大部分场景无需关注。
+
+## Props
+
+```typescript
+type EffectFileUploadProps = {
+  max?: number
+  accept?: string
+  remote?: boolean
+  deleteConfirm?: boolean
+  disabled?: boolean
+  needSave?: boolean
+  uploadOnAdd?: boolean
+  value?: SimpleFileData[]
+  defaultValue?: SimpleFileData[]
+  onChange?: (files: SimpleFileData[]) => void
+  files?: UploadFile[]
+  onFileChange?: (files: UploadFile[]) => void
+  onUpload?: () => void
+  onUploadDone?: (uploadResult: UploadResult) => void
+  extFormData?: Object
+  className?: string
+  name?: string
+}
+```
+
+| 属性          | 类型                                | 必填 | 默认值        | 说明                                                   |
+| ------------- | ----------------------------------- | ---- | ------------- | ------------------------------------------------------ |
+| value         | `SimpleFileData[]`                  | 否   | -             | 受控值，已上传文件列表                                 |
+| defaultValue  | `SimpleFileData[]`                  | 否   | -             | 默认已上传文件列表                                     |
+| onChange      | `(files: SimpleFileData[]) => void` | 否   | -             | 上传完成后回调，返回所有文件的简化数据                 |
+| files         | `UploadFile[]`                      | 否   | -             | 直接控制 antd UploadFile 列表（底层控制）              |
+| onFileChange  | `(files: UploadFile[]) => void`     | 否   | -             | 文件列表变化回调（添加/删除），返回 `false` 可阻止变更 |
+| max           | `number`                            | 否   | -             | 最大上传文件数                                         |
+| accept        | `string`                            | 否   | -             | 接受的文件类型，如 `image/*`、`.pdf,.doc`              |
+| uploadOnAdd   | `boolean`                           | 否   | `false`       | 是否在添加文件时自动上传                               |
+| needSave      | `boolean`                           | 否   | -             | 设为 `true` 时触发上传（适用于外部控制）               |
+| disabled      | `boolean`                           | 否   | -             | 禁用状态（上传中也会自动禁用）                         |
+| remote        | `boolean`                           | 否   | -             | 是否为远程文件模式                                     |
+| deleteConfirm | `boolean`                           | 否   | -             | 删除文件前是否弹窗确认                                 |
+| extFormData   | `Object`                            | 否   | -             | 上传时附加的表单字段                                   |
+| onUpload      | `() => void`                        | 否   | -             | 上传开始时回调                                         |
+| onUploadDone  | `(result: UploadResult) => void`    | 否   | -             | 上传完成后回调                                         |
+| name          | `string`                            | 否   | 自动生成 UUID | 组件实例标识，在 Group 中用于区分不同上传实例          |
+| className     | `string`                            | 否   | -             | 自定义样式类名                                         |
+
+## 导出类型
+
+```typescript
+// 简化文件数据
+export type SimpleFileData = {
+  id?: number
+  name?: string
+  fileName?: string
+  url: string
+}
+
+// 上传结果
+export type UploadResult = {
+  result: boolean // 是否全部成功
+  msg: string // 结果信息
+  data: SimpleFileData[] // 上传后的文件列表
+}
+
+// Ref 暴露的方法
+export type EffectFileUploadRef = {
+  handleUpload: () => Promise<UploadResult> // 手动触发上传
+  uploadTasks: Promise<UploadResult>[] // 当前进行中的上传任务
+  value: SimpleFileData[] // 当前文件列表
+}
+```
+
+## 工具函数
+
+### transformUploadFile2SimpleFile
+
+将 antd `UploadFile[]` 转换为 `SimpleFileData[]`，用于自定义绑定场景。
+
+```typescript
+export const transformUploadFile2SimpleFile: (uploadFiles?: UploadFile[]) => SimpleFileData[]
+```
+
+### transformSimpleFile2UploadFile
+
+将 `SimpleFileData[]` 转换为 antd `UploadFile[]`，用于数据回显。
+
+```typescript
+export const transformSimpleFile2UploadFile: (files?: SimpleFileData[]) => UploadFile[]
+```
+
+### 使用示例
+
+配合 `trigger` 和 `valuePropName` 自定义 Form.Item 绑定：
+
+```tsx
+import { EffectFileUpload, transformUploadFile2SimpleFile } from '@xfe-repo/web-components'
+;<Form.Item
+  name="attachments"
+  trigger="onFileChange"
+  valuePropName="files"
+  getValueFromEvent={(files) => transformUploadFile2SimpleFile(files)}
+>
+  <EffectFileUpload max={3} />
+</Form.Item>
+```
+
+## API 数据源
+
+- **内部接口**：`apiService.uploadUploadFile`
+- **请求格式**：`FormData`（包含 `type: 'product'`、`file`、以及 `extFormData` 中的字段）
+- **可覆盖**：通过 `<ConfigProvider apiService={{ uploadUploadFile: customFn }}>` 替换默认实现
+
+## 子组件
+
+### EffectFileUpload.Group
+
+> 批量上传管理器，包裹多个 EffectFileUpload 实例，统一控制上传时机。
+
+```tsx
+<EffectFileUpload.Group needSave={needSave} onUploadDone={handleDone}>
+  <EffectFileUpload name="photo1" />
+  <EffectFileUpload name="photo2" />
+</EffectFileUpload.Group>
+```
+
+| 属性         | 类型                                              | 必填 | 默认值 | 说明                                    |
+| ------------ | ------------------------------------------------- | ---- | ------ | --------------------------------------- |
+| needSave     | `boolean`                                         | 是   | -      | 设为 `true` 时触发所有子实例上传        |
+| onUploadDone | `(results: Record<string, UploadResult>) => void` | 否   | -      | 全部上传完成后回调，key 为各实例的 name |
+| children     | `ReactNode`                                       | 是   | -      | 子组件（EffectFileUpload 实例）         |
+
+## 常见陷阱
+
+- ❌ 选择文件后直接读取 `onChange` 结果，以为文件已上传：
+  ```tsx
+  // onChange 在上传完成后才触发，选择文件阶段不会触发
+  <EffectFileUpload onChange={(files) => saveToDb(files)} />
+  // 如果没有调用 handleUpload 或设置 uploadOnAdd，文件永远不会上传
+  ```
+- ✅ 确保触发上传后再处理结果：
+
+  ```tsx
+  ;<EffectFileUpload ref={uploadRef} uploadOnAdd onChange={(files) => saveToDb(files)} />
+  // 或者手动调用
+  const result = await uploadRef.current!.handleUpload()
+  ```
+
+- ❌ 在 Group 中不设置 `name`，导致多个实例无法区分：
+  ```tsx
+  <EffectFileUpload.Group needSave={save} onUploadDone={(results) => {
+    // results 的 key 是自动生成的 UUID，无法识别
+  }}>
+  ```
+- ✅ 为每个实例指定有意义的 `name`：
+
+  ```tsx
+  <EffectFileUpload name="front" />
+  <EffectFileUpload name="back" />
+  ```
+
+- ❌ 上传过程中重复调用 `handleUpload` —— 组件内部会等待之前的上传任务完成后再执行新任务
+- ✅ 等待上传完成或使用 `uploadTasks` 检查是否有进行中的任务
+
+## 相关组件
+
+| 场景     | 组件             | 说明                                      |
+| -------- | ---------------- | ----------------------------------------- |
+| 底层渲染 | `FileUpload`     | EffectFileUpload 内部使用的纯 UI 上传组件 |
+| API 配置 | `ConfigProvider` | 提供 apiService.uploadUploadFile 接口实现 |
+| 弹窗上传 | `WithModal`      | 常在弹窗内使用文件上传                    |

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

@@ -0,0 +1,222 @@
+# 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` 接口实现 |