@gmfe/react 2.14.30-alpha.0 → 2.14.31

package/src/component/nav/README.md

@@ -0,0 +1,101 @@
+# Nav
+
+## 简介
+导航菜单组件 - 支持三级导航结构的侧边栏导航，鼠标悬停显示二级、三级菜单的弹出浮层。
+
+## 安装
+已包含在 `@gmfe/react` 中，无需额外安装。
+
+## 使用
+```jsx
+import Nav from '@gmfe/react/lib/nav'
+
+<Nav
+  logo={<img src='/logo.png' alt='logo' />}
+  data={navData}
+  selected={currentPath}
+  onSelect={item => console.log(item)}
+/>
+```
+
+## API
+
+### Nav Props
+| 属性 | 说明 | 类型 | 默认值 | 必填 |
+|------|------|------|--------|------|
+| logo | Logo 元素 | `ReactElement` | - | 否 |
+| logoActive | Logo 区域是否激活 | `bool` | - | 否 |
+| data | 三级菜单数据，结构为 `[{link, name, icon, sub: [{link, name, style, sub: [{link, name}]}]}]`，sub 没有的话就没有 popup | `array` | - | 是 |
+| selected | 当前路由地址，会匹配到第三级 link | `string` | - | 是 |
+| onSelect | 点击菜单回调，返回选中的第三级 item 数据 | `(item: object) => void` | - | 是 |
+| showActive | 控制浮层的显示，传入对应一级菜单的 link 值 | `string` | - | 否 |
+| other | 其他自定义内容元素（如应用中心入口），显示在底部 | `ReactElement` | - | 否 |
+| className | 自定义类名 | `string` | - | 否 |
+| style | 自定义样式 | `object` | - | 否 |
+
+### Nav.SingleItem Props
+用于在 `other` 属性中渲染无二级菜单的一级菜单项。
+
+| 属性 | 说明 | 类型 | 默认值 | 必填 |
+|------|------|------|--------|------|
+| data | 菜单项数据，结构为 `{link, name, icon}` | `object` | - | 是 |
+| selected | 当前路由地址 | `string` | - | 是 |
+| onSelect | 点击菜单回调，返回当前 data | `(item: object) => void` | - | 是 |
+
+## 示例
+
+### 基础用法
+```jsx
+const navData = [
+  {
+    link: '/merchandise',
+    name: '商品',
+    sub: [
+      {
+        name: '商品管理',
+        link: '/merchandise/manage',
+        sub: [
+          { link: '/merchandise/manage/sale', name: '报价单管理' },
+          { link: '/merchandise/manage/list', name: '商品库' }
+        ]
+      }
+    ]
+  },
+  {
+    link: '/supply_chain',
+    name: '供应链',
+    sub: [
+      {
+        name: '订单',
+        link: '/supply_chain/order',
+        sub: [
+          { link: '/supply_chain/order/list', name: '订单列表' }
+        ]
+      }
+    ]
+  }
+]
+
+const application = { name: '应用中心', link: '/application_center' }
+
+<Nav
+  logo={<img src='/logo.png' style={{ maxHeight: '35px', maxWidth: '80px' }} />}
+  data={navData}
+  selected='/merchandise/manage/sale'
+  onSelect={item => navigate(item.link)}
+  other={
+    <Nav.SingleItem
+      data={application}
+      selected={currentPath}
+      onSelect={item => navigate(item.link)}
+    />
+  }
+/>
+```
+
+## 注意事项
+- data 为三级菜单结构，如果一级菜单没有 `sub` 字段则不会显示弹出浮层
+- `selected` 传入当前路由地址，组件会自动匹配到第三级 link 并高亮显示
+- 弹出浮层会自动适应屏幕底部边界，超出时会向上偏移
+- 弹出浮层通过 Portal 渲染到 `gmNavPopupContainer` 容器中
+- 使用 `Nav.SingleItem` 可在底部区域添加没有二级菜单的独立菜单项

package/src/component/nprogress/README.md

@@ -0,0 +1,135 @@
+# NProgress
+
+## 简介
+页面顶部进度条组件 - 在页面顶部显示加载进度条，适用于路由切换或异步请求时的全局加载指示，支持多次 start/done 的计数管理
+
+## 安装
+已包含在 `@gmfe/react` 中，无需额外安装。
+
+## 使用
+```jsx
+import { NProgress } from '@gmfe/react'
+```
+
+## API
+
+### 静态方法
+
+| 方法 | 说明 | 参数 | 返回值 |
+|------|------|------|--------|
+| `NProgress.start()` | 开始显示进度条，内部维护计数器，多次调用不会重复显示 | - | - |
+| `NProgress.done()` | 完成并隐藏进度条，每次调用减少计数器，计数归零时才真正隐藏 | - | - |
+
+## 示例
+
+### 基础用法
+
+```jsx
+import { NProgress } from '@gmfe/react'
+
+// 开始加载
+NProgress.start()
+
+// 加载完成后
+NProgress.done()
+```
+
+### 配合 axios 请求拦截器使用
+
+```jsx
+import axios from 'axios'
+import { NProgress } from '@gmfe/react'
+
+// 请求拦截器
+axios.interceptors.request.use(config => {
+  NProgress.start()
+  return config
+})
+
+// 响应拦截器
+axios.interceptors.response.use(
+  response => {
+    NProgress.done()
+    return response
+  },
+  error => {
+    NProgress.done()
+    return Promise.reject(error)
+  }
+)
+```
+
+### 配合 React Router 路由切换使用
+
+```jsx
+import React from 'react'
+import { BrowserRouter, Route, Switch } from 'react-router-dom'
+import { NProgress } from '@gmfe/react'
+
+function App() {
+  return (
+    <BrowserRouter>
+      <Route
+        render={({ location }) => {
+          NProgress.start()
+          return (
+            <Switch location={location}>
+              <Route path="/" component={Home} />
+              <Route path="/about" component={About} />
+            </Switch>
+          )
+        }}
+      />
+    </BrowserRouter>
+  )
+}
+
+// 在页面组件中完成后调用
+function Home() {
+  React.useEffect(() => {
+    NProgress.done()
+  }, [])
+
+  return <div>首页</div>
+}
+```
+
+### 并发请求
+
+```jsx
+// 多次 start 只会显示一个进度条
+NProgress.start() // 计数: 1
+NProgress.start() // 计数: 2
+NProgress.start() // 计数: 3
+
+// 每次 done 减少计数
+NProgress.done() // 计数: 2, 进度条仍在
+NProgress.done() // 计数: 1, 进度条仍在
+NProgress.done() // 计数: 0, 进度条隐藏
+```
+
+### 配合 Promise.all 多个请求
+
+```jsx
+async function loadPageData() {
+  NProgress.start()
+  try {
+    const [users, orders, products] = await Promise.all([
+      api.getUsers(),
+      api.getOrders(),
+      api.getProducts()
+    ])
+    // 处理数据...
+  } finally {
+    NProgress.done()
+  }
+}
+```
+
+## 注意事项
+
+- NProgress 使用内部计数器管理进度条的显示和隐藏，支持并发场景。多次调用 `start()` 只会显示一个进度条，需要相同次数的 `done()` 才会隐藏。
+- 进度条完成后会有 250ms 的完成动画，然后才从 DOM 中移除。
+- 进度条渲染到 `LayoutRoot` 中，位于页面顶部，通常不需要手动定位。
+- 进度条有两种 CSS 状态：`gm-nprogress-loading`（加载中）和 `gm-nprogress-completed`（完成）。
+- 不支持组件形式的调用，仅提供静态方法。

package/src/component/pagination/README.md

@@ -0,0 +1,87 @@
+# Pagination
+
+## 简介
+分页组件 - 提供多种分页模式，包括带总数的分页、不带总数的分页以及纯文本展示模式。
+
+## 安装
+已包含在 `@gmfe/react` 中，无需额外安装。
+
+## 使用
+```jsx
+import Pagination from '@gmfe/react/lib/pagination/pagination'
+import PaginationV2 from '@gmfe/react/lib/pagination/pagination_v2'
+import PaginationText from '@gmfe/react/lib/pagination/pagination_text'
+```
+
+## API
+
+### Pagination Props
+带 `toPage` 回调的分页组件，根据 data 中是否包含 count 自动判断显示模式。
+
+| 属性 | 说明 | 类型 | 默认值 | 必填 |
+|------|------|------|--------|------|
+| data | 分页数据 | `{ count?: number, offset: number, limit: number }` | - | 是 |
+| toPage | 翻页回调，参数为 `{offset, limit}`，可直接用于请求后台 | `({offset, limit}) => void` | - | 是 |
+| nextDisabled | 下一页按钮禁用（仅在 data 无 count 时有效） | `bool` | - | 否 |
+| className | 自定义类名 | `string` | - | 否 |
+| style | 自定义样式 | `object` | - | 否 |
+| limitData | 自定义分页，默认空数组 | `array` | - | 否 |
+
+### PaginationV2 Props
+直接使用 `onChange` 回调的分页组件（一般通过 PaginationBox 使用）。
+
+| 属性 | 说明 | 类型 | 默认值 | 必填 |
+|------|------|------|--------|------|
+| data | 分页数据，count 仅代表当前有多少条数据（非总数） | `{ count: number, offset: number, limit: number }` | - | 是 |
+| onChange | 翻页回调，参数为 `{offset, limit}` | `({offset, limit}) => void` | - | 是 |
+| showCount | 是否显示总数 | `bool` | - | 否 |
+| className | 自定义类名 | `string` | - | 否 |
+| style | 自定义样式 | `object` | - | 否 |
+
+### PaginationText Props
+纯文本展示分页信息（已废弃）。
+
+| 属性 | 说明 | 类型 | 默认值 | 必填 |
+|------|------|------|--------|------|
+| data | 分页数据 | `{ count?: number, offset: number, limit: number }` | - | 否 |
+
+## 示例
+
+### Pagination 带总数
+```jsx
+<Pagination
+  data={{ count: 70, offset: 0, limit: 10 }}
+  toPage={({ offset, limit }) => {
+    fetchData({ offset, limit })
+  }}
+/>
+```
+
+### Pagination 不带总数
+```jsx
+<Pagination
+  data={{ offset: 0, limit: 10 }}
+  toPage={({ offset, limit }) => {
+    fetchData({ offset, limit })
+  }}
+  nextDisabled={false}
+/>
+```
+
+### PaginationV2
+```jsx
+<PaginationV2
+  data={{ count: 70, offset: 0, limit: 10 }}
+  onChange={({ offset, limit }) => {
+    fetchData({ offset, limit })
+  }}
+  showCount
+/>
+```
+
+## 注意事项
+- `Pagination` 组件根据 `data.count` 是否存在自动切换显示模式：有 count 时显示总数，无 count 时不显示总数
+- `PaginationV2` 一般不直接使用，而是通过 `PaginationBox` 组件使用
+- `PaginationText` 已废弃，使用时会在控制台输出警告
+- `PaginationV2` 中 `data.count` 是当前数据条数，而非传统意义上的总条数
+- 分页规范参考：[分页规范文档](https://www.yuque.com/iyum9i/cudrs0/etfogz)

package/src/component/picture_preview/README.md

@@ -0,0 +1,50 @@
+# PicturePreview
+
+## 简介
+图片预览组件 - 基于 `react-photo-view` 的图片查看器，点击图片可放大预览
+
+## 安装
+已包含在 `@gmfe/react` 中，无需额外安装。
+
+## 使用
+```jsx
+import { PicturePreview } from '@gmfe/react'
+
+<PicturePreview
+  images={['img1.jpg', 'img2.jpg', 'img3.jpg']}
+/>
+```
+
+## API
+
+### Props
+| 属性 | 说明 | 类型 | 默认值 | 必填 |
+|------|------|------|--------|------|
+| images | 图片 URL 数组 | `array` | `[]` | 否 |
+| className | 图片自定义类名 | `string` | - | 否 |
+
+## 示例
+
+### 基础用法
+```jsx
+<PicturePreview
+  images={[
+    'https://example.com/img1.jpg',
+    'https://example.com/img2.jpg',
+    'https://example.com/img3.jpg'
+  ]}
+/>
+```
+
+### 自定义样式
+```jsx
+<PicturePreview
+  images={['img1.jpg', 'img2.jpg']}
+  className="custom-img-class"
+/>
+```
+
+## 注意事项
+- 底层依赖 `react-photo-view`，需要确保该包已安装
+- 图片点击后会进入全屏预览模式，支持缩放、滑动等手势操作
+- 如果 `images` 为空或 `undefined`，不会渲染任何内容

package/src/component/popover/README.md

@@ -0,0 +1,146 @@
+# Popover
+
+## 简介
+弹出层组件 - 提供灵活的弹出气泡功能，支持 focus、click、hover、realFocus 四种触发方式，可控制弹出位置、偏移和箭头方向
+
+## 安装
+已包含在 `@gmfe/react` 中，无需额外安装。
+
+## 使用
+```jsx
+import { Popover } from '@gmfe/react'
+```
+
+## API
+
+### Props
+
+| 属性 | 说明 | 类型 | 默认值 | 必填 |
+|------|------|------|--------|------|
+| type | 触发方式：`focus` 类似 click 但不因二次点击关闭；`click` 点击切换；`hover` 鼠标悬浮；`realFocus` 原生 focus 事件，失焦隐藏 | `'focus' \| 'click' \| 'hover' \| 'realFocus'` | `'focus'` | 否 |
+| popup | 弹出层内容，支持传入元素或返回元素的函数 | `element \| func` | - | 是 |
+| children | 触发元素（仅支持单个子元素） | `any` | - | 是 |
+| disabled | 是否禁用弹出，也可以通过 children 的 `disabled` 属性控制 | `bool` | `false` | 否 |
+| className | 弹出层自定义类名 | `string` | - | 否 |
+| style | 弹出层自定义样式 | `object` | - | 否 |
+| right | 是否右对齐弹出 | `bool` | `false` | 否 |
+| top | 是否向上弹出 | `bool` | `false` | 否 |
+| center | 是否居中对齐弹出 | `bool` | `false` | 否 |
+| offset | 偏移量（像素） | `number` | `0` | 否 |
+| showArrow | 是否显示三角标 | `bool` | `false` | 否 |
+| arrowLeft | 三角标的左偏移位置 | `string` | - | 否 |
+| pureContainer | 是否使用纯粹容器（无背景色、无阴影） | `bool` | `false` | 否 |
+| isInPopup | 弹出层是否嵌套在另一个 popup 中 | `bool` | `false` | 否 |
+| predictingHeight | 预判高度。因为 popup 的宽高是可变的，无法自动判断视窗内是否能放得下，可手动设置 | `number` | - | 否 |
+
+### 实例方法
+
+| 方法 | 说明 | 参数 |
+|------|------|------|
+| `apiDoSetActive(active)` | 编程式控制弹出层的显示/隐藏 | `active: bool` |
+
+## 示例
+
+### 四种触发方式
+
+```jsx
+// focus 模式（默认）- 类似 click 但不因二次点击关闭
+<Popover popup={renderPopup()}>
+  <Button>focus me</Button>
+</Popover>
+
+// click 模式 - 点击切换显示/隐藏
+<Popover type='click' popup={renderPopup()}>
+  <Button>click me</Button>
+</Popover>
+
+// hover 模式 - 鼠标悬浮显示，移开隐藏
+<Popover type='hover' showArrow popup={renderPopup()}>
+  <Button>hover me</Button>
+</Popover>
+
+// realFocus 模式 - 原生 focus 事件，失焦自动隐藏
+<Popover type='realFocus' showArrow popup={renderPopup()}>
+  <Button>realFocus me</Button>
+</Popover>
+```
+
+### 控制弹出位置
+
+```jsx
+// 默认 - 左下方弹出
+<Popover popup={renderPopup()}>
+  <Button>默认位置</Button>
+</Popover>
+
+// 右对齐 - 右下方弹出
+<Popover right popup={renderPopup()}>
+  <Button>右对齐</Button>
+</Popover>
+
+// 居中 - 正下方居中弹出
+<Popover center popup={renderPopup()}>
+  <Button>居中对齐</Button>
+</Popover>
+
+// 向上 - 上方弹出
+<Popover top popup={renderPopup()}>
+  <Button>向上弹出</Button>
+</Popover>
+```
+
+### 偏移位置
+
+```jsx
+<Popover offset={20} popup={renderPopup()}>
+  <Button>向下偏移 20px</Button>
+</Popover>
+
+<Popover offset={-20} popup={renderPopup()}>
+  <Button>向上偏移 20px</Button>
+</Popover>
+```
+
+### 带箭头
+
+```jsx
+<Popover showArrow popup={renderPopup()}>
+  <Button>带箭头</Button>
+</Popover>
+
+// 自定义箭头位置
+<Popover showArrow arrowLeft='0px' popup={renderPopup()}>
+  <Button>箭头靠左</Button>
+</Popover>
+```
+
+### 禁用状态
+
+```jsx
+// 通过 disabled 属性
+<Popover disabled popup={renderPopup()}>
+  <Button>已禁用</Button>
+</Popover>
+
+// 通过子元素的 disabled 属性
+<Popover popup={renderPopup()}>
+  <Button disabled>子元素禁用</Button>
+</Popover>
+```
+
+### 使用函数作为 popup
+
+```jsx
+<Popover popup={() => <div>动态内容</div>}>
+  <Button>函数式 popup</Button>
+</Popover>
+```
+
+## 注意事项
+
+- Popover 只接受单个子元素（`React.Children.only`），需要用一个容器元素包裹触发内容。
+- `type` 为 `focus` 时，行为类似 click 但不会因二次点击而关闭弹出层；如需真正的原生 focus 效果（失焦隐藏），请使用 `type='realFocus'`。
+- `popup` 属性不会随组件 re-render 自动更新，如需动态内容请使用函数形式传入。
+- Popover 会自动监听 Modal 滚动、Drawer 滚动、浏览器滚动和表格滚动事件，滚动时自动重新计算弹出层位置。
+- hover 模式下，鼠标移出触发元素后会有 500ms 的延迟才关闭弹出层。
+- `disabled` 支持两种方式：通过 Popover 的 `disabled` 属性，或通过子元素的 `disabled` 属性自动检测。

package/src/component/popup/README.md

@@ -0,0 +1,121 @@
+# Popup
+
+## 简介
+弹出定位组件 - 基于目标元素位置的弹出层容器，自动计算弹出位置并支持视窗边界检测，通常配合 Popover 组件使用
+
+## 安装
+已包含在 `@gmfe/react` 中，无需额外安装。
+
+## 使用
+```jsx
+import { Popup, PopupContentConfirm } from '@gmfe/react'
+```
+
+## API
+
+### Popup 组件 Props
+
+| 属性 | 说明 | 类型 | 默认值 | 必填 |
+|------|------|------|--------|------|
+| children | 弹出层内容 | `any` | - | 否 |
+| rect | 目标元素的位置信息（包含 `top`、`left`、`width`、`height`） | `object` | - | 是 |
+| className | 自定义类名 | `string` | - | 否 |
+| style | 自定义样式 | `object` | - | 否 |
+| top | 是否向上弹出 | `bool` | `false` | 否 |
+| right | 是否右对齐弹出 | `bool` | `false` | 否 |
+| center | 是否居中对齐弹出 | `bool` | `false` | 否 |
+| offset | 偏移量（像素） | `number` | `0` | 否 |
+| showArrow | 是否显示三角标 | `bool` | `false` | 否 |
+| arrowLeft | 三角标的左偏移位置 | `string` | - | 否 |
+| predictingHeight | 预判高度，因弹出层宽高可变无法自动判断视窗内是否能放得下时可手动设置 | `number` | - | 否 |
+| pureContainer | 是否使用纯粹容器（无背景色、无阴影） | `bool` | `false` | 否 |
+
+### PopupContentConfirm 组件 Props
+
+| 属性 | 说明 | 类型 | 默认值 | 必填 |
+|------|------|------|--------|------|
+| type | 确认类型，决定底部按钮的展示方式 | `'save' \| 'delete'` | `'save'` | 否 |
+| title | 标题 | `string` | - | 否 |
+| onCancel | 取消回调 | `func` | - | 是 |
+| onDelete | 删除回调（`type='delete'` 时使用） | `func` | - | 否 |
+| onSave | 保存回调（`type='save'` 时使用） | `func` | - | 否 |
+| className | 自定义类名 | `string` | - | 否 |
+| hideClose | 是否隐藏关闭按钮 | `bool` | `false` | 否 |
+| style | 自定义样式 | `object` | - | 否 |
+| children | 内容 | `any` | - | 否 |
+
+## 示例
+
+### Popup 基础用法
+
+Popup 通常由 Popover 组件内部调用，以下展示直接使用的场景：
+
+```jsx
+<Popup
+  rect={{ top: 100, left: 200, width: 100, height: 40 }}
+  showArrow
+>
+  <div>弹出层内容</div>
+</Popup>
+```
+
+### Popup 向上弹出
+
+```jsx
+<Popup
+  rect={{ top: 300, left: 200, width: 100, height: 40 }}
+  top
+  showArrow
+>
+  <div>向上弹出的内容</div>
+</Popup>
+```
+
+### PopupContentConfirm - 保存类型
+
+```jsx
+<PopupContentConfirm
+  title="编辑信息"
+  onCancel={() => console.log('取消')}
+  onSave={() => console.log('保存')}
+>
+  <div>
+    <input placeholder="请输入内容" />
+  </div>
+</PopupContentConfirm>
+```
+
+### PopupContentConfirm - 删除类型
+
+```jsx
+<PopupContentConfirm
+  type="delete"
+  title="确认删除"
+  onCancel={() => console.log('取消')}
+  onDelete={() => console.log('删除')}
+>
+  <div>确定要删除这条数据吗？</div>
+</PopupContentConfirm>
+```
+
+### PopupContentConfirm - 隐藏关闭按钮
+
+```jsx
+<PopupContentConfirm
+  title="不可关闭"
+  hideClose
+  onCancel={() => console.log('取消')}
+  onSave={() => console.log('保存')}
+>
+  <div>内容区域</div>
+</PopupContentConfirm>
+```
+
+## 注意事项
+
+- Popup 通常不直接使用，而是由 Popover 组件内部管理。如需弹出层功能，建议直接使用 Popover 组件。
+- Popup 具有自动边界检测能力：当向上弹出空间不足时会自动切换到向下弹出，反之亦然。
+- `rect` 属性是必填项，需要包含目标元素的 `top`、`left`、`width`、`height` 信息。
+- `pureContainer` 为 `true` 时，弹出层将去除背景色和阴影，适用于需要自定义外观的场景。
+- PopupContentConfirm 是一个预设布局的弹出内容组件，提供了标题、内容区和底部操作按钮的标准结构。
+- PopupContentConfirm 的 `type` 属性控制底部按钮：`save` 显示"取消"和"保存"按钮，`delete` 显示"取消"和红色"删除"按钮。