@pisell/materials 1.8.41 → 1.8.42

package/lib/components/pisellDataSourceContainer/docs/PisellDataSourceContainer.md

@@ -3,7 +3,7 @@ nav:
   title: 组件
   order: 1
 group:
-  title: Data Entry
+  title: 基础组件
   order: 1
 title: PisellDataSourceContainer
 order: 1
@@ -12,37 +12,72 @@ category: pro
 
 # PisellDataSourceContainer 数据源容器
 
-PisellDataSourceContainer 为列表页提供统一的数据管理、操作处理、状态共享与子组件协调能力，内置数据源管理、list/get/create/update/destroy 操作、RefManager 与 SharedState、以及 Filter/Table/Pagination/Sort 等子组件的 props 管理。
+PisellDataSourceContainer 是一个强大的数据源容器组件，为列表页面提供统一的数据管理、操作处理、状态共享和子组件协调能力。
 
-## 何时使用
+## 设计理念
 
-- 列表页需要统一的数据源与查询/分页/筛选
-- 多子组件（筛选、表格、分页、排序）需共享数据与操作
-- 需要跨组件共享状态（如选中行、当前 Tab）而不 props 层层下传
-- 基于同一套数据源的增删改查与表格联动
+在后台管理系统中，大量页面都涉及数据的增删改查（CRUD）操作。PisellDataSourceContainer 将这些通用的数据操作能力进行了封装和抽象，提供了以下核心能力:
 
-## 特性
+- **数据源管理**: 统一管理数据源配置，支持动态切换
+- **操作处理**: 封装 list、get、create、update、destroy 等常用操作
+- **状态共享**: 提供 RefManager 和 SharedState 机制，实现跨组件状态管理
+- **子组件协调**: 统一管理 Filter、Table、Pagination、Sort 等子组件的 props
+- **表单集成**: 内置 Form 实例，自动处理表单变化并触发数据查询
 
-- **数据源管理**：统一 dataSource 配置，支持动态切换、extraParams、overrideData
-- **操作封装**：list.onSearch / onReset / onPageChange，以及 get、create、update、destroy
-- **状态共享**：RefManager 的 registerRef/getRef、SharedState 的 setSharedState/subscribeSharedState
-- **子组件协调**：childComponentProps 统一配置 Filter、Table、Pagination、Sort 等
-- **表单集成**：内置 Form 实例，表单值变化可联动查询
+## 核心功能
 
-## 代码演示
+### 1. 数据源管理
+
+通过 `DataSourceProvider` 提供数据源上下文，支持:
+
+- 数据源配置
+- 数据覆盖（overrideData）
+- 额外参数（extraParams）
+- 设计模式支持（\_\_designMode）
+
+### 2. 操作处理
+
+通过 `HandleActionsProvider` 提供操作方法:
+
+- **list.onSearch**: 查询数据
+- **list.onReset**: 重置查询条件
+- **list.onPageChange**: 分页切换
+- **get**: 获取单条数据
+- **create**: 创建数据
+- **update**: 更新数据
+- **destroy**: 删除数据
+
+### 3. 引用管理
+
+通过 `RefManagerProvider` 提供:
+
+- **Ref 管理**: 注册、获取、注销组件引用
+- **SharedState**: 跨组件共享状态和订阅机制
+
+### 4. 子组件协调
+
+通过 `ChildComponentPropsProvider` 统一管理子组件属性:
+
+- Filter 组件属性
+- Table 组件属性
+- Pagination 组件属性
+- Sort 组件属性
+- ColumnsSetting 组件属性
+- 等等...
+
+## 基础使用
 
 ### 简单列表查询
 
-```tsx
-import React from 'react';
+```
 import { PisellDataSourceContainer } from '@pisell/materials';
 
 export default () => {
   return (
     <PisellDataSourceContainer
-      dataSource="users"
-      autoRun={{ list: true }}
-      pagination={true}
+      dataSource="users" // 数据源表名
+      autoRun={{ list: true }} // 自动执行查询
+      pagination={true} // 启用分页
     >
       <PisellDataSourceContainer.Table />
       <PisellDataSourceContainer.Pagination />
@@ -51,49 +86,34 @@ export default () => {
 };
 ```
 
-### 带筛选的列表
+### 带筛选条件的列表
 
-```tsx
-import React from 'react';
+```
 import { PisellDataSourceContainer } from '@pisell/materials';
 
 export default () => {
-  const childComponentProps = {
-    filterComponent: {
-      value: {
-        quickFilter: [
-          { name: 'keyword', label: '关键词', type: 'input', props: {}, other: {} },
-          {
-            name: 'status',
-            label: '状态',
-            type: 'single',
-            props: {
-              options: [
-                { label: '全部', value: '' },
-                { label: '启用', value: '1' },
-                { label: '禁用', value: '0' },
-              ],
-            },
-            other: {},
-          },
-        ],
-      },
-    },
-    tableComponent: {
-      columns: [
-        { title: 'ID', dataIndex: 'id' },
-        { title: '名称', dataIndex: 'name' },
-        { title: '状态', dataIndex: 'status' },
-      ],
-    },
-  };
-
   return (
     <PisellDataSourceContainer
       dataSource="products"
       autoRun={{ list: true }}
       pagination={{ pageNumber: 1, pageSize: 20 }}
-      childComponentProps={childComponentProps}
+      childComponentProps={{
+        filterComponent: {
+          value: {
+            quickFilter: [
+              { name: 'keyword', label: '关键词', type: 'input' },
+              { name: 'status', label: '状态', type: 'select', options: [...] }
+            ]
+          }
+        },
+        tableComponent: {
+          columns: [
+            { title: 'ID', dataIndex: 'id' },
+            { title: '名称', dataIndex: 'name' },
+            { title: '状态', dataIndex: 'status' }
+          ]
+        }
+      }}
     >
       <PisellDataSourceContainer.Filter />
       <PisellDataSourceContainer.Table />
@@ -103,15 +123,11 @@ export default () => {
 };
 ```
 
-### 自定义子组件（useContainerContext）
-
-通过 `PisellDataSourceContainer.useContainerContext` 获取 `serverActions`、`refManager`、`form`，在自定义子组件内发起查询或读取数据。
+### 自定义子组件
 
-```tsx
-import React from 'react';
+```
 import { PisellDataSourceContainer } from '@pisell/materials';
-
-const useContainerContext = PisellDataSourceContainer.useContainerContext;
+import useContainerContext from '@pisell/materials/pisellDataSourceContainer/hooks/useContainerContext';
 
 const CustomList = () => {
   const { serverActions } = useContainerContext();
@@ -120,7 +136,7 @@ const CustomList = () => {
   return (
     <div>
       {loading && <div>加载中...</div>}
-      {data?.list?.map((item: { id: string; name: string }) => (
+      {data?.list?.map(item => (
         <div key={item.id}>{item.name}</div>
       ))}
     </div>
@@ -129,41 +145,33 @@ const CustomList = () => {
 
 export default () => {
   return (
-    <PisellDataSourceContainer dataSource="items" autoRun={{ list: true }}>
+    <PisellDataSourceContainer
+      dataSource="items"
+      autoRun={{ list: true }}
+    >
       <CustomList />
     </PisellDataSourceContainer>
   );
 };
 ```
 
-### 使用 withContainer 包装子组件
+### 使用 HOC 包装组件
 
-使用 `PisellDataSourceContainer.withContainer` 将自定义组件挂到容器的 childComponentProps 上，并注入 `serverActions`、`refManager`、`form` 等。
-
-```tsx
-import React from 'react';
-import { PisellDataSourceContainer } from '@pisell/materials';
+```
+import { withContainer } from '@pisell/materials/pisellDataSourceContainer/utils/withContainer';
 
-const withContainer = PisellDataSourceContainer.withContainer;
-
-const MyTableComponent = ({
-  serverActions,
-  refManager,
-  form,
-}: {
-  serverActions: any;
-  refManager: any;
-  form: any;
-}) => {
+const MyTableComponent = ({ serverActions, refManager, form, ...props }) => {
   const { data, loading, onSearch } = serverActions.list;
+
   return (
     <div>
       <button onClick={() => onSearch({ keyword: 'test' })}>搜索</button>
-      {loading ? '加载中' : (data?.list?.length ?? 0) + ' 条'}
+      {/* 表格内容 */}
     </div>
   );
 };
 
+// 使用 withContainer 包装组件
 const MyTable = withContainer(MyTableComponent, 'tableComponent');
 
 export default () => {
@@ -175,33 +183,41 @@ export default () => {
 };
 ```
 
-### RefManager 与 SharedState
-
-通过 `refManager.setSharedState` / `subscribeSharedState` 做跨组件状态同步；订阅需在卸载时取消。
+### RefManager 使用示例
 
-```tsx
-import React, { useEffect } from 'react';
+```
 import { PisellDataSourceContainer } from '@pisell/materials';
-
-const useContainerContext = PisellDataSourceContainer.useContainerContext;
+import useContainerContext from '@pisell/materials/pisellDataSourceContainer/hooks/useContainerContext';
+import { useEffect } from 'react';
 
 const ComponentA = () => {
   const { refManager } = useContainerContext();
+
   useEffect(() => {
-    const unsubscribe = refManager.subscribeSharedState('selectedIds', (ids: string[]) => {
+    // 订阅共享状态
+    const unsubscribe = refManager.subscribeSharedState('selectedIds', (ids) => {
       console.log('选中的 IDs:', ids);
     });
+
     return () => unsubscribe();
-  }, [refManager]);
+  }, []);
+
   return <div>组件 A</div>;
 };
 
 const ComponentB = () => {
   const { refManager } = useContainerContext();
+
   const handleSelect = (ids: string[]) => {
+    // 设置共享状态，会自动通知所有订阅者
     refManager.setSharedState('selectedIds', ids);
   };
-  return <button onClick={() => handleSelect(['1', '2', '3'])}>选择</button>;
+
+  return (
+    <button onClick={() => handleSelect(['1', '2', '3'])}>
+      选择
+    </button>
+  );
 };
 
 export default () => {
@@ -214,135 +230,170 @@ export default () => {
 };
 ```
 
-### 自定义操作（导出、批量删除）
+## API
 
-在子组件内通过 `serverActions` 与 `form` 组合实现导出、批量删除等，操作后调用 `list.onSearch()` 刷新列表。
+### PisellDataSourceContainer Props
 
-```tsx
-import React from 'react';
-import { PisellDataSourceContainer } from '@pisell/materials';
+| 参数                | 说明           | 类型                                                  | 默认值 | 必填 |
+| ------------------- | -------------- | ----------------------------------------------------- | ------ | ---- |
+| dataSource          | 数据源配置     | `string \| DataSourceConfig`                          | -      | ✅   |
+| autoRun             | 自动执行配置   | `{ list?: boolean }`                                  | -      | ❌   |
+| pagination          | 分页配置       | `boolean \| { pageNumber: number; pageSize: number }` | `true` | ❌   |
+| extraParams         | 额外请求参数   | `{ list?: Record<string, any> }`                      | -      | ❌   |
+| actions             | 操作方法配置   | `ActionsConfig`                                       | -      | ❌   |
+| overrideData        | 数据覆盖       | `any`                                                 | -      | ❌   |
+| currentValue        | 当前值         | `any`                                                 | -      | ❌   |
+| \_\_designMode      | 设计模式       | `boolean`                                             | -      | ❌   |
+| childComponentProps | 子组件属性配置 | `ChildComponentPropsType`                             | -      | ❌   |
+| children            | 子组件         | `ReactNode`                                           | -      | ✅   |
 
-const useContainerContext = PisellDataSourceContainer.useContainerContext;
+### ChildComponentPropsType
+
+| 参数                    | 说明                    | 类型                                                                                                                                         |
+| ----------------------- | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| filterComponent         | Filter 组件属性         | `{ value: { quickFilter?: FilterItemProps[]; otherFilter?: FilterItemProps[] }; formFiltersPrefix?: string; quickFilterMaxLength?: number }` |
+| quickFilterComponent    | QuickFilter 组件属性    | `{ filterList: FilterItemProps[]; formFiltersPrefix?: string }`                                                                              |
+| filterButtonComponent   | FilterButton 组件属性   | `FilterListProps`                                                                                                                            |
+| tabsComponent           | Tabs 组件属性           | `{ items: TabsProps['items']; type?: 'default' \| 'button' \| 'buttonGroup' \| 'dropdown' }`                                                 |
+| sortComponent           | Sort 组件属性           | `SortListProps`                                                                                                                              |
+| tableComponent          | Table 组件属性          | `AntdTableProps<any>`                                                                                                                        |
+| columnsSettingComponent | ColumnsSetting 组件属性 | `{ value?: Record<string, any>[]; onChange?: (val) => void }`                                                                                |
+| paginationComponent     | Pagination 组件属性     | `PaginationProps`                                                                                                                            |
+
+### useContainerContext 返回值
+
+| 参数           | 说明               | 类型                                 |
+| -------------- | ------------------ | ------------------------------------ |
+| serverActions  | 服务端操作方法集合 | `HandleActionContextType`            |
+| refManager     | 引用管理器         | `RefManagerContextType`              |
+| form           | 表单实例           | `FormInstance`                       |
+| onValuesChange | 表单值变化回调     | `(changedValues, allValues) => void` |
+
+### serverActions.list
+
+| 参数         | 说明                     | 类型                                       |
+| ------------ | ------------------------ | ------------------------------------------ |
+| data         | 列表数据                 | `{ list: any[]; count: number }`           |
+| loading      | 加载状态                 | `boolean`                                  |
+| error        | 错误信息                 | `Error`                                    |
+| run          | 执行查询（原始方法）     | `(params) => void`                         |
+| onSearch     | 查询方法（自动处理分页） | `(params?) => void`                        |
+| onReset      | 重置方法                 | `() => void`                               |
+| onPageChange | 分页切换方法             | `(pageNumber, pageSize) => void`           |
+| pagination   | 当前分页状态             | `{ pageNumber: number; pageSize: number }` |
+
+### refManager 方法
 
+| 方法                 | 说明         | 类型                                                           |
+| -------------------- | ------------ | -------------------------------------------------------------- |
+| registerRef          | 注册组件引用 | `<T>(id: string, ref: T) => void`                              |
+| getRef               | 获取组件引用 | `<T>(id: string) => T \| undefined`                            |
+| unregisterRef        | 注销组件引用 | `(id: string) => void`                                         |
+| getSharedState       | 获取共享状态 | `<T>(key: string) => T \| undefined`                           |
+| setSharedState       | 设置共享状态 | `<T>(key: string, value: T) => void`                           |
+| subscribeSharedState | 订阅共享状态 | `<T>(key: string, callback: (value: T) => void) => () => void` |
+
+## 内置子组件
+
+PisellDataSourceContainer 提供了一系列开箱即用的子组件：
+
+### PisellDataSourceContainer.Filter
+
+筛选组件，支持快速筛选和高级筛选。
+
+### PisellDataSourceContainer.Table
+
+表格组件，自动连接数据源。
+
+### PisellDataSourceContainer.Pagination
+
+分页组件，自动处理分页逻辑。
+
+### PisellDataSourceContainer.Sort
+
+排序组件。
+
+### PisellDataSourceContainer.ColumnsSetting
+
+列设置组件。
+
+## 高级用法
+
+### 自定义操作
+
+```
 const CustomActions = () => {
   const { serverActions, form } = useContainerContext();
-  const { list } = serverActions;
 
-  const handleExport = () => {
+  const handleExport = async () => {
     const values = form.getFieldsValue();
-    console.log('导出条件', values);
+    // 导出逻辑
   };
 
   const handleBatchDelete = async () => {
-    await serverActions.destroy.run({ ids: ['1', '2'] });
-    list.onSearch();
+    const { list } = serverActions;
+    // 批量删除逻辑
+    await serverActions.destroy.run({ ids: selectedIds });
+    list.onSearch(); // 重新查询
   };
 
   return (
-    <div style={{ marginBottom: 16 }}>
+    <div>
       <button onClick={handleExport}>导出</button>
       <button onClick={handleBatchDelete}>批量删除</button>
     </div>
   );
 };
-
-export default () => {
-  return (
-    <PisellDataSourceContainer dataSource="users" autoRun={{ list: true }}>
-      <CustomActions />
-      <PisellDataSourceContainer.Table />
-      <PisellDataSourceContainer.Pagination />
-    </PisellDataSourceContainer>
-  );
-};
 ```
 
-## API
-
-### PisellDataSourceContainer Props
+### 跨组件通信
 
-| 参数                | 说明           | 类型                                                  | 默认值 | 必填 |
-| ------------------- | -------------- | ----------------------------------------------------- | ------ | ---- |
-| dataSource          | 数据源配置     | `string \| DataSourceConfig`                          | -      | 是   |
-| children            | 子组件         | `ReactNode`                                           | -      | 是   |
-| autoRun             | 自动执行配置   | `{ list?: boolean }`                                  | -      | 否   |
-| pagination          | 分页配置       | `boolean \| { pageNumber: number; pageSize: number }` | `true` | 否   |
-| extraParams         | 额外请求参数   | `{ list?: Record<string, any> }`                      | -      | 否   |
-| actions             | 操作方法配置   | `ActionsConfig`                                       | -      | 否   |
-| overrideData        | 数据覆盖       | `any`                                                 | -      | 否   |
-| currentValue        | 当前值         | `any`                                                 | -      | 否   |
-| __designMode        | 设计模式       | `boolean`                                             | -      | 否   |
-| childComponentProps | 子组件属性配置 | `ChildComponentPropsType`                             | -      | 否   |
-
-### ChildComponentPropsType
-
-| 参数                    | 说明                 | 类型 |
-| ----------------------- | -------------------- | ---- |
-| filterComponent         | Filter 组件属性      | `{ value: { quickFilter?, otherFilter? }; formFiltersPrefix?; quickFilterMaxLength? }` |
-| quickFilterComponent    | QuickFilter 组件属性 | `{ filterList; formFiltersPrefix? }` |
-| filterButtonComponent   | FilterButton 组件属性| `FilterListProps` |
-| tabsComponent           | Tabs 组件属性        | `{ items; type? }` |
-| sortComponent           | Sort 组件属性        | `SortListProps` |
-| tableComponent          | Table 组件属性       | `AntdTableProps<any>` |
-| columnsSettingComponent | ColumnsSetting 组件属性 | `{ value?; onChange? }` |
-| paginationComponent     | Pagination 组件属性  | `PaginationProps` |
+```
+// 组件 A - 设置状态
+const ComponentA = () => {
+  const { refManager } = useContainerContext();
 
-### useContainerContext 返回值
+  const handleClick = () => {
+    refManager.setSharedState('currentTab', 'all');
+  };
 
-| 参数           | 说明               | 类型 |
-| -------------- | ------------------ | ---- |
-| serverActions  | 服务端操作方法集合 | `HandleActionContextType` |
-| refManager     | 引用管理器         | `RefManagerContextType` |
-| form           | 表单实例           | `FormInstance` |
-| onValuesChange | 表单值变化回调     | `(changedValues, allValues) => void` |
+  return <button onClick={handleClick}>切换</button>;
+};
 
-### serverActions.list
+// 组件 B - 订阅状态
+const ComponentB = () => {
+  const { refManager } = useContainerContext();
+  const [tab, setTab] = useState('all');
 
-| 参数         | 说明                     | 类型 |
-| ------------ | ------------------------ | ---- |
-| data         | 列表数据                 | `{ list: any[]; count: number }` |
-| loading      | 加载状态                 | `boolean` |
-| error        | 错误信息                 | `Error` |
-| run          | 执行查询（原始方法）     | `(params) => void` |
-| onSearch     | 查询（自动处理分页）     | `(params?) => void` |
-| onReset      | 重置                     | `() => void` |
-| onPageChange | 分页切换                 | `(pageNumber, pageSize) => void` |
-| pagination   | 当前分页状态             | `{ pageNumber; pageSize }` |
+  useEffect(() => {
+    return refManager.subscribeSharedState('currentTab', setTab);
+  }, []);
 
-### refManager 方法
+  return <div>当前标签：{tab}</div>;
+};
+```
 
-| 方法                 | 说明         | 类型 |
-| -------------------- | ------------ | ---- |
-| registerRef          | 注册组件引用 | `<T>(id: string, ref: T) => void` |
-| getRef               | 获取组件引用 | `<T>(id: string) => T \| undefined` |
-| unregisterRef        | 注销组件引用 | `(id: string) => void` |
-| getSharedState       | 获取共享状态 | `<T>(key: string) => T \| undefined` |
-| setSharedState       | 设置共享状态 | `<T>(key: string, value: T) => void` |
-| subscribeSharedState | 订阅共享状态 | `<T>(key: string, callback: (value: T) => void) => () => void` |
+## 扩展开发
 
-## 内置子组件
+如果你需要开发新的子组件或扩展现有功能，请参考：
 
-| 子组件 | 说明 |
-|--------|------|
-| `PisellDataSourceContainer.Filter` | 筛选，支持快速筛选与高级筛选 |
-| `PisellDataSourceContainer.QuickFilter` | 快速筛选 |
-| `PisellDataSourceContainer.FilterButton` | 筛选按钮 |
-| `PisellDataSourceContainer.Table` | 表格，自动连接数据源 |
-| `PisellDataSourceContainer.Pagination` | 分页 |
-| `PisellDataSourceContainer.Sort` | 排序 |
-| `PisellDataSourceContainer.ColumnsSetting` | 列设置 |
+- [设计文档](./PisellDataSourceContainer.$tab-design.md)
+- [开发文档](./PisellDataSourceContainer.$tab-dev.md)
 
 ## 注意事项
 
-1. **数据源**：`dataSource` 可为字符串（表名）或完整数据源配置对象。
-2. **分页**：启用 `pagination` 时，`onSearch` 会重置到第一页。
-3. **表单**：容器内置 Form，子组件通过 `childComponentProps` 与 Form 联动，表单变化可触发查询。
-4. **Ref**：使用 `withContainer` 包装的组件会自动注册/注销 ref。
-5. **SharedState**：`subscribeSharedState` 返回取消订阅函数，请在组件卸载时调用。
-6. **性能**：子组件内合理使用 `useMemo` / `useCallback` 减少重复渲染。
-
-## 相关文档
-
-- [设计文档](./PisellDataSourceContainer.$tab-design.md)
-- [开发文档](./PisellDataSourceContainer.$tab-dev.md)
-- [测试文档](./PisellDataSourceContainer.$tab-test.md)
+1. **数据源配置**: 确保 dataSource 配置正确，可以是字符串（表名）或完整的数据源配置对象
+2. **分页配置**: 如果启用分页（pagination=true），onSearch 会自动重置到第一页
+3. **表单集成**: 容器内置了 Form 实例，表单值变化会自动触发 onSearch
+4. **Ref 管理**: 使用 withContainer HOC 包装组件时，会自动注册和注销 ref
+5. **SharedState**: 使用 subscribeSharedState 时，记得在组件卸载时取消订阅
+6. **性能优化**: 合理使用 useMemo 和 useCallback 避免不必要的重新渲染
+
+## 最佳实践
+
+1. **统一数据管理**: 将所有数据操作集中在 PisellDataSourceContainer 中管理
+2. **组件解耦**: 使用 useContainerContext 访问上下文，保持组件独立性
+3. **状态共享**: 使用 SharedState 代替 props drilling
+4. **类型安全**: 为 serverActions、refManager 等添加明确的类型定义
+5. **错误处理**: 在操作方法中添加错误处理逻辑
+6. **加载状态**: 合理使用 loading 状态提升用户体验

package/lib/components/pisellDataSourceContainer/type.d.ts

@@ -1,5 +1,5 @@
-import { SortListProps } from "../sort/types.js";
 import { FilterItemProps } from "../filter/types.js";
+import { SortListProps } from "../sort/types.js";
 import { DataSourceContextProps, DataSourceContextType } from "../dataSourceComponents/provider/dataSource/DataSourceContext.js";
 import { FilterListProps } from "../filter/components/FilterButton/types.js";
 import { FormInstance, PaginationProps, TableProps, TabsProps } from "antd";