@xfe-repo/web-components 1.6.2 → 1.7.1

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

@@ -0,0 +1,254 @@
+# commonFn
+
+> 通用工具函数和常量集合，提供表格/选择器的默认 Props、状态选项、日期格式化等。
+
+## 导入
+
+```tsx
+import {
+  typedMemo,
+  getCommonTableProps,
+  getCommonSelectProps,
+  commonStatusSelectOptions,
+  commonYesOrNoSelectOptions,
+  commonYesOrNoSelectOptionsMap,
+  commonDatePickerNormalize,
+  commonDatePickerGetValueProps,
+  commonDateRangePickerNormalize,
+  commonDateRangePickerGetValueProps,
+  getSelectValue,
+  getStrValue,
+  getInitialValue,
+  getFirstValue,
+  getSecondValue,
+} from '@xfe-repo/web-components'
+```
+
+## 函数和常量
+
+### typedMemo
+
+保留泛型类型的 `React.memo` 包装。
+
+```typescript
+export const typedMemo: <T extends ComponentType>(c: T) => MemoExoticComponent<T>
+```
+
+```tsx
+interface Props<T> {
+  data: T[]
+}
+
+const MyList = typedMemo(<T,>(props: Props<T>) => {
+  return <div>{props.data.length}</div>
+})
+```
+
+### getCommonTableProps
+
+返回通用表格默认 Props（无边框样式、横向滚动、无分页）。
+
+```typescript
+export const getCommonTableProps: <T = any>(coverProps?: CTableProps<T>) => CTableProps<T>
+```
+
+```tsx
+<CTable {...getCommonTableProps()} columns={columns} dataSource={data} />
+
+// 覆盖默认值
+<CTable {...getCommonTableProps({ pagination: { pageSize: 20 }, bordered: true })} />
+```
+
+默认值：
+| 属性 | 值 |
+|------|-----|
+| className | `'table no_border'`（bordered 时为 `'table'`） |
+| scroll | `{ x: true }` |
+| pagination | `false` |
+
+### getCommonSelectProps
+
+返回通用选择器默认 Props（可搜索、可清除、按 label 过滤）。
+
+```typescript
+export const getCommonSelectProps: <T = any>(coverProps?: SelectProps<T>) => SelectProps<T>
+```
+
+```tsx
+<Select {...getCommonSelectProps()} options={options} />
+
+// 覆盖默认值
+<Select {...getCommonSelectProps({ placeholder: '请选择品牌' })} />
+```
+
+> ⚠️ **注意调用括号**：`getCommonSelectProps` 是函数，使用时必须加括号调用。
+>
+> - ❌ 漏掉括号，将函数本身展开为 props（运行时不报错但行为异常）：
+>   ```tsx
+>   <Select {...getCommonSelectProps} />
+>   ```
+> - ✅ 正确调用函数获取返回值：
+>   ```tsx
+>   <Select {...getCommonSelectProps()} />
+>   ```
+
+默认值：
+| 属性 | 值 |
+|------|-----|
+| showSearch | `true` |
+| allowClear | `true` |
+| optionFilterProp | `'label'` |
+| notFoundContent | `'暂无数据'` |
+| placeholder | `'请选择'` |
+
+### commonStatusSelectOptions
+
+启用/禁用状态选项。
+
+```typescript
+export const commonStatusSelectOptions = [
+  { value: 1, label: '启用' },
+  { value: 2, label: '禁用' },
+]
+```
+
+### commonYesOrNoSelectOptions
+
+是/否选项。
+
+```typescript
+export const commonYesOrNoSelectOptions = [
+  { value: 1, label: '是' },
+  { value: 2, label: '否' },
+]
+```
+
+也可用于 Radio.Group：
+
+```tsx
+<Form.Item name="isEnabled" label="是否启用">
+  <Radio.Group options={commonYesOrNoSelectOptions} />
+</Form.Item>
+```
+
+### commonYesOrNoSelectOptionsMap
+
+是/否映射字典。
+
+```typescript
+export const commonYesOrNoSelectOptionsMap: Record<number, string> = { 1: '是', 2: '否' }
+```
+
+### commonDatePickerNormalize / commonDatePickerGetValueProps
+
+用于 antd Form.Item 的 DatePicker `normalize` 和 `getValueProps`，在 Dayjs 和格式化字符串之间转换。
+
+```tsx
+<Form.Item name="createDate" label="创建日期" normalize={commonDatePickerNormalize} getValueProps={commonDatePickerGetValueProps}>
+  <DatePicker />
+</Form.Item>
+```
+
+```typescript
+export const commonDatePickerNormalize: (date: Dayjs | null, format?: string) => string
+export const commonDatePickerGetValueProps: (date: string | null) => { value: Dayjs | '' }
+```
+
+### commonDateRangePickerNormalize / commonDateRangePickerGetValueProps
+
+用于 RangePicker 的日期范围转换。
+
+```tsx
+<Form.Item name="dateRange" label="日期范围" normalize={commonDateRangePickerNormalize} getValueProps={commonDateRangePickerGetValueProps}>
+  <RangePicker />
+</Form.Item>
+```
+
+```typescript
+export const commonDateRangePickerNormalize: (dates: Dayjs[] | null, format?: string) => string[]
+export const commonDateRangePickerGetValueProps: (dateStrs: string[] | null) => { value: Dayjs[] | [] }
+```
+
+> 日期格式默认为 `'YYYY-MM-DD HH:mm:ss'`。
+
+---
+
+### getSelectValue / getStrValue 系列
+
+配合 `EffectLabelSelect` 的 `customLabelInValue` 模式使用的解析函数组。当 EffectLabelSelect 设置了 `customLabelInValue` 后，value 不再是简单的 ID，而是一个分号分隔的组合字符串。
+
+导入：
+
+```tsx
+import { getSelectValue, getStrValue, getInitialValue, getFirstValue, getSecondValue } from '@xfe-repo/web-components'
+```
+
+#### getStrValue
+
+生成分号分隔的组合字符串，由 EffectLabelSelect 内部调用。
+
+```typescript
+export const getStrValue: (displayType: 'label' | 'value', value?: string, label?: string, labelDicKey?: string) => string | undefined
+
+// 示例
+getStrValue('label', '123', '张三', 'phone')
+// => 'label;123;张三;phone'
+```
+
+#### getSelectValue
+
+从分号分隔字符串中解析指定字段。
+
+```typescript
+type ReturnType = 'label' | 'value' | 'labelDicKey' | 'labelAndValue'
+
+export const getSelectValue: (str?: string | null | number, returnType?: ReturnType) => string | undefined
+
+// 示例
+const str = 'label;123;张三;phone'
+getSelectValue(str, 'value') // => '123'
+getSelectValue(str, 'label') // => '张三'
+getSelectValue(str, 'labelDicKey') // => 'phone'
+getSelectValue(str, 'labelAndValue') // => '123 - 张三'
+```
+
+#### getInitialValue
+
+拼接 `value - label` 展示格式。
+
+```typescript
+export const getInitialValue: (label?: string, value?: string) => string
+// getInitialValue('张三', '123') => '123 - 张三'
+```
+
+#### getFirstValue / getSecondValue
+
+从 `value - label` 格式中提取各部分。
+
+```typescript
+export const getFirstValue: (str?: string) => string // 提取 value
+export const getSecondValue: (str?: string) => string // 提取 label
+
+// getFirstValue('123 - 张三') => '123'
+// getSecondValue('123 - 张三') => '张三'
+```
+
+#### 典型业务使用
+
+配合 EffectLabelSelect 的 customLabelInValue 模式：
+
+```tsx
+// 搜索表单中使用 EffectLabelSelect
+;<Form.Item name="merchantStr" noStyle>
+  <EffectLabelSelect customLabelInValue optionsDisplayType="labelAndValue" labelDic={{ phone: '手机号', name: '商户名' }} />
+</Form.Item>
+
+// 提交时解析值
+const handleSubmit = (values) => {
+  const params = {
+    merchantId: getSelectValue(values.merchantStr, 'value'),
+    merchantName: getSelectValue(values.merchantStr, 'label'),
+  }
+  dispatch(fetchList(params))
+}
+```