fexd-pro-components

name	fexd-pro-components
description	React 管理系统组件库 @fexd/pro-components 的完整使用指南。涵盖 ProTable、ProForm、ProField、ConfigProvider 等核心组件以及 showModal、showImages、useCoverable、Action 等实用工具的用法、API、代码示例和最佳实践。 当用户使用 @fexd/pro-components 开发管理页面、查找组件用法、定制配置、查询 API 时使用。 触发词：fexd、pro-components、@fexd/pro-components、ProTable、ProForm、ProField。
metadata	{"author":"FEXD Team","version":"2026.05.08","source":"packages/components/src/"}

@fexd/pro-components 使用指南

文档基于 @fexd/pro-components v0.2.99，更新于 2026-05-08。

React 管理系统组件库，基于 Ant Design 4.x + React 16/17，覆盖表格、表单、字段、全局配置、命令式弹窗/图片预览、业务组件化等场景。

Skill 导览

按任务场景选择对应文档，避免全量阅读：

场景	应读文件
使用某个组件/工具	references/{Name}.md
选组件 / 了解有哪些组件	catalog.md
查完整 Props / API	references/{Name}.md 或 source-navigation.md → 源码 type
国际化 / 全局配置	references/ConfigProvider.md
开发表格页面	references/ProTable.md（→ Ref · Query · CRUD · Actions · Plugins）
开发表单页面	references/ProForm.md（→ Ref · Fields · Layout · Advanced） + ProField
命令式弹窗 / 图片预览	references/showModal.md / references/showImages.md / references/showDrawer.md
确认操作	references/confirmPromise.md（轻量确认）/ references/Action.md（按钮+确认）
业务组件化	references/useCoverable.md（→ 设计指南 · BC编写 · 消费指南 · request.coverable · 迁移）
理解架构	architecture.md
体验规范 / 最佳实践	guide.md
使用 Hooks / 工具函数	utilities.md；useProState 详见 references/useProState.md
源码探索	source-navigation.md
终端快速查文档	npx pro-components list/docs/search

CLI 可用性

@fexd/pro-components 包内置了 pro-components CLI。AI Agent 或开发者可以用它做快速发现与检索：

• npx pro-components list：查看组件、Hooks、工具函数清单
• npx pro-components docs <name>：输出某个组件/工具的内置文档
• npx pro-components search <query>：在内置文档中全文搜索

安装本 skill 请使用 fexd-tools skills install @fexd/pro-components。fexd-tools 会扫描当前项目 node_modules 和 workspace 包中的 skills/*/SKILL.md，统一安装依赖包发布的 skills。

CLI 是检索辅助；当 Agent 已加载本 skill 时，应优先按本文件的任务路由读取 references/**、catalog.md、guide.md 等结构化文档。

BC 组件（Business Components）

BC 组件是一种可覆盖配置的复用业务组件设计模式，核心理念：将完整的业务页面（含 API 调用、权限控制、表格/表单配置）封装为一个组件，通过 coverable prop 暴露所有可定制点，让消费方按需覆盖而无需修改源码。

核心机制：

• 组件内部使用 useCoverable Hook 定义默认配置（API 地址、权限、列定义、枚举等）
• 消费方通过 <Component coverable={{ ... }}> 传入覆盖配置
• useCoverable 将默认值与覆盖值深度合并（对象递归合并、数组按索引合并）
• 组件通过 getConfig() 读取最终合并后的配置

典型场景：

• 同一套业务逻辑（如用户列表、权限管理）在多个项目中复用，仅 API 地址、权限、部分 UI 有差异
• BC 组件发布为 npm 包（如 @my-bc/user-manager），各业务项目引入后通过 coverable 定制

快速示例：

// BC 组件（封装方）
const UserList = useCoverable.component(({ coverable }) => {
  const apis = useCoverable({ getList: request.coverable({ url: '/api/users' }) }, coverable?.apis)
  const permission = useCoverable({ add: true, delete: true }, coverable?.permission)
  return <ProTable onQuery={() => apis.getConfig().getList()} ... />
})

// 消费方 — 只改 API 地址，禁用删除
<UserList coverable={{ apis: { getList: { url: '/v2/users' } }, permission: { delete: false } }} />

详细指南：useCoverable.md → 设计 · BC编写 · 消费

推荐实践

• 所有 import 统一从 @fexd/pro-components 引入，无需分包导入
• ProTable 的 onQuery 返回值必须符合 { success, data, total? } 格式
• 表单提交两种方式：ProForm.useForm() → form.validateFields()（常用），或 ProForm.useRef() → ref.current.getValues()（带归一化+过滤空值）
• 命令式弹窗 API（showModal / showImages）优先于声明式；ProTable 内置 CRUD 弹窗除外（已集成在 actions 中）
• Action 组件的异步 onClick 自动管理 loading 状态，无需手动 useState
• 危险操作（删除等）必须使用 confirm 属性进行二次确认
• 国际化通过 <ConfigProvider localeKey="en-US"> 全局配置
• ProTable ref 按插件分组（ref.current.queryField.refresh()），非扁平结构
• ProTable 控制器（ProTable.useController()）提供扁平化常用操作
• ProForm preserve 默认 false（非旧文档的 true）
• ProForm hook 可使用 React Hooks，返回 false 隐藏字段
• useCoverableProps 自动保护 ref/tableRef/formRef，可安全放在配置中
• 非 ref 的特殊对象（SDK 实例、事件总线等）用 useCoverable.raw(obj) 标记保护
• React ref（{ current: ... } 单键对象）在 coverable 系统中被自动识别，不会被 clone / merge 破坏

需求澄清

当用户需求包含以下模糊词时，先给出选型分析和推荐方案，再编码：

• "表格" → 静态数据展示？用 ProTable + dataSource。带查询？加 onQuery + queryFields（详见 ProTable-query）。带 CRUD？加 actions + columnActions + onAdd/onEdit/onDelete（详见 ProTable-crud）。需要外部控制？用 ProTable.useRef() 或 ProTable.useController()（详见 ProTable-ref）。
• "表单" → 简单表单？用 ProForm + fields 配置（详见 ProForm-fields）。复杂布局？用 render 属性（详见 ProForm-layout）。字段关联？用 hook + dependencies（详见 ProForm-advanced）。独立字段？用 ProField。
• "弹窗" → 确认对话？用 showModal + promise。表单弹窗？showModal 嵌套 Form。图片预览？用 showImages。
• "按钮" → 普通按钮用 antd Button。需要异步 loading / 确认操作？用 Action 组件。
• "业务组件" → 需要可配置/可覆盖的封装？用 useCoverable Hook。

CLI 命令

安装 @fexd/pro-components 后可通过 CLI 快速查阅文档；安装 AI Skills 请使用 fexd-tools 的集中式入口：

# 列出所有组件
npx pro-components list

# 查看某个组件/工具的文档
npx pro-components docs ProTable
npx pro-components docs ProForm
npx pro-components docs showModal
npx pro-components docs request

# 全文搜索文档内容
npx pro-components search "queryField"
npx pro-components search "hook dependencies"

# 安装 AI Skills
npx fexd-tools skills install @fexd/pro-components
npx fexd-tools skills install @fexd/pro-components --agents cursor,claude-code,opencode
npx fexd-tools skills install @fexd/pro-components --agents codex --scope global

Import 规范

import {
  ProTable,
  ProForm,
  ProField,
  ConfigProvider,
  showModal,
  showImages,
  Action,
  useCoverable,
  useDebounce,
  useAutoLoading,
  createBC,
} from '@fexd/pro-components'

样式引入：

@import '~@fexd/pro-components/es/style.less';

多步骤任务

搭建表格管理页面：

1. 确认数据结构和字段 → 定义 columns 配置
2. 确认查询需求 → 配置 queryFields 或在 columns 中设置 queryField: true
3. 确认操作需求 → 配置 actions、columnActions、batchActions
4. 实现数据接口 → onQuery 返回 { success, data, total }
5. 实现 CRUD → onAdd、onEdit、onDelete 回调

搭建表单页面：

1. 确认字段列表和类型 → 定义 fields 配置
2. 确认布局 → gridColumns 或 render 自定义布局
3. 获取表单实例 → const [form] = ProForm.useForm()
4. 提交逻辑 → await form.validateFields() → 调接口
5. 模式切换 → mode="edit" / mode="view"

分类概览 → catalog.md

分类	导出	典型组件
数据展示	ProTable	表格、查询、CRUD、插件系统
表单	ProForm, ProField	配置化表单、字段组件、Grid 布局
全局配置	ConfigProvider	国际化、尺寸、文案定制
工具组件	Action, showModal, showImages	操作按钮、命令式弹窗、图片预览
Hooks	useCoverable, useDebounce, useAutoLoading	业务组件化、防抖、加载状态
基础	createBC	BC 组件创建工厂

回复前自检

生成 @fexd/pro-components 相关代码后，检查：

1. Import 正确：从 @fexd/pro-components 统一导入
2. 响应格式：onQuery / onAdd / onEdit / onDelete 返回 { success, data?, total?, message? }
3. 命令式优先：弹窗用 showModal，图片预览用 showImages
4. 确认操作：删除等危险操作配置了 confirm
5. 类型匹配：字段 type 与数据类型匹配
6. 占位文案：所有表单字段提供明确的 placeholder
7. Ref 结构：ProTable ref 是按插件分组的对象（ref.current.queryField.refresh()），不要写 ref.current.refresh()
8. 默认值准确：refreshAfterEdit 默认 true（非 false）；preserve 默认 false（非 true）
9. hook 用法：hook 返回对象可修改除 name 外的所有配置，返回 false 隐藏字段
10. columns 继承：editField: true / queryField: true 从 column 继承 label/name/type/options
11. Ref 安全：在 useCoverableProps 中传 ref/tableRef/formRef 是安全的（自动提取），非 ref 特殊对象用 useCoverable.raw() 保护