企业管理系统前端组件化设计：为何 OA、CRM、ERP 表单不能直接用 Element UI 或 Ant Design

如果每个模块都从零开始组装，一个简单的表单页面就需要 300+ 行模板代码，更别说还有表单校验、状态管理、审批流对接等逻辑。

1.2 缺少业务语义

原生 UI 库不理解"审批状态"、'单据编号'、"数据字典"这些业务概念。你无法告诉 <a-tag> '这是一个审批状态标签，请根据字典自动配色'——你得自己写映射逻辑、自己管理颜色、自己处理异常值。

1.3 跨页面一致性难以保障

当团队有多个开发者同时开发不同模块时，如果没有统一的业务组件，每个人对"表单布局应该是几列"、'按钮顺序应该怎么排'、"状态标签用什么颜色"都有不同的理解。结果就是同一个系统，不同模块的 UI 风格和交互逻辑参差不齐。

1.4 表单与审批流的集成是噩梦

这是企业管理系统最大的痛点。一个业务表单不仅仅是"填数据然后提交"——它需要：

• 新建态：表单可编辑，底部显示"提交"和"保存"按钮
• 审批中：表单只读，显示审批进度时间线和审批记录
• 已审批：表单只读，可查看完整审批历史和流程图
• 已撤回：表单可重新编辑
• 审批不通过：可查看驳回原因，可重新发起

如果每个模块都自己处理这些状态逻辑，你会在 14 个模块中重复写 14 遍几乎相同但又不完全相同的代码。

二、组件化架构全景

2.1 组件目录结构

src/components/
├── basic-form/ # 🏗️ 核心业务表单（审批表单一体化）
│   ├── basic-form.vue # 主组件：表头 + Tab 页 + 表单 + 底部操作
│   ├── header-form.vue # 表头信息组件
│   ├── footer-form.vue # 底部操作按钮组件
│   ├── card-container.vue # 信息卡片容器
│   ├── flow-steps.vue # 审批进度步骤条
│   ├── no-flow-form.vue # 无审批流表单
│   ├── typing.ts # 类型定义
│   └── index.ts # 统一导出
├── attachment-list/ # 📎 附件管理组件
├── dict-tag/ # 🏷️ 数据字典标签
├── table-action/ # ⚡ 表格操作列
├── description/ # 📋 详情描述组件
├── upload/ # 📤 文件上传组件
├── input-amount/ # 💰 金额输入组件
├── shortcut-date-range-picker/ # 📅 快捷日期范围选择
├── help-input/ # 🔍 辅助选择输入框
└── ...

2.2 组件层次设计

┌─────────────────────────────────────────────────────────────┐
│ 业务页面层 (Views)                                          │
│ 用车申请单 / 用印申请单 / 请假单 / 入职申请单 / ...         │
├─────────────────────────────────────────────────────────────┤
│ 业务组件层 (Components)                                     │
│ BasicForm / AttachmentList / DictTag / TableAction / ...    │
├─────────────────────────────────────────────────────────────┤
│ Vben Admin 框架层                                           │
│ useVbenForm / Page / VxeTable / useTabs / ...               │
├─────────────────────────────────────────────────────────────┤
│ UI 基础层 (Ant Design Vue)                                  │
│ Form / Table / Input / Select / Tag / Button / ...          │
└─────────────────────────────────────────────────────────────┘

这四层架构让每一层都有清晰的职责边界：

• UI 基础层：提供原子组件，不包含任何业务逻辑
• 框架层：Vben Admin 的 useVbenForm 等工具，封装表单创建和管理
• 业务组件层：面向企业管理场景的业务组件，理解"审批流"、'单据'、"字典"等概念
• 业务页面层：具体业务模块，通过组合业务组件快速搭建

三、核心组件深度解析

3.1 BasicForm：审批表单一体化组件

这是整个组件体系中最核心、最复杂的组件。它将"业务表单"和"审批流程"无缝融合为一个统一的页面结构。

▲ 用车申请单新建页面：表头信息 + 单据信息 Tab + 基本信息卡片 + 附件信息卡片 + 底部操作按钮，所有这些都由 BasicForm 组件统一编排

单据提交审批后，BasicForm 自动切换为审批模式，展示审批信息和流程图两个额外 Tab：

▲ 审批信息 Tab：上方为审批进度时间线，清晰展示每个审批节点的状态；下方为审批记录表格，记录每次审批的节点、审批人、时间、状态、审批建议和耗时

▲ 流程图 Tab：渲染完整的审批流程图，直观展示发起人 → 部门负责人 → 车辆管理岗 → 结束的审批链路，每个节点标注审批角色和岗位信息

3.1.1 组件架构

BasicForm 采用关注点分离的设计思想，将一个复杂的审批表单页面拆解为多个子组件：

BasicForm
├── HeaderForm # 表头区域：标题 + 状态 + 单据编号 + 申请人信息
├── Tabs
│   ├── Tab 1: 单据信息
│   │   ├── CardContainer("基本信息")
│   │   │   ├── 内置表单 (useVbenForm) -- formSchema 模式
│   │   │   └── 插槽表单 (slot) -- 自定义模式
│   │   └── slot("form-extension") -- 扩展区域（附件、明细表等）
│   ├── Tab 2: 审批信息（仅审批中/已审批显示）
│   │   ├── BpmProcessInstanceTimeline # 审批进度时间线
│   │   └── BpmProcessInstanceTaskList # 审批记录表格
│   └── Tab 3: 流程图（仅审批中/已审批显示）
│       └── ProcessInstanceSimpleViewer # 流程图渲染器
└── FooterForm # 底部操作：提交 / 保存 / 撤回 / 删除 / 关闭

3.1.2 核心源码解析

表单初始化——支持 Schema 驱动和自定义插槽两种模式：

// BasicForm 表单初始化逻辑
function initForm() {
  if (props.formSchema && props.formSchema.length > 0 && !formApi) {
    const [Form, api] = useVbenForm({
      commonConfig: {
        componentProps: { class: 'w-full' },
        formItemClass: 'col-span-1', // 每行四列，每项占 1/4
        labelWidth: 120,
        disabled: props.disabled,
      },
      layout: 'horizontal',
      schema: props.formSchema,
      showDefaultActions: false,
      wrapperClass: 'grid-cols-4', // 4 列网格布局
    });
    FormComponent = Form;
    formApi = api;
  }
}

这里的设计精妙之处在于双模式支持：

• Schema 驱动模式：传入 formSchema，组件内部自动通过 useVbenForm 创建表单，适用于标准表单
• 自定义插槽模式：不传 formSchema，通过 <slot name="base-form"> 注入自定义表单，适用于复杂表单

模板结构——三 Tab 页签布局：

<a-tabs v-model:active-key="activeKey" class="custom-tabs">
  <!-- Tab 1: 单据信息 -->
  <a-tab-pane key="1" :tab="$t('common.billInfo')">
    <CardContainer title="$t('common.baseInfo')">
      <!-- Schema 模式渲染内置表单 -->
      <component v-if="formApi" :is="FormComponent" ref="formRef" />
      <!-- 插槽模式使用自定义表单 -->
      <slot v-else name="base-form"></slot>
    </CardContainer>
    <!-- 扩展区域：明细表格、附件等 -->
    <slot name="form-extension"></slot>
  </a-tab-pane>
  <!-- Tab 2: 审批信息（条件渲染） -->
  <a-tab-pane key="2" :tab="$t('common.approvalInfo')" v-if="headerData.processInstanceId && headerData.processStatus">
    <CardContainer title="$t('common.approvalProgress')">
      <BpmProcessInstanceTimeline :activity-nodes="activityNodes"/>
    </CardContainer>
    <CardContainer title="$t('common.approvalRecord')">
      <BpmProcessInstanceTaskList :id="headerData.processInstanceId"/>
    </CardContainer>
  </a-tab-pane>
  <!-- Tab 3: 流程图（条件渲染） -->
  <a-tab-pane key="3" :tab="$t('common.processFlow')" :force-render="true" v-if="headerData.processInstanceId && headerData.processStatus">
    <ProcessInstanceSimpleViewer :model-view="processModelView"/>
  </a-tab-pane>
</a-tabs>

核心设计思想： 审批信息和流程图这两个 Tab 仅在单据已提交审批后才显示，通过 v-if="headerData.processInstanceId && headerData.processStatus" 条件控制。新建单据时只显示"单据信息"一个 Tab，提交审批后自动出现后两个 Tab。

3.1.3 业务页面如何使用 BasicForm？

以用车申请单为例，一个完整的业务表单页面只需要不到 50 行模板代码：

<template>
  <Loading :spinning="loading">
    <BasicForm
      ref="basicFormRef"
      :header-data="{ ...formData, billName: '用车申请单' }"
      :form-data="formData"
      :form-schema="formSchema"
      :disabled="readonly"
      @close="handleClose"
      @save="handleSaveAndSubmit(false)"
      @submit="handleSaveAndSubmit(true)"
      @revoke="handleRevoke"
      @delete="handleDelete"
      :hide-footer="props.isApproval"
      :activity-nodes="props.activityNodes"
    >
      <template #form-extension>
        <CardContainer :title="$t('common.attachmentInfo')">
          <template #extra>
            <Button v-if="!readonly" type="primary" @click="handleUploadAttachment">
              上传附件
            </Button>
          </template>
          <AttachmentList ref="attachmentListRef" v-model="formData.attachments" :readonly="readonly" />
        </CardContainer>
      </template>
    </BasicForm>
  </Loading>
</template>

对比一下如果不用 BasicForm，直接用原生 Ant Design 构建同样的页面，你至少需要 500+ 行模板代码——表头布局、Tab 切换、表单渲染、审批进度查询、流程图加载、按钮状态控制，每一样都要自己写。

3.2 HeaderForm：表头信息组件

HeaderForm 负责展示单据的关键元信息，让用户一眼就能把握单据的全貌。

<!-- 表头信息展示 -->
<div>
  <h2>{{ headerData.billName }}</h2>
  <div>
    <span>单据编号：{{ headerData.billCode }} <CopyOutlined @click="copyBillCode" /> <!-- 一键复制 --> </span>
    <span>申请人：{{ headerData.creatorName }}</span>
    <span>申请日期：{{ formatDate(headerData.createTime) }}</span>
    <span>所属单位：{{ headerData.companyName }}</span>
    <span>所属部门：{{ headerData.deptName }}</span>
  </div>
  <!-- 状态标签：右上角醒目展示 -->
  <DictTag :type="DICT_TYPE.BPM_PROCESS_INSTANCE_STATUS" :value="headerData.processStatus" />
</div>

设计要点：

• 所有审批表单的表头信息格式统一，用户切换不同业务模块时没有学习成本
• 单据编号支持一键复制，方便沟通协作
• 状态标签使用 DictTag 组件，自动根据字典配置显示颜色

3.3 FooterForm：智能底部操作栏

FooterForm 根据单据的审批状态自动控制按钮的显示与隐藏：

// footer-form.vue 中的按钮显示逻辑
const processStatus = props.processStatus;
// 提交按钮：仅在"未提交"和"已撤回"状态显示
const showSubmit = computed(() => !props.hideSubmit && BpmProcessInstanceStatusEditValue.includes(processStatus));
// 保存按钮：仅在可编辑状态显示
const showSave = computed(() => !props.hideSave && BpmProcessInstanceStatusEditValue.includes(processStatus));
// 撤回按钮：仅在"审批中"状态显示
const showRevoke = computed(() => processStatus === BpmProcessInstanceStatus.RUNNING);
// 删除按钮：仅在"未提交"状态显示
const showDelete = computed(() => !props.hideDelete && processStatus === BpmProcessInstanceStatus.NOT_START);

这意味着业务开发者完全不需要关心按钮的显隐逻辑——只需要传入 processStatus，FooterForm 会自动处理一切。同时，撤回和删除按钮都内置了二次确认弹窗（Popconfirm），防止误操作。

3.4 DictTag：数据字典标签组件

在企业管理系统中，"状态"字段无处不在——审批状态、车辆状态、请假类型、合同阶段…。DictTag 组件统一解决了字典值的展示问题：

▲ 用车申请单列表页面：单据状态列使用 DictTag 自动渲染彩色标签，操作列使用 TableAction 统一管理

<!-- dict-tag.vue 核心逻辑 -->
<template>
  <a-tag v-for="dict in getDictOptions" :key="dict.value" :color="dict.colorType">
    {{ dict.label }}
  </a-tag>
</template>
<script setup lang="ts">
const props = defineProps<{
  type: string; // 字典类型（如 'bpm_process_instance_status'
  value: any; // 字典值（如 10、20、30）
}>();
// 自动从全局字典缓存中获取选项并匹配
const getDictOptions = computed(() => {
  const options = getDictOpts(props.type);
  return options.filter(dict => dict.value === String(props.value));
});
</script>

使用极其简单，只需一行代码：

<DictTag :type="DICT_TYPE.BPM_PROCESS_INSTANCE_STATUS" :value="row.processStatus"/>

无需关心"审批中"是什么颜色、"已通过"用什么标签——所有配色方案都在后台字典管理中统一维护。

3.5 TableAction：表格操作列组件

表格操作列是 CRUD 页面的标配，但直接用 <a-button> 拼接会导致代码冗长且不统一。TableAction 将常见的操作列模式标准化：

<!-- table-action.vue 关键设计 -->
<template>
  <div>
    <template v-for="action in actions" :key="action.label">
      <!-- 权限控制：无权限时自动隐藏 -->
      <template v-if="hasPermission(action.auth)">
        <!-- 带确认弹窗的危险操作 -->
        <a-popconfirm v-if="action.popConfirm" :title="action.popConfirm.title" @confirm="action.popConfirm.confirm">
          <a-button v-bind="getButtonProps(action)"> {{ action.label }} </a-button>
        </a-popconfirm>
        <!-- 普通操作按钮 -->
        <a-button v-else v-bind="getButtonProps(action)"> {{ action.label }} </a-button>
      </template>
    </template>
    <!-- 更多操作下拉菜单（超过 N 个按钮时自动折叠） -->
    <a-dropdown v-if="dropdownActions.length > 0">
      <a-button type="link">更多 <DownOutlined /></a-button>
      <template #overlay>
        <a-menu>
          <a-menu-item v-for="action in dropdownActions" :key="action.label" @click="action.onClick">
            {{ action.label }}
          </a-menu-item>
        </a-menu>
      </template>
    </a-dropdown>
  </div>
</template>

核心能力：

• 权限控制集成：通过 auth 属性关联 RBAC 权限，无权限时按钮自动隐藏
• 危险操作保护：删除等操作内置 Popconfirm 二次确认
• 自动折叠：操作按钮过多时自动折叠为"更多"下拉菜单
• 样式统一：链接型/主按钮/危险按钮等样式标准化

3.6 AttachmentList：附件管理组件

企业管理系统中，几乎每个业务单据都需要附件管理功能。AttachmentList 提供了完整的附件生命周期管理：

<!-- attachment-list.vue 核心功能 -->
<template>
  <vxe-table :data="attachments" :loading="loading">
    <vxe-column type="seq" title="序号" />
    <vxe-column field="name" title="文件名" />
    <vxe-column field="size" title="文件大小">
      <template #default="{ row }">{{ formatFileSize(row.size) }}</template>
    </vxe-column>
    <vxe-column field="type" title="文件类型" />
    <vxe-column field="createTime" title="上传时间" />
    <vxe-column field="remark" title="备注">
      <!-- 可编辑备注列 -->
      <template #default="{ row }">
        <a-input v-if="!readonly" v-model:value="row.remark" />
        <span v-else>{{ row.remark }}</span>
      </template>
    </vxe-column>
    <vxe-column title="操作">
      <template #default="{ row }">
        <a-button type="link" @click="previewFile(row)">预览</a-button>
        <a-button type="link" @click="downloadFile(row)">下载</a-button>
        <a-button v-if="!readonly" type="link" danger @click="deleteFile(row)">删除</a-button>
      </template>
    </vxe-column>
  </vxe-table>
</template>

设计亮点：

• 双上传模式：支持客户端直传 S3（大文件）和服务端中转（安全场景）
• 只读控制：审批中/已审批状态自动隐藏上传和删除按钮
• 内联编辑：备注列在可编辑状态下直接输入，无需弹窗
• 文件预览：支持图片、PDF、Office 文档在线预览

3.7 InputAmount：金额输入组件

金额输入在 ERP、CRM、财务等模块中至关重要。原生 <a-input-number> 不支持千分位格式化，InputAmount 弥补了这个不足：

<!-- input-amount/index.vue 核心逻辑 -->
<template>
  <a-input v-model:value="displayValue" @focus="onFocus" @blur="onBlur" :suffix="suffix" :placeholder="placeholder">
  </a-input>
</template>
<script setup lang="ts">
// 焦点时显示原始数字（方便编辑）
function onFocus() {
  displayValue.value = String(actualValue.value);
}
// 失焦时格式化为千分位
function onBlur() {
  displayValue.value = formatAmount(actualValue.value, props.precision);
}
// 千分位格式化：1234567.89 → 1,234,567.89
function formatAmount(value: number, precision: number): string {
  return value.toFixed(precision).replace(/\B(?=(\d{3})+(?!\d))/g, ',');
}
</script>

3.8 ShortcutDateRangePicker：快捷日期范围选择

列表页的日期筛选是高频操作。ShortcutDateRangePicker 在标准日期范围选择器上增加了快捷选项：

<template>
  <div>
    <!-- 快捷按钮组 -->
    <a-radio-group v-model:value="shortcutKey" @change="onShortcutChange">
      <a-radio-button value="yesterday">昨天</a-radio-button>
      <a-radio-button value="last7days">最近 7 天</a-radio-button>
      <a-radio-button value="last30days">最近 30 天</a-radio-button>
      <a-radio-button value="thisMonth">本月</a-radio-button>
      <a-radio-button value="lastMonth">上月</a-radio-button>
    </a-radio-group>
    <!-- 自定义日期范围 -->
    <a-range-picker v-model:value="dateRange" @change="onDateChange" />
  </div>
</template>

3.9 HelpInput：辅助选择输入框

在企业管理系统中，很多字段不是手动输入的，而是从关联数据中选择的——比如"选择车辆"、'选择客户'、'选择产品'。HelpInput 提供了统一的选择器交互模式：

<!-- help-input/index.vue -->
<template>
  <a-input v-model:value="displayValue" readonly :placeholder="placeholder" @click="openSelector">
    <template #suffix>
      <SearchOutlined />
    </template>
  </a-input>
</template>

设计思路： 输入框本身是只读的，禁止手动输入和粘贴，只能通过点击后缀图标打开选择弹窗进行选择。这保证了数据的关联完整性——用户选择的一定是系统中真实存在的数据。

四、CardContainer：看似简单，实则不可或缺

CardContainer 是所有业务组件中最简单的一个，但它的存在至关重要：

<!-- card-container.vue -->
<template>
  <div>
    <div>
      <div>
        <span></span> <!-- 左侧蓝色竖条 -->
        <span>{{ title }}</span>
      </div>
      <div>
        <slot name="extra"></slot> <!-- 右侧操作区 -->
      </div>
    </div>
    <div>
      <slot></slot>
    </div>
  </div>
</template>

它解决的问题是信息分区——在一个长表单中，如果所有字段平铺展示，用户很难快速定位。CardContainer 通过标题和分割线将表单划分为"基本信息"、'附件信息'、"明细信息"等多个逻辑区域，提升了信息的可读性和可扫描性。

五、NoFlowForm：无审批流表单

并非所有业务都需要走审批流程。NoFlowForm 是 BasicForm 的轻量版本，适用于基础数据维护（如车辆信息管理、客户信息编辑等）：

<!-- no-flow-form.vue -->
<template>
  <Page>
    <a-layout>
      <a-layout-header>
        <h2>{{ title }}</h2>
      </a-layout-header>
      <a-layout-content>
        <slot name="form-content"></slot>
      </a-layout-content>
      <a-layout-footer>
        <div>
          <a-button type="primary" @click="$emit('submit')">提 交</a-button>
          <a-button @click="$emit('save')">保 存</a-button>
          <a-button @click="$emit('close')">关 闭</a-button>
        </div>
      </a-layout-footer>
    </a-layout>
  </Page>
</template>

与 BasicForm 共享相同的布局风格和底部操作栏设计，保证了审批流表单和非审批流表单的 视觉一致性。

六、组件化带来的实际收益

6.1 开发效率对比

6.2 代码量对比

以 OA 模块为例（用车申请单、用印申请单、会议室预约等 6 个子模块）：

• 不使用 BasicForm 等组件：每个子模块约需 800-1200 行前端代码 → 总计 ~6000 行
• 使用组件体系：每个子模块约需 200-400 行前端代码 → 总计 ~1800 行
• 组件本身：约 1200 行代码（一次投入，所有模块受益）

总代码量减少约 50%，且随着模块数量增加，收益越来越明显。

6.3 维护成本对比

当需求变更时（例如"所有审批表单的底部增加一个'转交'按钮"），组件化架构只需修改 footer-form.vue 一个文件，所有业务模块自动生效。不使用组件的话，你需要逐一修改每个模块——这在一个有 14 个业务模块的系统中，意味着改 30+ 个文件。

七、组件化设计的六大原则

回顾整个组件化架构的设计过程，我们总结出六大核心原则：

1. 面向业务语义封装

组件不只是 UI 的组合，更要理解业务概念。BasicForm 理解"审批状态"，DictTag 理解"数据字典"，FooterForm 理解"单据生命周期"。

2. 双模式兼容

核心组件同时支持"约定优先"和"自由定制"两种使用方式。BasicForm 既支持 Schema 驱动的标准表单，也支持插槽注入的自定义表单。

3. 状态驱动 UI

按钮显隐、字段禁用、Tab 可见性等，全部由数据状态驱动，业务开发者只需传入正确的状态值。

4. 关注点分离

每个子组件只负责一个关注点：HeaderForm 管表头、FooterForm 管按钮、CardContainer 管分区、DictTag 管字典。

5. 渐进式增强

从 NoFlowForm（最简单）到 BasicForm（全功能），组件体系提供不同层级的抽象，开发者可以根据业务复杂度选择合适的组件。

6. 国际化优先

所有组件的文本都通过 $t() 国际化函数处理，支持多语言切换。

八、总结：组件化是企业管理系统的必经之路

在企业管理系统的开发中，前端组件化不是"锦上添花"，而是生存必需。当你的系统需要支撑 OA、CRM、ERP、HRM 等多个业务模块，每个模块都有大量结构相似的表单和列表时，如果没有一套经过精心设计的组件体系，你将面临：

• 💥 代码爆炸：重复代码遍地开花
• 🎨 风格割裂：每个模块长得都不一样
• 🐛 Bug 传染：同一个逻辑在多处存在，修了一处漏了另一处
• 🐌 开发缓慢：每个新模块都从零开始

该系统的组件化实践证明：通过合理的抽象和封装，可以让一个拥有 14 个业务模块的大型企业管理系统保持代码的整洁、一致和可维护性。

如果你也在做企业管理系统，强烈建议投入时间建设自己的业务组件体系——这笔前期投入，会在后续的开发维护中获得数十倍的回报。