@pointcloud/pcloud-components

一套基于 Ant Design v5.x 与 React v18 打造的业务组件库，沉淀了中后台系统中高频复用的 38 个组件。开箱即用、类型完备，帮助你在企业级项目中减少重复开发，快速搭建出风格统一的产品原型。

✨ 特性

• 贴合业务场景：表格、表单、CRUD 等组件针对中后台的实际需求做了深度增强，例如异步加载、分页联动、弹窗检索等
• 完整的 TypeScript 类型：所有组件与 Props 均提供类型定义，可获得完善的编辑器智能提示
• 开箱即用的主题体系：基于 antd 5 的 Design Token，可通过 ConfigProvider 统一定制，无需额外配置
• 支持按需引入与 UMD：既支持 ES Module 按需加载，也可通过 UMD 直接在浏览器中引入
• 文档与示例齐全：每个组件均配有可交互示例、详细的 API 文档与国标/业务规范说明

🎁 组件列表

分组与在线文档的导航保持一致。

业务组件

业务开发中最常使用的增强型组件。

| 组件名称 | 描述 | | --------------- | --------------------------------------- | | DForm | 基于 antd Form 的配置化表单组件 | | DInput | 增强版输入框组件 | | DSelect | 支持异步数据源的下拉选择组件 | | DCascader | 支持异步加载的级联选择组件 | | DTreeSelect | 支持异步加载的树选择组件 | | DUpload | 集成上传进度与校验的文件上传组件 | | DRangePicker | 日期区间选择组件 | | DynamicFormItem | 支持动态增删的表单项组件 | | DTable | 增强版表格组件，支持分页与请求联动 | | DModal | 增强版模态框组件 | | LabelValue | 标签值一体的展示组件 | | AdvancedFilter | 可配置的高级筛选组件 | | AuthComponent | 权限控制组件，按权限渲染子元素 | | ErrorBoundary | 错误边界组件，避免局部异常导致白屏 | | LicensePlate | 车牌号输入组件，牌面严格依据 GA 36-2018 | | IPAddress | IP 地址输入组件 | | IconFont | 自定义图标组件 | | AspectRatio | 固定宽高比的容器组件 | | PictureCard | 图片卡片组件 | | SignaturePad | 手写签名板组件 | | RCropper | 图片裁剪组件 | | RndDrag | 可拖拽与调整大小的容器组件 | | ColorPicker | 颜色选择器组件 | | ContextMenu | 右键菜单组件 | | Loading | 全局加载组件，附带 useLoading 方法 | | NoData | 无数据占位组件 |

组合组件

由多个基础组件封装而成，用于承载完整的交互流程。

| 组件名称 | 描述 | | ------------------ | ---------------------------------------- | | CRUD | 集查询、表格、表单于一体的 CRUD 组件 | | ModalForm | 模态框与表单的组合组件 | | DrawerForm | 抽屉与表单的组合组件，适合侧滑编辑 | | ModalTable | 弹窗、表单与表格的组合组件，支持顶部检索 | | LoginForm | 通用登录表单组件 | | InfiniteScrollList | 无限滚动列表组件，支持下拉加载更多 |

数据展示

以可视化或动画方式呈现数据的组件。

| 组件名称 | 描述 | | ------------------ | ------------------ | | WordCloud | 词云组件 | | ScrollNumber | 数字滚动动画组件 | | TypewriterText | 打字机文字效果组件 | | AnimatedScrollList | 动画滚动列表组件 | | OrgTree | 组织架构树组件 |

其他

| 组件名称 | 描述 | | -------------- | ---------------------------------------- | | ConfigProvider | 全局化配置组件，用于统一注入主题与上下文 |

🚀 安装

# 使用 npm
npm install @pointcloud/pcloud-components

# 使用 yarn
yarn add @pointcloud/pcloud-components

# 使用 pnpm
pnpm add @pointcloud/pcloud-components

环境要求

本组件库依赖以下运行时环境，请确保你的项目满足：

| 依赖 | 版本要求 | | ----------------- | ---------- | | React | 18.x | | React DOM | 18.x | | Ant Design | >= 5.x | | @ant-design/icons | >= 5.x | | Node.js | >= 16.20.0 |

本组件库基于 antd 5 开发，不兼容 antd 4。若你的项目仍在使用 antd 4，请先升级至 5.x。

🔨 快速开始

1. 基础使用

import React from 'react';
import { DCascader } from '@pointcloud/pcloud-components';

const App = () => {
  const handleChange = (value, selectedOptions) => {
    console.log(value, selectedOptions);
  };

  return <DCascader showSearch placeholder="请选择" onChange={handleChange} />;
};

export default App;

2. 使用表单组件

DForm 支持通过 items 配置项以数据驱动的方式生成表单，无需手写大量 JSX。

import React from 'react';
import { DForm } from '@pointcloud/pcloud-components';

const App = () => {
  const onFinish = (values) => {
    console.log('表单值:', values);
  };

  const items = [
    {
      label: '用户名',
      name: 'username',
      rules: [{ required: true, message: '请输入用户名' }],
      renderType: 'input',
    },
    {
      label: '状态',
      name: 'status',
      rules: [{ required: true, message: '请选择状态' }],
      renderType: 'select',
      options: [
        { label: '启用', value: 1 },
        { label: '禁用', value: 0 },
      ],
    },
    {
      label: '提交',
      renderType: 'button',
      type: 'primary',
      htmlType: 'submit',
    },
  ];

  return <DForm onFinish={onFinish} items={items} />;
};

export default App;

3. 全局化配置

通过 ConfigProvider 注入统一配置，例如请求实例、主题定制等。

import React from 'react';
import { ConfigProvider } from '@pointcloud/pcloud-components';

const App = () => (
  <ConfigProvider theme={{ token: { colorPrimary: '#1677ff' } }}>
    <YourApp />
  </ConfigProvider>
);

export default App;

4. 通过 UMD 引入

若在浏览器中直接使用，请先引入 react 与 react-dom，再引入组件库的资源文件。

<link rel="stylesheet" href="https://unpkg.com/@pointcloud/pcloud-components/dist/umd/pcloud-components.min.css" />
<script src="https://unpkg.com/react@18/umd/react.production.min.js"></script>
<script src="https://unpkg.com/react-dom@18/umd/react-dom.production.min.js"></script>
<script src="https://unpkg.com/@pointcloud/pcloud-components/dist/umd/pcloud-components.min.js"></script>

📖 文档

完整的组件列表、可交互示例与 API 说明，请访问 在线文档。

🤝 参与贡献

欢迎通过 GitHub Issues 反馈问题或提出改进建议。

本项目使用 Conventional Commits 规范提交信息，提交前会自动执行 ESLint 与 Stylelint 检查。

📄 License

MIT © Frank Dong