agent/.opencode/skills/tech-stack/umijs-procomponents/SKILL.md

name, description

name	description
umijs-procomponents	UmiJS 4 + Ant Design 5 + ProComponents 全栈开发规范。涵盖技术栈约束、组件用法、样式系统、服务层架构、国际化和图标管理。当项目使用 UmiJS + ProComponents 技术栈时，PM 必须将本 Skill 的要点注入给所有子 Agent。

UmiJS + ProComponents 开发规范

1. 技术栈

• 框架: UmiJS 4 + React 18 + TypeScript（严格模式）
• UI 库: Ant Design 5 + ProComponents（ProTable, ProForm, ProLayout 等）
• 数据流: useRequest（ahooks / Umi 内置）、Umi Models
• 路由/权限: Umi Max 内置插件 — access、initialState、request、model、locale

2. ProComponents 使用规范

2.1 组件选型原则

• 配置优于代码: 始终优先使用 ProComponents 的 request 属性处理数据加载。
• 利用 valueType 进行字段自动格式化。
• 只有在 ProComponents 无法满足极度复杂需求时才使用原生 Antd 或手动实现。

2.2 组件映射

场景	组件
列表/表格	ProTable
表单	ProForm / ModalForm / DrawerForm
搜索/筛选	QueryFilter / LightFilter
布局	ProLayout / PageContainer
详情	ProDescriptions

2.3 ⚠️ 禁止双内边距

• 严禁在 ProTable、QueryFilter、ProForm 外层包裹 Card 组件。
• 原因: ProComponents 自带卡片样式，额外包裹导致双内边距问题。
• 错误示例: <Card><ProTable /></Card> ❌
• 正确示例: <ProTable style={{ marginBottom: token.marginLG }} /> ✅

3. 搜索区域规范（Separated Card 模式）

3.1 复杂度规则

• < 4 个搜索字段: 使用 ProTable 内置 search 属性。
• >= 4 个搜索字段: 使用独立 QueryFilter 组件，配置 layout="vertical"。

3.2 视觉结构

• 搜索区域: 直接使用 QueryFilter（自带白色背景和内边距）。
• 背景色: QueryFilter 必须设置白色背景（token.colorBgContainer）。
• 表格区域: 直接使用 ProTable（自带卡片样式）。
• 间距: QueryFilter 使用 style={{ marginBottom: token.marginLG }}。
• ⚠️ 避免双内边距: 不要在 QueryFilter 或 ProTable 外层再包裹 div 或 Card 添加 padding。

4. 样式系统

4.1 零 CSS 文件

• 严格使用 Ant Design Design Tokens 内联样式。
• 使用 const { token } = theme.useToken() 获取 token。
• 间距调整: 使用 style={{ marginBottom: token.marginLG }} 而非外层容器。
• 禁止导入 .module.css 或外部样式表。

4.2 图标

• 统一使用 @ant-design/icons。
• 除非明确要求或用于特定品牌标志，否则不使用外部图标库、SVG 或 emoji。

4.3 UI 框架

• 严格使用原生 Ant Design ProComponents。禁止自定义 UI/UX 设计工具。
• 表单布局: 输入标签放在输入框上方（layout="vertical"）。

5. 服务层架构

5.1 真实服务层

• 所有页面逻辑必须调用 src/services/。禁止在 JSX 中内联 mock 数据或逻辑。
• 强制使用 useRequest: 所有数据交互（包括查询、提交、删除）必须通过 useRequest hook 发起。
• 禁止直接 request: 严禁在组件内直接手动调用 request 方法（除非在极特殊的底层封装中）。useRequest 提供了标准化的 loading、error 和 data 状态管理，手动 request 会导致状态管理不一致。

5.2 统一 Mocking

• 使用 UmiJS mock/ 目录存放所有 mock 数据。禁止在组件中硬编码对象。

5.3 类型定义

• TypeScript 接口统一在 data.d.ts 中定义。

5.4 菜单配置

• 菜单图标必须在 src/app.ts 中配置渲染逻辑（确保图标显示为图形而非文本）。
• 菜单文案必须配置在 src/locales/ 中，Key 以 menu. 开头（如 menu.system.user）。

6. 国际化 (i18n)

6.1 强制规则

• 所有面向用户的字符串必须使用 intl.formatMessage 或 <FormattedMessage>。
• 每个 formatMessage 或 FormattedMessage 调用必须包含 defaultMessage 作为后备。
  • 示例: intl.formatMessage({ id: 'key', defaultMessage: '默认文案' })
• 在 src/locales/ 中维护翻译。

6.2 双语同步

• 必须同时在 src/locales/zh-CN.ts 和 en-US.ts 中定义所有使用的 Key。
• 严禁仅添加中文而忽略英文，或仅添加英文而忽略中文。

6.3 QA 验证

• 测试时必须在两种语言环境下验证页面显示。
• 浏览器控制台不得出现 [React Intl] Missing message 警告。

7. Figma 图标导出规范

当 Figma 设计稿中包含图标元素时：

7.1 优先级原则

1. 优先匹配 Ant Design Icons: 检查设计稿中的图标是否可用 @ant-design/icons 替代。如果视觉上高度一致，必须使用 Ant Design 图标。
2. 自定义图标导出: 仅当 Ant Design Icons 中没有匹配或视觉差异明显时，才从 Figma 导出。

7.2 导出流程

1. 使用 Figma MCP 获取图标设计详情。
2. 导出为 SVG 格式，保存到 src/assets/icons/。
3. 文件命名: icon-{功能名称}.svg（全小写，中划线分隔）。
4. 封装为 React 组件存放 src/components/Icons/。
5. 在 src/components/Icons/index.ts 中统一导出。

7.3 目录结构

src/
├── assets/icons/
│   ├── icon-custom-chart.svg
│   └── icon-data-flow.svg
└── components/Icons/
    ├── index.ts
    ├── CustomChartIcon.tsx
    └── DataFlowIcon.tsx

8. Ant Design 5 兼容性

• 使用 open 而非 visible。
• 使用 onOpenChange 而非 onVisibleChange。
• 对 Ant Design 5 更新极为警惕，避免使用废弃 API。