Pro Components Vue2：为存量后台补齐现代工程能力

Pro Components Vue2 是一套面向 Vue 2.6 与 Element UI 存量管理后台的 TypeScript 业务组件库。它不试图重新发明基础 UI，而是把表单提交、查询分页、异步状态和复杂录入等高频工作整理成边界明确、可以测试的组件与 Hooks。

为什么现在还要做 Vue 2 组件库

Vue 2 已进入维护后期，但大量企业后台仍然稳定运行在 Vue 2.6 与 Element UI 上。对这类系统来说，全面迁移 Vue 3 往往不是一个单独的技术升级，而是会同时触发路由、状态管理、构建工具、组件库和业务页面的连锁改造。

在迁移条件尚不成熟时，团队真正需要的是两件事：一是继续控制存量代码的维护成本，二是避免为了赶需求不断复制新的技术债。Pro Components Vue2 的定位就在这里——保留 Vue 2 与 Element UI 的既有运行基础，同时引入 Composition API、TypeScript、可等待的异步流程和可复用的业务抽象。

它适合渐进治理，不是用来证明旧技术栈可以无限延期。是否迁移 Vue 3，仍应根据浏览器范围、人员投入、业务节奏和依赖风险单独决策。

当前发布状态

截至 2026 年 9 月，npm 最新版本为 1.0.0，主分支提供：

• 25 个公开组件，覆盖表单容器、17 个表单字段、查询、表格与导航结构；
• 9 个组合式 Hook，以及一个前端局部标识工具；
• ESM、UMD、CSS、TypeScript 声明和 source map；
• 独立文档站、实时示例、组件 API、深色模式与站内搜索；
• ESLint、Prettier、类型检查、Vitest 回归测试和 GitHub Actions 门禁。

项目入口：

• GitHub 仓库
• 在线文档
• npm 包
• 更新日志

文档站跟随主分支部署，npm 则对应正式版本。评估或排查问题时，应先确认自己安装的版本，不要默认在线文档与本地锁文件始终处于同一个提交。

它主要解决什么问题

1. 把表单从控件集合提升为完整流程

ProForm 不只是排列输入框。它统一管理初始化数据、规则校验、重置、只读模式和提交状态，并通过 submitter 接收同步或异步提交函数。Promise 结束前，提交按钮保持 loading，重复操作会被拦截；只有校验和业务提交都成功后，才会触发 submit 事件。

ModalForm 与 DrawerForm 在此基础上补齐弹窗和抽屉工作流。字段层则覆盖文本、数字、日期、级联、上传、范围、评分、动态标签、动态列表和依赖显示等常见场景。

<template>
  <ProForm :initial-value="record" :rules="rules" :submitter="save">
    <template #default="{ formData }">
      <ProFormText
        v-model="formData.name"
        name="name"
        label="项目名称"
        required
      />
      <ProFormSelect
        v-model="formData.status"
        name="status"
        label="状态"
        :options="statusOptions"
      />
    </template>
  </ProForm>
</template>

这个设计的重点是明确责任：字段组件负责值与交互，ProForm 负责表单生命周期，业务层的 save 函数负责调用接口。任何一层失败，都不会被伪装成成功事件。

2. 让查询、表格和分页使用同一份协议

ProTable 使用列配置同时描述展示、搜索、枚举和操作列，减少页面里重复维护查询表单与表格字段。request 采用明确的返回协议：data、total 和 success；业务接口与该协议不一致时，可以通过 useProTableRequest 做适配。

import type { ICommonTableColumn } from "pro-components-vue2";

const columns: ICommonTableColumn[] = [
  { prop: "name", label: "姓名", searchPlaceholder: "搜索姓名" },
  {
    prop: "status",
    label: "状态",
    valueType: "select",
    valueEnum: {
      1: { label: "启用", value: 1, status: "success" },
      0: { label: "停用", value: 0, status: "warning" },
    },
  },
  {
    prop: "action",
    label: "操作",
    type: "actions",
    hideInSearch: true,
    buttons: [{ text: "编辑", type: "text", onClick: row => edit(row) }],
  },
];

const request = async (params: Record<string, unknown>) => {
  const result = await api.list(params);
  return { data: result.list, total: result.total, success: true };
};

useProTableRequest 还处理页码转换、刷新、重置、空白尾页回退和“最后一次请求获胜”。最后一项尤其重要：筛选条件快速变化时，较早发出的慢请求不应该覆盖最新结果。

3. 把异步语义做成可复用能力

组件库中的 Hooks 不追求数量，而是集中处理后台系统最容易重复出错的状态：

这些 API 的价值不在于少写几行代码，而在于把 loading 何时结束、错误是否抛出、重复请求如何处理、取消操作返回什么等行为固定下来。团队可以围绕同一份契约测试，而不必在每个页面重新解释。

4. 保持 Element UI 可见，而不是把它藏起来

Pro Components Vue2 是业务层增强，不是新的视觉系统。底层仍然是 Element UI，原有主题、Form 规则和组件习惯可以继续使用。遇到库没有覆盖的场景，也可以直接组合 el-form、el-table 或原生插槽，不需要绕过一层封闭 DSL。

CustomTabs 与 Segmented 补充了方向键、Home、End、焦点样式等键盘交互。可访问性不是“有 ARIA 属性就结束”，实际项目仍需结合业务文案、焦点顺序、颜色对比度和读屏结果继续验证。

快速开始

运行时依赖由业务项目安装，组件库不会重复打包 Vue、Composition API 和 Element UI：

pnpm add pro-components-vue2 vue@2.6.14 @vue/composition-api element-ui

全局注册时，Composition API 必须先于组件库安装：

import Vue from "vue";
import VueCompositionAPI from "@vue/composition-api";
import ElementUI from "element-ui";
import ProComponentsVue2 from "pro-components-vue2";
import "element-ui/lib/theme-chalk/index.css";
import "pro-components-vue2/style.css";

Vue.use(VueCompositionAPI);
Vue.use(ElementUI);
Vue.use(ProComponentsVue2);

也可以使用命名导出，只注册当前页面需要的组件；样式仍需引入一次。

兼容边界

1.0.0 的支持范围是：

Vue 2.7 已内置 Composition API，与当前 peer dependency 模型不同，因此不在 1.0.0 的支持范围内。这个限制是显式边界，不应通过忽略安装警告来绕过。

组件库同样不会替业务项目解决接口鉴权、菜单权限、国际化、埋点或 Vue 3 迁移。它提供的是可组合的页面基础能力，而不是完整中后台框架。

工程质量如何保证

当前仓库的 check 命令会依次执行格式检查、Lint、TypeScript 检查、Vitest 和文档构建。本次发布基线包含 9 个测试文件、18 项测试，并在 Node.js 18 与 20 上运行 CI。

测试重点覆盖 Vue 2 v-model、异步提交 loading、动态标签、ProTable 请求竞态、全局安装和文档示例解析。构建同时验证组件库产物与文档站，避免“源码可以运行，但 npm 包入口、CSS 或声明文件不可用”的发布事故。

当然，自动化通过不等于业务 UAT。引入到真实项目后，仍应针对目标浏览器、既有 Element UI 主题、接口协议和关键表单流程做回归。

适合哪些项目

如果项目同时满足下面几项，Pro Components Vue2 会比较合适：

• 仍运行 Vue 2.6 与 Element UI，短期无法整体迁移；
• 表单、查询列表、弹窗和抽屉页面较多；
• 已经或准备使用 Composition API 与 TypeScript；
• 希望逐步统一异步状态和组件契约，而不是重写全部页面。

如果是全新项目，通常应优先评估 Vue 3 与仍在活跃维护的组件生态；如果现有系统已经是 Vue 2.7，也应先完成兼容性验证，而不是直接套用 2.6 的依赖方案。

结语

维护存量系统，不等于停止工程化。更现实的做法，是承认迁移需要时间，同时把新增代码的边界、类型、异步行为和验证方式逐步收紧。

Pro Components Vue2 正是一次这样的整理：不改变 Vue 2 后台的基本运行模型，但让高频业务页面拥有更一致的实现方式。如果你正在维护类似项目，可以从一个查询列表或一个抽屉表单开始试用，再根据真实收益决定采用范围。