@xfe-repo/web-components 1.6.2 → 1.7.1

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

@@ -0,0 +1,119 @@
+# RichTextEditor
+
+> 富文本编辑器，基于 TipTap 封装，支持加粗、斜体、下划线、删除线、标题、文字颜色、背景高亮、撤销重做，可选图片插入。
+
+## 导入
+
+```tsx
+import { RichTextEditor } from '@xfe-repo/web-components'
+import type { RichTextEditorProps } from '@xfe-repo/web-components'
+```
+
+## 基本用法
+
+```tsx
+import { RichTextEditor } from '@xfe-repo/web-components'
+
+function Editor() {
+  const [content, setContent] = useState('')
+
+  return <RichTextEditor defaultValue="<p>初始内容</p>" onChange={(html) => setContent(html)} />
+}
+```
+
+### Form.Item 集成
+
+```tsx
+<Form.Item name="content" label="内容">
+  <RichTextEditor />
+</Form.Item>
+```
+
+> 💡 RichTextEditor 兼容 Form.Item 受控模式，value/onChange 由 Form 自动注入。
+
+## 进阶用法
+
+### 禁用编辑
+
+```tsx
+<RichTextEditor value={htmlContent} disabled />
+```
+
+### 自定义占位文案
+
+```tsx
+<RichTextEditor placeholder="请输入商品描述..." onChange={setContent} />
+```
+
+### 启用图片插入
+
+需要在 `ConfigProvider` 内使用，图片会自动上传到 OSS。
+
+```tsx
+<RichTextEditor defaultValue={content} onChange={setContent} enableImageInsert />
+```
+
+### 自定义图片按钮图标
+
+```tsx
+<RichTextEditor enableImageInsert imageInsertIcon={<PictureOutlined />} onChange={setContent} />
+```
+
+## Props
+
+```typescript
+export interface RichTextEditorProps {
+  defaultValue?: string
+  onChange?: (value: string) => void
+  value?: string
+  disabled?: boolean
+  placeholder?: string
+  enableImageInsert?: boolean
+  imageInsertIcon?: React.ReactNode
+}
+```
+
+| 属性              | 类型                      | 必填 | 默认值                | 说明                                      |
+| ----------------- | ------------------------- | ---- | --------------------- | ----------------------------------------- |
+| defaultValue      | `string`                  | 否   | -                     | 初始 HTML 内容（与 value 二选一）         |
+| value             | `string`                  | 否   | -                     | HTML 内容（与 defaultValue 二选一）       |
+| onChange          | `(value: string) => void` | 否   | -                     | 编辑器失焦时触发，参数为 HTML 字符串      |
+| disabled          | `boolean`                 | 否   | -                     | 是否禁用编辑                              |
+| placeholder       | `string`                  | 否   | `'请输入内容'`        | 占位文案                                  |
+| enableImageInsert | `boolean`                 | 否   | `false`               | 是否启用图片插入（工具栏按钮 + 粘贴图片） |
+| imageInsertIcon   | `React.ReactNode`         | 否   | `<PictureOutlined />` | 自定义图片插入按钮图标                    |
+
+## 导出类型
+
+### replaceRgbWithHex
+
+```typescript
+export const replaceRgbWithHex: (value: string) => string
+```
+
+将 HTML 中的 `rgb(r,g,b)` 颜色值转换为 `#rrggbb` 格式。编辑器 onChange 输出时自动调用。
+
+## 注意事项
+
+- 编辑器底部会自动显示 **字数统计**（格式：`字数 : N`），无需额外配置
+- 图片插入支持的格式：**jpeg、jpg、png、gif、webp**，不支持的格式会提示错误
+- 插入的图片样式约束为 `max-width: 100%; max-height: 200px`
+- 图片上传过程中再次粘贴图片会被阻止（提示"正在上传中，请稍候..."），需等当前上传完成
+
+## 常见陷阱
+
+- ❌ `onChange` 在 **失焦** 时触发而非实时输入，如果编辑器内容为空 `<p></p>` 则回调空字符串 `''`
+- ✅ 需要实时获取内容，考虑通过 TipTap 的 `onUpdate` 自行扩展
+
+- ❌ 启用 `enableImageInsert` 时，图片上传依赖 `ConfigProvider` 提供的 `apiService.uploadUploadFile`
+- ✅ 确保在 `ConfigProvider` 内使用，且已配置 `apiPayload`
+
+- ❌ 同时传 `value` 和 `defaultValue` 时，优先使用 `defaultValue`
+- ✅ 建议只传其中一个
+
+## 相关组件
+
+| 场景     | 组件               | 说明                        |
+| -------- | ------------------ | --------------------------- |
+| 图片上传 | `EffectFileUpload` | 独立的文件上传组件          |
+| 全局配置 | `ConfigProvider`   | 提供图片上传所需的 API 服务 |

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

@@ -0,0 +1,270 @@
+# SearchForm
+
+> 搜索表单组件，提供统一的搜索表单布局和操作按钮，支持完整表单模式和内容模式（Content 子组件）。
+
+## 导入
+
+```tsx
+import { SearchForm, SearchFormContent, useSearchFormStyle } from '@xfe-repo/web-components'
+import type { SearchFormProps, SearchFormContentProps } from '@xfe-repo/web-components'
+```
+
+## 基本用法
+
+### 完整表单模式
+
+组件内部自动包裹 `<Form>`，提供 inline 布局和统一样式。
+
+```tsx
+import { SearchForm } from '@xfe-repo/web-components'
+import { Form, Input, Select } from 'antd'
+
+function OrderSearch({ filter, onFinish, onReset }) {
+  const [form] = Form.useForm()
+
+  return (
+    <SearchForm form={form} filter={filter} onFinish={onFinish} onReset={onReset} className="my-search">
+      <Form.Item name="orderNo" label="订单号">
+        <Input placeholder="请输入" />
+      </Form.Item>
+      <Form.Item name="status" label="状态">
+        <Select options={statusOptions} />
+      </Form.Item>
+    </SearchForm>
+  )
+}
+```
+
+### 内容模式（Content Only）
+
+当不传 `className`、`layout`、`style` 等 Form 属性时，自动降级为内容模式（不包裹 `<Form>`），需要自行在外部包裹 `<Form>`。
+
+```tsx
+import { SearchForm } from '@xfe-repo/web-components'
+
+function OrderSearch({ filter }) {
+  const [form] = Form.useForm()
+
+  return (
+    <Form form={form} onFinish={handleSearch}>
+      <SearchForm filter={filter} form={form}>
+        <Form.Item name="orderNo" label="订单号">
+          <Input />
+        </Form.Item>
+      </SearchForm>
+    </Form>
+  )
+}
+```
+
+## 进阶用法
+
+### 显式使用 SearchFormContent
+
+适用于跨包场景（避免 antd Context 隔离问题），需要放在消费方自己的 `<Form>` 内部。
+
+```tsx
+import { SearchFormContent } from '@xfe-repo/web-components'
+
+function OrderSearch({ filter }) {
+  const [form] = Form.useForm()
+
+  return (
+    <Form form={form} onFinish={handleSearch}>
+      <SearchFormContent filter={filter} form={form}>
+        <Form.Item name="keyword" label="关键词">
+          <Input />
+        </Form.Item>
+      </SearchFormContent>
+    </Form>
+  )
+}
+```
+
+### Redux 标准模式
+
+业务项目中的标准使用模式 — 配合 Redux 管理搜索状态：
+
+```tsx
+import { useAppSelector, useAppDispatch } from '@/store'
+import { selectFilter, effectSearch } from './slice'
+
+function OrderList() {
+  const [form] = Form.useForm()
+  const filter = useAppSelector(selectFilter)
+  const dispatch = useAppDispatch()
+
+  const handleFinish = (values) => {
+    dispatch(effectSearch({ ...values, page: 1 }))
+  }
+
+  const handleReset = () => {
+    dispatch(effectSearch(initialState.filter))
+  }
+
+  return (
+    <SearchForm form={form} filter={filter} onFinish={handleFinish} onReset={handleReset}>
+      <Form.Item name="orderNo" label="订单号">
+        <CInput placeholder="请输入" allowClear />
+      </Form.Item>
+    </SearchForm>
+  )
+}
+```
+
+> 💡 标准三件套：`selectFilter`（读取 Redux 搜索条件）→ `effectSearch`（触发搜索 action）→ `initialState.filter`（重置时恢复初始值）。
+
+### 自定义操作按钮
+
+```tsx
+<SearchForm filter={filter} form={form} operations={<Button>导出</Button>}>
+  {/* 表单项 */}
+</SearchForm>
+```
+
+### 隐藏重置按钮
+
+```tsx
+<SearchForm filter={filter} form={form} showReset={false}>
+  {/* 表单项 */}
+</SearchForm>
+```
+
+### 自定义确认按钮文案
+
+```tsx
+<SearchForm filter={filter} form={form} confirmText="搜索">
+  {/* 表单项 */}
+</SearchForm>
+```
+
+### 使用 useSearchFormStyle
+
+在需要自定义 Form 但保持一致样式时使用。
+
+```tsx
+import { useSearchFormStyle } from '@xfe-repo/web-components'
+
+function CustomSearch() {
+  const searchFormStyle = useSearchFormStyle()
+
+  return (
+    <Form className={searchFormStyle.className} layout={searchFormStyle.layout} style={searchFormStyle.style}>
+      {/* 表单内容 */}
+    </Form>
+  )
+}
+```
+
+## Props
+
+### SearchFormProps
+
+```typescript
+export type SearchFormProps<T extends object = any> = SearchFormBaseProps<T> &
+  Omit<FormProps<T>, 'children'> & {
+    contentOnly?: boolean
+  }
+
+type SearchFormBaseProps<T> = {
+  children: ReactNode
+  operations?: ReactNode
+  showReset?: boolean
+  confirmText?: string
+  filter: T
+  form?: FormInstance<T>
+}
+```
+
+| 属性         | 类型                           | 必填 | 默认值   | 说明                                                 |
+| ------------ | ------------------------------ | ---- | -------- | ---------------------------------------------------- |
+| filter       | `T`                            | 是   | -        | 筛选条件对象，变更时自动同步到表单                   |
+| form         | `FormInstance<T>`              | 否   | -        | antd Form 实例                                       |
+| children     | `ReactNode`                    | 是   | -        | 表单项                                               |
+| showReset    | `boolean`                      | 否   | `true`   | 是否显示重置按钮                                     |
+| confirmText  | `string`                       | 否   | `'确认'` | 确认按钮文案                                         |
+| operations   | `ReactNode`                    | 否   | -        | 额外操作按钮（渲染在确认/重置按钮后）                |
+| contentOnly  | `boolean`                      | 否   | -        | 是否显式使用内容模式（不包裹 Form）                  |
+| onFinish     | `(values: T) => void`          | 否   | -        | 表单提交回调，点击"确认"按钮触发（继承自 FormProps） |
+| onReset      | `(e: React.FormEvent) => void` | 否   | -        | 表单重置回调，点击"重置"按钮触发（继承自 FormProps） |
+| ...formProps | `FormProps`                    | 否   | -        | 所有 antd Form 属性                                  |
+
+## 子组件
+
+| 子组件              | 说明                                                   |
+| ------------------- | ------------------------------------------------------ |
+| `SearchFormContent` | 纯内容组件（无 Form 包裹），适用于自行管理 Form 的场景 |
+
+## 导出类型
+
+### useSearchFormStyle
+
+```typescript
+export const useSearchFormStyle: () => {
+  className: string
+  layout: 'inline'
+  style: React.CSSProperties
+}
+```
+
+返回搜索表单的标准样式配置（inline 布局、背景色、圆角、内边距）。
+
+## 使用模式
+
+### 常见表单字段组合
+
+除了 CInput，SearchForm 中常用的字段类型：
+
+```tsx
+<SearchForm form={form} filter={filter} onFinish={onFinish} onReset={onReset}>
+  <Form.Item name="orderNo" label="订单号">
+    <CInput placeholder="请输入" allowClear />
+  </Form.Item>
+  <Form.Item name="categoryIds" label="分类">
+    <EffectCategoryCascade changeOnSelect style={{ width: 200 }} />
+  </Form.Item>
+  <Form.Item name="dateRange" label="日期" normalize={commonDateRangePickerNormalize} getValueProps={commonDateRangePickerGetValueProps}>
+    <DatePicker.RangePicker />
+  </Form.Item>
+  <Form.Item name="status" label="状态">
+    <Select options={statusOptions} allowClear style={{ width: 150 }} />
+  </Form.Item>
+</SearchForm>
+```
+
+### 字段联动
+
+分类→品牌级联场景：
+
+```tsx
+const categoryIds = Form.useWatch('categoryIds', form)
+const categoryId = categoryIds?.at(-1)
+
+<Form.Item name="brandId" label="品牌">
+  <EffectBrandSelect categoryId={categoryId} key={categoryId} />
+</Form.Item>
+```
+
+> 💡 **日期字段标准化**：使用 `normalize={commonDateRangePickerNormalize}` 和 `getValueProps={commonDateRangePickerGetValueProps}` 处理 DatePicker 与 Redux 之间的 dayjs 序列化。详见 [commonFn](./commonFn.md)。
+
+> 💡 `operations` 区域支持根据权限条件渲染操作按钮（如 `buttonConfig.canExport && <Button>导出</Button>`）。
+
+## 常见陷阱
+
+- ❌ 在跨包场景中使用完整表单模式，antd Context 可能隔离导致 Form 功能异常：
+  ```tsx
+  // 组件库和业务代码的 antd 版本/实例不一致
+  <SearchForm form={form} filter={filter} className="search">
+  ```
+- ✅ 跨包场景使用 `SearchFormContent` 或 `contentOnly`，由消费方包裹 `<Form>`：
+  ```tsx
+  <Form form={form}>
+    <SearchFormContent filter={filter} form={form}>
+  ```
+
+## 相关组件
+
+| 场景         | 组件         | 说明                                |
+| ------------ | ------------ | ----------------------------------- |
+| 简单搜索列表 | `SearchList` | 更轻量的搜索容器，只有查询/重置按钮 |
+| 增强输入框   | `CInput`     | 搜索表单中常用的自动 trim 输入框    |

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

@@ -0,0 +1,128 @@
+# SearchList
+
+> 搜索列表容器，提供查询和重置按钮的简单布局，需要配合外部 `<Form>` 使用。
+
+## 导入
+
+```tsx
+import { SearchList } from '@xfe-repo/web-components'
+import type { SearchListProps } from '@xfe-repo/web-components'
+```
+
+## 基本用法
+
+> SearchList 需要放在外部 `<Form>` 内使用。children 内部约定使用 `div.search_item > div.label + Form.Item(noStyle)` 的结构，确保搜索项的标签和输入控件对齐。
+
+```tsx
+import { SearchList } from '@xfe-repo/web-components'
+import { CInput } from '@xfe-repo/web-components'
+import { Form } from 'antd'
+
+function OrderFilter({ filter, onFinish, onReset }) {
+  const [form] = Form.useForm()
+
+  return (
+    <Form form={form} onFinish={onFinish} onReset={onReset}>
+      <SearchList showReset>
+        <div className={styles.search_item}>
+          <div className={styles.label}>订单号 :</div>
+          <Form.Item name="orderNo" noStyle initialValue={filter.orderNo}>
+            <CInput placeholder="请输入" allowClear />
+          </Form.Item>
+        </div>
+        <div className={styles.search_item}>
+          <div className={styles.label}>状态 :</div>
+          <Form.Item name="status" noStyle initialValue={filter.status}>
+            <Select options={statusOptions} allowClear placeholder="请选择" />
+          </Form.Item>
+        </div>
+      </SearchList>
+    </Form>
+  )
+}
+```
+
+## 进阶用法
+
+### 隐藏查询按钮
+
+```tsx
+<SearchList hideSearch>
+  <Form.Item name="keyword">
+    <Input />
+  </Form.Item>
+</SearchList>
+```
+
+### 自定义操作按钮
+
+```tsx
+<SearchList buttonChildren={<Button onClick={handleExport}>导出</Button>}>
+  <Form.Item name="keyword">
+    <Input />
+  </Form.Item>
+</SearchList>
+```
+
+## Props
+
+```typescript
+export type SearchListProps = {
+  showReset?: boolean
+  hideSearch?: boolean
+  children: ReactNode
+  buttonChildren?: ReactNode
+}
+```
+
+| 属性           | 类型        | 必填 | 默认值 | 说明                             |
+| -------------- | ----------- | ---- | ------ | -------------------------------- |
+| children       | `ReactNode` | 是   | -      | 表单项内容                       |
+| showReset      | `boolean`   | 否   | -      | 是否显示重置按钮                 |
+| hideSearch     | `boolean`   | 否   | -      | 是否隐藏查询按钮                 |
+| buttonChildren | `ReactNode` | 否   | -      | 额外操作按钮（渲染在查询按钮前） |
+
+### onReset 处理
+
+89% 场景启用 `showReset`，需提供 `onReset` 处理函数：
+
+```tsx
+<Form
+  form={form}
+  onFinish={(values) => dispatch(effectSearch({ ...values, page: 1 }))}
+  onReset={() => dispatch(effectSearch(initialState.filter))}
+>
+  <SearchList showReset>{/* 搜索项 */}</SearchList>
+</Form>
+```
+
+### Redux filter 同步
+
+当 Redux filter 变化时（如翻页），需同步更新表单：
+
+```tsx
+useEffect(() => {
+  form.resetFields()
+}, [filter])
+```
+
+> 💡 日期字段需配合 `normalize` 和 `getValueProps` 处理 dayjs 序列化，用法同 SearchForm。详见 [commonFn](./commonFn.md)。
+
+> 💡 `hideSearch` 和 `buttonChildren` 业务使用率 <2%，大部分场景无需关注。
+
+## 常见陷阱
+
+- ❌ Form.Item 不加 `noStyle`，导致额外的 margin-bottom 破坏搜索栏布局：
+  ```tsx
+  <Form.Item name="keyword">  {/* 会有 24px 下边距 */}
+  ```
+- ✅ 始终使用 `noStyle`，由外层 div.search_item 控制布局：
+  ```tsx
+  <Form.Item name="keyword" noStyle>
+  ```
+
+## 相关组件
+
+| 场景         | 组件         | 说明                               |
+| ------------ | ------------ | ---------------------------------- |
+| 完整搜索表单 | `SearchForm` | 带表单包裹和 filter 同步的搜索表单 |