@brain-toolkit/antd-blocks

基于 Ant Design 的高级业务组件库，提供开箱即用的 CRUD 资源管理解决方案

English | 简体中文

✨ 特性

• 🚀 开箱即用：提供完整的 CRUD 资源管理解决方案，大幅减少样板代码
• 📦 高度集成：基于 Ant Design 组件体系，与现有项目无缝集成
• 🎯 类型安全：完整的 TypeScript 类型定义，提供优秀的开发体验
• 🔄 状态管理：内置响应式状态管理，自动处理加载、成功、错误状态
• 🎨 高度可定制：灵活的配置选项和插槽，满足各种业务场景
• 📱 响应式设计：支持移动端适配，提供良好的移动体验

📦 安装

# npm
npm install @brain-toolkit/antd-blocks

# yarn
yarn add @brain-toolkit/antd-blocks

# pnpm
pnpm add @brain-toolkit/antd-blocks

依赖要求

{
  "react": ">=18.0.0",
  "antd": ">=5.0.0",
  "@qlover/corekit-bridge": ">=1.6.0",
  "@qlover/slice-store-react": ">=1.4.0"
}

🚀 快速开始

在线示例

想要快速体验？可以运行我们准备的交互式示例：

# 进入 antd-blocks 目录
cd packages/antd-blocks

# 安装依赖
pnpm install

# 启动示例
pnpm dev:example

查看 example/README.md 了解更多示例详情。

基础示例

import React, { useEffect, useMemo } from 'react';
import { Form } from 'antd';
import { ResourceTable, ResourceEvent } from '@brain-toolkit/antd-blocks/resourceTable';
import { UserService } from './services/UserService';

function UserList() {
  const [form] = Form.useForm();

  // Use useMemo to ensure instances are created only once
  const userService = useMemo(() => new UserService(), []);
  const tableEvent = useMemo(
    () => new ResourceEvent('users', userService, undefined, form),
    [userService, form]
  );

  useEffect(() => {
    tableEvent.created();
    return () => tableEvent.destroyed();
  }, [tableEvent]);

  const columns = [
    { title: '姓名', dataIndex: 'name', key: 'name' },
    { title: '邮箱', dataIndex: 'email', key: 'email' },
    { title: '角色', dataIndex: 'role', key: 'role' }
  ];

  return (
    <ResourceTable
      columns={columns}
      tableEvent={tableEvent}
    />
  );
}

export default UserList;

⚡ 性能优化建议

使用 useMemo 包裹实例创建

在 React 组件中创建服务实例和事件处理器时，必须使用 useMemo 包裹，以避免每次渲染时都创建新实例。

❌ 错误示例（会导致性能问题）：

function UserList() {
  // 错误：每次渲染都会创建新实例
  const userService = new UserService();
  const tableEvent = new ResourceEvent('users', userService);
  // ...
}

✅ 正确示例：

function UserList() {
  // 正确：使用 useMemo 确保实例只创建一次
  const userService = useMemo(() => new UserService(), []);
  const tableEvent = useMemo(
    () => new ResourceEvent('users', userService),
    [userService]
  );
  // ...
}

原因说明：

• 不使用 useMemo 会导致每次渲染创建新实例
• 新实例会触发子组件不必要的重新渲染
• 可能导致 useEffect 依赖项变化，引发无限循环
• 造成内存泄漏和性能下降

📚 核心组件

ResourceTable

资源表格组件，提供完整的 CRUD 功能和分页支持。

主要特性：

• ✅ 自动数据加载和分页
• ✅ 内置增删改查操作按钮
• ✅ 加载状态自动管理
• ✅ 响应式设计，支持移动端

Props：

| 属性 | 类型 | 必填 | 默认值 | 说明 | | ------------- | ----------------------------------------------------- | ---- | ------ | ------------------------------- | | columns | ResourceTableOption<T>[] | ✅ | - | 表格列配置 | | tableEvent | ResourceTableEventInterface | ✅ | - | 事件处理器实例 | | actionProps | false \| TableColumnProps & ResourceTableActionI18n | ❌ | - | 操作列配置，设为 false 可隐藏 |

ResourceEvent

资源事件处理类，管理 CRUD 操作的完整生命周期。

主要特性：

• ✅ 统一的 CRUD 操作接口
• ✅ 自动状态管理（loading、success、error）
• ✅ 表单数据自动填充和重置
• ✅ 可扩展的操作钩子

构造函数参数：

| 参数 | 类型 | 必填 | 说明 | | --------------- | -------------------------- | ---- | ---------------------- | | namespace | string | ✅ | 命名空间，用于状态隔离 | | resource | ResourceServiceInterface | ✅ | 资源服务实例 | | store | ResourceEventStroe | ❌ | 自定义 store 实例 | | schemaFormRef | FormInstance | ❌ | Ant Design Form 实例 |

ResourceTableProvider

资源表格上下文提供者，用于共享状态和事件处理器。

import { ResourceTableProvider } from '@brain-toolkit/antd-blocks/resourceTable';

<ResourceTableProvider tableEvent={tableEvent}>
  <ResourceTableHeader />
  <ResourceTable columns={columns} tableEvent={tableEvent} />
  <ResourceTablePopup />
</ResourceTableProvider>

💡 使用场景

场景 1：标准 CRUD 管理

import { useMemo } from 'react';
import { ResourceTable, ResourceEvent } from '@brain-toolkit/antd-blocks/resourceTable';

function ProductList() {
  const productService = useMemo(() => new ProductService(), []);
  const tableEvent = useMemo(
    () => new ResourceEvent('products', productService),
    [productService]
  );

  const columns = [
    { title: '产品名称', dataIndex: 'name' },
    { title: '价格', dataIndex: 'price' },
    { title: '库存', dataIndex: 'stock' }
  ];

  return <ResourceTable columns={columns} tableEvent={tableEvent} />;
}

场景 2：自定义操作列

<ResourceTable
  columns={columns}
  tableEvent={tableEvent}
  actionProps={{
    width: 200,
    fixed: 'right',
    editText: '修改',
    deleteText: '删除',
    detailText: '查看详情'
  }}
/>

场景 3：隐藏操作列

<ResourceTable
  columns={columns}
  tableEvent={tableEvent}
  actionProps={false}
/>

场景 4：自定义删除逻辑

class CustomResourceEvent extends ResourceEvent {
  protected async actionDelete(values: unknown): Promise<unknown> {
    const confirmed = await Modal.confirm({
      title: '确认删除',
      content: '删除后数据将无法恢复，是否继续？'
    });

    if (confirmed) {
      await this.resource.remove(values);
      await this.onRefresh({ resource: this.resource });
      message.success('删除成功');
    }

    return confirmed;
  }
}

场景 5：完整的表单集成

import { useEffect, useMemo } from 'react';
import { Form, Input, Select } from 'antd';
import { ResourceTableProvider, ResourceTableHeader, ResourceTablePopup, ResourceTableSchemaForm } from '@brain-toolkit/antd-blocks/resourceTable';

function UserManagement() {
  const [form] = Form.useForm();

  const userService = useMemo(() => new UserService(), []);
  const tableEvent = useMemo(
    () => new ResourceEvent('users', userService, undefined, form),
    [userService, form]
  );

  useEffect(() => {
    tableEvent.created();
    return () => tableEvent.destroyed();
  }, [tableEvent]);

  return (
    <ResourceTableProvider tableEvent={tableEvent}>
      <ResourceTableHeader />
      <ResourceTable columns={columns} tableEvent={tableEvent} />
      <ResourceTablePopup title="用户信息">
        <ResourceTableSchemaForm>
          <Form.Item name="name" label="姓名" rules={[{ required: true }]}>
            <Input />
          </Form.Item>
          <Form.Item name="email" label="邮箱" rules={[{ required: true, type: 'email' }]}>
            <Input />
          </Form.Item>
          <Form.Item name="role" label="角色">
            <Select>
              <Select.Option value="admin">管理员</Select.Option>
              <Select.Option value="user">普通用户</Select.Option>
            </Select>
          </Form.Item>
        </ResourceTableSchemaForm>
      </ResourceTablePopup>
    </ResourceTableProvider>
  );
}

🔌 实现资源服务

资源服务需要实现 ResourceServiceInterface 接口：

import {
  ResourceServiceInterface,
  ResourceStore,
  ResourceStateInterface
} from '@qlover/corekit-bridge';

class UserService
  implements
    ResourceServiceInterface<User, ResourceStore<ResourceStateInterface>>
{
  private store = new ResourceStore<ResourceStateInterface>();

  getStore() {
    return this.store;
  }

  async create(data: unknown): Promise<User> {
    // 实现创建逻辑
    const response = await api.post('/users', data);
    return response.data;
  }

  async update(data: Partial<User>): Promise<User> {
    // 实现更新逻辑
    const response = await api.put(`/users/${data.id}`, data);
    return response.data;
  }

  async remove(data: unknown): Promise<void> {
    // 实现删除逻辑
    await api.delete(`/users/${(data as User).id}`);
  }

  async search(query: ResourceQuery): Promise<ResourceListResult<User>> {
    // 实现查询逻辑
    const response = await api.get('/users', { params: query });
    return {
      list: response.data.items,
      total: response.data.total
    };
  }

  created() {
    // 组件挂载时调用
    this.search({ page: 1, pageSize: 10 });
  }

  updated() {
    // 组件更新时调用
  }

  destroyed() {
    // 组件卸载时调用
  }
}

📖 API 文档

ResourceTable Props

| 属性 | 类型 | 必填 | 默认值 | 说明 | | ------------- | ---------------------------------------------------------- | ---- | ------ | ------------------------------------------ | | columns | ResourceTableOption<T>[] | ✅ | - | 表格列配置，扩展自 Ant Design Table Column | | tableEvent | ResourceTableEventInterface | ✅ | - | 事件处理器实例 | | actionProps | false \| (TableColumnProps<T> & ResourceTableActionI18n) | ❌ | - | 操作列配置，设为 false 隐藏操作列 | | ...其他 | TableProps<T> | ❌ | - | 继承所有 Ant Design Table 组件 props |

ResourceEvent Methods

| 方法 | 参数 | 返回值 | 说明 | | ------------------------ | ------------------------------------------------ | ------------------ | -------------- | | onCreated(params) | ResourceTableEventCommonParams | void | 触发创建操作 | | onEdited(params) | ResourceTableEventCommonParams | void | 触发编辑操作 | | onDeleted(params) | ResourceTableEventCommonParams | void | 触发删除操作 | | onDetail(params) | ResourceTableEventCommonParams | void | 查看详情 | | onRefresh(params) | ResourceTableEventCommonParams | Promise<unknown> | 刷新列表 | | onSubmit(values) | unknown | Promise<unknown> | 提交表单 | | onClosePopup() | - | void | 关闭弹窗 | | onChangeParams(params) | ResourceTableEventCommonParams & ResourceQuery | void | 更改查询参数 | | created() | - | void | 生命周期：创建 | | updated() | - | void | 生命周期：更新 | | destroyed() | - | void | 生命周期：销毁 |

🎨 主题定制

组件基于 Ant Design，支持 Ant Design 的所有主题定制方式：

import { ConfigProvider } from 'antd';

<ConfigProvider
  theme={{
    token: {
      colorPrimary: '#00b96b',
    },
  }}
>
  <ResourceTable columns={columns} tableEvent={tableEvent} />
</ConfigProvider>

🔗 相关链接

• GitHub Repository
• Ant Design 文档
• 问题反馈

🤝 贡献

欢迎贡献代码！请查看我们的 贡献指南。

📄 许可证

ISC © qlover

🙏 致谢

本项目基于以下优秀的开源项目：

• Ant Design - 企业级 UI 设计语言和 React 组件库
• React - 用于构建用户界面的 JavaScript 库
• @qlover/corekit-bridge - 核心工具库