@xfe-repo/web-components 1.6.2 → 1.7.1

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

@@ -0,0 +1,68 @@
+# Loading
+
+> 全屏加载状态组件，基于 antd Spin 封装，`loading` 为 false 时不渲染任何内容。
+
+## 导入
+
+```tsx
+import { Loading } from '@xfe-repo/web-components'
+```
+
+## 基本用法
+
+```tsx
+import { Loading } from '@xfe-repo/web-components'
+
+function MyPage() {
+  const [loading, setLoading] = useState(true)
+
+  return (
+    <div>
+      <Loading loading={loading} />
+      <Content />
+    </div>
+  )
+}
+```
+
+### 条件式初始化加载（最常用模式）
+
+在数据未加载完成时展示 Loading，加载完成后渲染正常内容：
+
+```tsx
+function OrderDetail({ orderId }) {
+  const data = useSelector(selectOrderDetail)
+
+  // 数据未加载完成时，展示 Loading
+  if (!data) return <Loading loading={true} />
+
+  return (
+    <div>
+      <h2>{data.orderNo}</h2>
+      {/* 正常内容 */}
+    </div>
+  )
+}
+```
+
+### 路由懒加载 fallback
+
+```tsx
+const OrderPage = loadable(() => import('./pages/Order'), {
+  fallback: <Loading loading={true} />,
+})
+```
+
+## Props
+
+```typescript
+type Props = {
+  loading: boolean
+}
+```
+
+| 属性    | 类型      | 必填 | 默认值 | 说明                                   |
+| ------- | --------- | ---- | ------ | -------------------------------------- |
+| loading | `boolean` | 是   | -      | 是否显示加载状态，为 false 时返回 null |
+
+> 💡 内部 Spin 设置了 `delay={200}`，200ms 内完成的加载不会显示 loading 动画，避免闪烁。此值不可通过 props 自定义。

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

@@ -0,0 +1,145 @@
+# MultiWindow
+
+> 多窗口 Tab 容器，基于 KeepAlive 实现页面缓存，支持标签页拖拽排序、搜索、刷新和关闭操作。
+
+## 导入
+
+```tsx
+import { MultiWindow, MultiWindowContents, useMultiWindowContentsRef } from '@xfe-repo/web-components'
+import type { MultiWindowProps, PagePathType, MultiWindowContentsProps, MultiWindowContentsRefType } from '@xfe-repo/web-components'
+```
+
+## 基本用法
+
+```tsx
+import { MultiWindow, MultiWindowContents, useMultiWindowContentsRef } from '@xfe-repo/web-components'
+
+function Layout() {
+  const contentRef = useMultiWindowContentsRef()
+  const routerPath = window.location.pathname + window.location.search
+
+  return (
+    <div>
+      <MultiWindow routerPath={routerPath} contentRef={contentRef} appName="我的应用" />
+      <MultiWindowContents routerPath={routerPath} contentRef={contentRef}>
+        <RouterOutlet />
+      </MultiWindowContents>
+    </div>
+  )
+}
+```
+
+## 进阶用法
+
+### 自定义主题和黑名单
+
+通过 `collectionBlackList` 禁止某些路径启用搜索集合（默认对 detail 页面自动启用），通过 `theme` 传入 antd 主题配置。
+
+```tsx
+<MultiWindow
+  routerPath={routerPath}
+  contentRef={contentRef}
+  appName="ERP"
+  theme={{ token: { colorPrimary: '#1890ff' } }}
+  collectionBlackList={['/order/detail', '/refund/detail']}
+/>
+```
+
+## Props
+
+### MultiWindowProps
+
+```typescript
+export type MultiWindowProps = {
+  routerPath: string
+  collectionBlackList?: string[]
+  contentRef?: MultiWindowContentsRefType
+  appName?: string
+  theme?: ThemeConfig
+  className?: string
+}
+```
+
+| 属性                | 类型                         | 必填 | 默认值 | 说明                                         |
+| ------------------- | ---------------------------- | ---- | ------ | -------------------------------------------- |
+| routerPath          | `string`                     | 是   | -      | 当前路由路径（含 search）                    |
+| collectionBlackList | `string[]`                   | 否   | `[]`   | 不启用搜索集合的路径黑名单                   |
+| contentRef          | `MultiWindowContentsRefType` | 否   | -      | 内容页的 ref，用于控制缓存销毁               |
+| appName             | `string`                     | 否   | -      | 应用名称，用于从 document.title 中提取标签名 |
+| theme               | `ThemeConfig`                | 否   | -      | antd 主题配置                                |
+| className           | `string`                     | 否   | -      | 自定义 className                             |
+
+### MultiWindowContentsProps
+
+```typescript
+export type MultiWindowContentsProps = {
+  routerPath: string
+  children: ReactNode
+  contentRef?: MultiWindowContentsRefType
+}
+```
+
+| 属性       | 类型                         | 必填 | 默认值 | 说明                                  |
+| ---------- | ---------------------------- | ---- | ------ | ------------------------------------- |
+| routerPath | `string`                     | 是   | -      | 当前路由路径，用于提取 activeCacheKey |
+| children   | `ReactNode`                  | 是   | -      | 路由页面内容                          |
+| contentRef | `MultiWindowContentsRefType` | 否   | -      | KeepAlive ref，与 MultiWindow 共享    |
+
+## 导出类型
+
+### PagePathType
+
+```typescript
+export type PagePathType = {
+  label: string // 页面标签名
+  key: string // 页面路径（不含 search），用作唯一标识
+  fullPath: string // 页面完整路径（含 search）
+  closable?: boolean // 是否可关闭
+  disabled?: boolean // 是否禁用
+  searchCollection?: string[] // search 集合，用于存储同一页面不同搜索条件
+}
+```
+
+### MultiWindowContentsRefType
+
+```typescript
+export type MultiWindowContentsRefType = RefObject<KeepAliveRef | undefined>
+```
+
+## 子组件
+
+| 子组件                | 说明                                                                                           |
+| --------------------- | ---------------------------------------------------------------------------------------------- |
+| `MultiWindowContents` | 内容缓存容器，内部使用 `keepalive-for-react` 实现页面缓存，最多缓存 10 个页面，最长存活 1 小时 |
+
+## Ref 方法
+
+通过 `useMultiWindowContentsRef()` 获取的 ref 提供以下方法（来自 `KeepAliveRef`）：
+
+| 方法                | 说明                       |
+| ------------------- | -------------------------- |
+| `destroy(key)`      | 销毁指定页面的缓存         |
+| `destroyOther(key)` | 销毁除指定页面外的所有缓存 |
+
+## 常见陷阱
+
+- ❌ 忘记将 `contentRef` 同时传给 `MultiWindow` 和 `MultiWindowContents`：
+  ```tsx
+  <MultiWindow routerPath={path} contentRef={contentRef} />
+  <MultiWindowContents routerPath={path}>  {/* 缺少 contentRef，关闭标签时无法清除缓存 */}
+  ```
+- ✅ 两个组件共享同一个 `contentRef`：
+
+  ```tsx
+  const contentRef = useMultiWindowContentsRef()
+
+  <MultiWindow routerPath={path} contentRef={contentRef} />
+  <MultiWindowContents routerPath={path} contentRef={contentRef}>
+  ```
+
+## 注意事项
+
+- 标签页最多保留 **10 个**，超出后最早的标签会被自动移除
+- 标签状态通过 **sessionStorage** 持久化，刷新页面后自动恢复
+
+> 💡 MultiWindow 可独立使用（不依赖其他组件），用于管理多窗口/多标签页场景。

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

@@ -0,0 +1,230 @@
+# OSSImage
+
+> OSS 图片组件，基于 antd Image 封装，自动对阿里云 OSS 图片进行尺寸裁剪，支持预览原图和分组预览。
+
+## 导入
+
+```tsx
+import { OSSImage } from '@xfe-repo/web-components'
+import type { OSSImageProps } from '@xfe-repo/web-components'
+```
+
+## 基本用法
+
+```tsx
+import { OSSImage } from '@xfe-repo/web-components'
+
+function ProductImage() {
+  return <OSSImage src="https://imgs.eshetang.com/product/example.jpg" width={100} height={100} />
+}
+```
+
+### Table 列渲染
+
+最高频场景 — 在表格列中渲染商品/订单图片：
+
+```tsx
+const columns = [
+  {
+    title: '商品图片',
+    dataIndex: 'imageUrl',
+    render: (url: string) => (url ? <OSSImage width={60} height={60} src={url} /> : '-'),
+    align: 'center' as const,
+  },
+]
+```
+
+多图预览（配合 PreviewGroup）：
+
+```tsx
+const renderImages = (urls: string[]) => (
+  <OSSImage.PreviewGroup>
+    {urls.filter(Boolean).map((url) => (
+      <OSSImage key={url} width={60} height={60} src={url} preview={{ src: url }} />
+    ))}
+  </OSSImage.PreviewGroup>
+)
+```
+
+> 💡 始终对 `src` 做空值防守（三元或 `filter(Boolean)`），避免空 URL 导致的 broken image。
+
+### Descriptions 详情页展示
+
+在详情页中展示商品/订单图片：
+
+```tsx
+<Descriptions>
+  <Descriptions.Item label="商品图片">
+    <OSSImage width={120} height={120} src={data.imageUrl} preview />
+  </Descriptions.Item>
+</Descriptions>
+```
+
+## 进阶用法
+
+### 自定义裁剪宽度
+
+```tsx
+<OSSImage
+  src="https://imgs.eshetang.com/product/example.jpg"
+  resizeWidth={300} // 缩略图裁剪到 300px 宽
+/>
+```
+
+### 预览原图
+
+默认预览图也会被裁剪到 1200px，设置 `showOriginPreview` 可预览原始尺寸。
+
+```tsx
+<OSSImage src="https://imgs.eshetang.com/product/example.jpg" showOriginPreview />
+```
+
+### 清除默认 fallback
+
+默认在图片加载失败时显示占位图，设置 `clearDefault` 可禁用。
+
+```tsx
+<OSSImage src={imageSrc} clearDefault />
+```
+
+### 图片分组预览（PreviewGroup）
+
+```tsx
+<OSSImage.PreviewGroup>
+  <OSSImage src="https://imgs.eshetang.com/1.jpg" />
+  <OSSImage src="https://imgs.eshetang.com/2.jpg" />
+  <OSSImage src="https://imgs.eshetang.com/3.jpg" />
+</OSSImage.PreviewGroup>
+```
+
+### 弹窗分组预览（ModalGroup）
+
+点击第一张图片即可预览所有图片，常用于列表中的缩略图。
+
+```tsx
+<OSSImage.ModalGroup images={['https://imgs.eshetang.com/1.jpg', 'https://imgs.eshetang.com/2.jpg']} width={80} resizeWidth={300} />
+```
+
+### 交互式预览（countRender）
+
+在图片预览工具栏中嵌入业务操作按钮：
+
+```tsx
+const previewProps = {
+  countRender: (current: number, total: number) => {
+    const currentImage = images[current - 1]
+    return (
+      <Space>
+        {current} / {total}
+        <Button type="primary" onClick={() => handleAction(currentImage)}>
+          选择此图
+        </Button>
+      </Space>
+    ) as unknown as string  // antd 类型定义限制，实际支持 ReactNode
+  },
+}
+
+<OSSImage.PreviewGroup preview={previewProps}>
+  {images.map((img) => (
+    <OSSImage key={img.id} width={100} height={100} src={img.url} />
+  ))}
+</OSSImage.PreviewGroup>
+```
+
+> ⚠️ `countRender` 的 antd 类型签名要求返回 `string`，但实际支持 `ReactNode`。需要使用 `as unknown as string` 类型断言。
+
+### 常用继承属性
+
+OSSImage 支持所有 antd Image 属性，常用的有：
+
+```tsx
+<OSSImage
+  src={url}
+  width={100}
+  height={100}
+  alt="商品图片" // 无障碍文案
+  style={{ borderRadius: 8 }} // 圆角
+  className="product-img" // 自定义样式类
+  preview={{ src: originalUrl }} // 预览时使用原图
+  fallback={defaultImg} // 加载失败时的兜底图
+/>
+```
+
+### 后端逗号分隔字符串格式
+
+后端常返回逗号分隔的图片 URL 字符串，需转换后渲染：
+
+```tsx
+const renderImages = (urlStr: string) => {
+  const urls = urlStr?.split(',').filter(Boolean) ?? []
+  return (
+    <OSSImage.PreviewGroup>
+      {urls.map((url) => (
+        <OSSImage key={url} width={60} height={60} src={url} />
+      ))}
+    </OSSImage.PreviewGroup>
+  )
+}
+```
+
+## Props
+
+### OSSImageProps
+
+```typescript
+export interface OSSImageProps extends ImageProps {
+  resizeWidth?: number
+  clearDefault?: boolean
+  showOriginPreview?: boolean
+}
+```
+
+| 属性              | 类型         | 必填 | 默认值  | 说明                                      |
+| ----------------- | ------------ | ---- | ------- | ----------------------------------------- |
+| resizeWidth       | `number`     | 否   | `750`   | 缩略图裁剪宽度（通过阿里云 OSS 图片处理） |
+| clearDefault      | `boolean`    | 否   | `false` | 是否清除默认 fallback 占位图              |
+| showOriginPreview | `boolean`    | 否   | `false` | 预览时是否使用原始图片（裁剪到 1200px）   |
+| ...imageProps     | `ImageProps` | 否   | -       | 所有 antd Image 属性                      |
+
+### OSSImageGroupProps（ModalGroup）
+
+```typescript
+export interface OSSImageGroupProps extends Pick<ImageProps, 'fallback' | 'height' | 'width' | 'onError' | 'rootClassName'> {
+  resizeWidth?: number
+  images: string[]
+}
+```
+
+| 属性        | 类型       | 必填 | 默认值     | 说明               |
+| ----------- | ---------- | ---- | ---------- | ------------------ |
+| images      | `string[]` | 是   | -          | 图片 URL 数组      |
+| resizeWidth | `number`   | 否   | `750`      | 缩略图裁剪宽度     |
+| width       | `number`   | 否   | `100`      | 缩略图宽度         |
+| fallback    | `string`   | 否   | 默认占位图 | 加载失败时的占位图 |
+
+## 子组件
+
+| 子组件                  | 说明                                                |
+| ----------------------- | --------------------------------------------------- |
+| `OSSImage.PreviewGroup` | 图片分组预览，直接透传 antd 的 `Image.PreviewGroup` |
+| `OSSImage.ModalGroup`   | 弹窗分组预览，点击首张图片弹出预览所有图片          |
+
+## 常见陷阱
+
+- ❌ 直接使用 antd `Image` 加载 OSS 大图，页面加载慢：
+  ```tsx
+  <Image src="https://imgs.eshetang.com/product/big-image.jpg" width={100} />
+  ```
+- ✅ 使用 `OSSImage` 自动裁剪，缩略图加载 750px，预览加载 1200px：
+  ```tsx
+  <OSSImage src="https://imgs.eshetang.com/product/big-image.jpg" width={100} />
+  ```
+
+> 💡 可以只设 `height` 不设 `width`（或反过来），图片将按比例自适应另一维度。
+
+## 相关组件
+
+| 场景               | 组件               | 说明                                |
+| ------------------ | ------------------ | ----------------------------------- |
+| 文件上传           | `FileUpload`       | 上传组件，预览部分内部使用 OSSImage |
+| 文件上传（带接口） | `EffectFileUpload` | 带 API 上传能力的文件上传           |

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

@@ -0,0 +1,90 @@
+# PrivacyField
+
+> 隐私脱敏字段组件，展示脱敏值并支持本地解密查看原始值，内置神策埋点。
+
+## 导入
+
+```tsx
+import { PrivacyField } from '@xfe-repo/web-components'
+```
+
+## 基本用法
+
+```tsx
+import { PrivacyField } from '@xfe-repo/web-components'
+
+function UserInfo() {
+  return <PrivacyField value="138****1234" encryptedValue="base64_encrypted_string" />
+}
+```
+
+## 进阶用法
+
+### Table 列渲染
+
+```tsx
+const columns = [
+  {
+    title: '手机号',
+    dataIndex: 'phone',
+    render: (phone: string) => <PrivacyField value={phone} />,
+  },
+]
+```
+
+### 带埋点的解密
+
+每条数据在组件生命周期内仅触发一次埋点。
+
+```tsx
+<PrivacyField
+  value="138****1234"
+  encryptedValue={encrypted}
+  trackEventName="view_phone_number"
+  trackEventParams={{ userId: 123, source: 'order_list' }}
+/>
+```
+
+### 仅展示脱敏值（无解密按钮）
+
+```tsx
+<PrivacyField value="138****1234" />
+```
+
+### 隐藏解密按钮
+
+```tsx
+<PrivacyField
+  value="138****1234"
+  encryptedValue={encrypted}
+  showDecryptButton={false} // 有加密值但不显示解密按钮
+/>
+```
+
+## Props
+
+```typescript
+interface PrivacyFieldProps {
+  value: string
+  encryptedValue?: string
+  showDecryptButton?: boolean
+  trackEventName?: string
+  trackEventParams?: Record<string, any>
+}
+```
+
+| 属性              | 类型                  | 必填 | 默认值 | 说明                               |
+| ----------------- | --------------------- | ---- | ------ | ---------------------------------- |
+| value             | `string`              | 是   | -      | 脱敏后的展示值（如 `138****1234`） |
+| encryptedValue    | `string`              | 否   | -      | 后端返回的加密值，用于前端解密     |
+| showDecryptButton | `boolean`             | 否   | `true` | 是否展示解密按钮                   |
+| trackEventName    | `string`              | 否   | -      | 神策事件名称                       |
+| trackEventParams  | `Record<string, any>` | 否   | `{}`   | 神策事件参数                       |
+
+## 常见陷阱
+
+- ❌ 无 `encryptedValue` 或 `showDecryptButton={false}` 时，组件仅渲染一个 `<span>`，不显示眼睛图标
+- ✅ 解密在前端完成（XOR + Base64），无需额外请求后端
+
+- ❌ `encryptedValue` 变化时，解密状态会自动重置为隐藏
+- ✅ 这是预期行为，防止切换数据时误显示上一条的解密值

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

@@ -0,0 +1,148 @@
+# QRCode
+
+> 二维码展示组件，配合 `useSseQrcode` Hook 实现 SSE 轮询扫码状态，支持过期刷新和多次扫码。
+
+## 导入
+
+```tsx
+import { QRCode, useSseQrcode, QRCodeStatus } from '@xfe-repo/web-components'
+import type { QRCodePropsType, UseRemoteUploadConfigType, SseEventDataType } from '@xfe-repo/web-components'
+```
+
+## 基本用法
+
+### 纯展示二维码
+
+```tsx
+import { QRCode } from '@xfe-repo/web-components'
+
+function SimpleQRCode() {
+  return <QRCode url="https://example.com/qrcode.png" />
+}
+```
+
+### 配合 SSE 轮询
+
+```tsx
+import { QRCode, useSseQrcode } from '@xfe-repo/web-components'
+
+function ScanUpload() {
+  const [result] = useSseQrcode({
+    enable: true,
+    createQRCode: async (requestConfig) => {
+      const { data } = await api.createQRCode({}, requestConfig)
+      return data // { uuid: string, qrcode: string }
+    },
+    sseUrl: '/common/upload/remote/sse',
+    onSuccess: (payload) => {
+      console.log('扫码成功:', payload)
+    },
+  })
+
+  return (
+    <QRCode
+      url={result.qrCodeUrl || ''}
+      status={result.qrCodeStatus}
+      onRefresh={result.refreshQRCode}
+      refreshLoading={result.refreshLoading}
+    />
+  )
+}
+```
+
+## 进阶用法
+
+### 支持多次扫码
+
+设置 `multiple` 后，完成状态也会显示刷新按钮，允许重新扫码。
+
+```tsx
+<QRCode
+  url={result.qrCodeUrl || ''}
+  status={result.qrCodeStatus}
+  onRefresh={result.refreshQRCode}
+  refreshLoading={result.refreshLoading}
+  multiple
+/>
+```
+
+## Props
+
+### QRCodePropsType
+
+```typescript
+export type QRCodePropsType = {
+  url: string
+  status?: QRCodeStatus
+  onRefresh?: () => void
+  refreshLoading?: boolean
+  multiple?: boolean
+}
+```
+
+| 属性           | 类型           | 必填 | 默认值  | 说明                                     |
+| -------------- | -------------- | ---- | ------- | ---------------------------------------- |
+| url            | `string`       | 是   | -       | 二维码图片地址                           |
+| status         | `QRCodeStatus` | 否   | -       | 二维码状态                               |
+| onRefresh      | `() => void`   | 否   | -       | 刷新按钮回调                             |
+| refreshLoading | `boolean`      | 否   | `false` | 刷新中 loading 状态                      |
+| multiple       | `boolean`      | 否   | -       | 是否支持多次扫码（完成后仍显示刷新按钮） |
+
+## 导出类型
+
+### QRCodeStatus
+
+```typescript
+export enum QRCodeStatus {
+  ACTIVE = 'active', // 等待扫码
+  SCANNED = 'scanned', // 扫码成功
+  EXPIRED = 'expired', // 二维码已失效
+  COMPLETE = 'complete', // 已完成
+}
+```
+
+### useSseQrcode
+
+```typescript
+export const useSseQrcode: <SuccessPayloadType>(
+  config: UseRemoteUploadConfigType<SuccessPayloadType>,
+) => [{ qrCodeUrl?: string; qrCodeStatus?: QRCodeStatus; refreshQRCode: () => void; refreshLoading: boolean; sseLoading: boolean }]
+```
+
+### UseRemoteUploadConfigType
+
+```typescript
+export type UseRemoteUploadConfigType<SuccessPayloadType = any> = {
+  createQRCode: (requestConfig: BFFRequestConfig) => Promise<{ uuid: string; qrcode: string }>
+  sseUrl: string
+  enable?: boolean
+  onSuccess?: (data: SuccessPayloadType) => void
+}
+```
+
+| 属性         | 类型                                    | 必填 | 默认值 | 说明                               |
+| ------------ | --------------------------------------- | ---- | ------ | ---------------------------------- |
+| createQRCode | `(config) => Promise<{ uuid, qrcode }>` | 是   | -      | 创建二维码的异步函数               |
+| sseUrl       | `string`                                | 是   | -      | SSE 地址（会拼接 baseURL 和 uuid） |
+| enable       | `boolean`                               | 否   | -      | 是否启用，为 true 时自动创建二维码 |
+| onSuccess    | `(data) => void`                        | 否   | -      | 扫码完成回调                       |
+
+### SseEventDataType
+
+```typescript
+export type SseEventDataType<SuccessPayloadType> = {
+  data: { status: QRCodeStatus; payload: SuccessPayloadType }
+}
+```
+
+## 常见陷阱
+
+- ❌ SSE 连接出错时状态自动变为 `EXPIRED`，需要用户点击刷新按钮重新创建
+- ✅ 组件卸载时会自动关闭 EventSource 连接
+
+## 相关组件
+
+| 场景     | 组件               | 说明                                        |
+| -------- | ------------------ | ------------------------------------------- |
+| 远程上传 | `FileUpload`       | `remote` 模式内部使用 QRCode + useSseQrcode |
+| 文件上传 | `EffectFileUpload` | 带 API 上传的增强版                         |