@trasen/vben-ant-design

基于 Ant Design Vue 4.x 的业务组件库，提供 40 个开箱即用的企业级组件。

项目结构

@trasen/vben-ant-design/
├── src/
│   ├── components/        # 业务组件（Button、Table、Form、Modal 等）
│   ├── config-provider/   # 全局配置提供器
│   ├── hooks/             # 组合式函数（useDesign、useForm、useTable 等）
│   ├── utils/             # 工具函数
│   ├── enums/             # 枚举常量
│   ├── design/            # 样式变量与主题
│   ├── index.ts           # 库入口，导出所有组件、hooks、utils
│   └── install.ts         # 全局注册插件入口
├── dist/                  # 构建产物（发布到 npm 的内容）
├── package.json           # 包配置、依赖、脚本
├── vite.config.ts         # Vite 库模式构建配置
├── tsconfig.json          # TypeScript 配置
└── README.md              # 本文档

安装

npm install @trasen/vben-ant-design

npm 7+ 会自动安装以下依赖（vue 由项目本身提供）：

• ant-design-vue ^4.0.0
• vue-i18n ^9.0.0
• vue-router ^4.0.0
• @ant-design/icons-vue ^7.0.0

@vueuse/core、dayjs、lodash-es 已内置打包，无需额外安装。

使用

全局注册

import { createApp } from 'vue';
import VbenComponents from '@trasen/vben-ant-design';
import '@trasen/vben-ant-design/style.css';

const app = createApp(App);
app.use(VbenComponents);

按需引入

import { BasicButton, BasicTable, BasicForm } from '@trasen/vben-ant-design';
import '@trasen/vben-ant-design/style.css';

组件列表

通用组件

| 组件 | 说明 | |------|------| | BasicButton | 按钮组件，支持颜色、图标、加载态 | | PopConfirmButton | 带确认气泡的按钮 | | BasicArrow | 箭头图标组件 | | BasicHelp | 帮助提示组件 | | BasicTitle | 标题组件 | | CardList | 卡片列表 | | CountDown | 倒计时组件 | | CountTo | 数字滚动组件 | | ClickOutSide | 点击外部区域触发 | | ContextMenu | 右键菜单 | | Cropper | 图片裁剪组件 | | EllipsisText | 文本省略组件 | | Icon | 图标组件（支持 SvgIcon、IconPicker） | | Loading | 加载组件 | | Preview | 图片预览组件 | | Prompt | 对话框组件 | | Qrcode | 二维码组件 | | Scrollbar | 自定义滚动条 | | StrengthMeter | 密码强度检测 | | Time | 时间显示组件 | | Transition | 过渡动画组件 | | VirtualScroll | 虚拟滚动组件 | | Verify | 验证码组件（滑动、旋转） |

布局组件

| 组件 | 说明 | |------|------| | Application | 应用壳组件（Logo、语言切换、暗黑模式切换） | | Container | 容器组件（折叠面板、滚动容器） | | Drawer | 抽屉组件 | | Modal | 模态框组件 | | Page | 页面容器组件 |

数据录入

| 组件 | 说明 | |------|------| | BasicForm | 表单组件，支持动态表单、API 数据源 | | Upload | 上传组件（文件上传、图片上传） | | CodeEditor | 代码编辑器 | | FlowChart | 流程图组件 | | Markdown | Markdown 编辑器 | | Tinymce | 富文本编辑器 |

数据展示

| 组件 | 说明 | |------|------| | BasicTable | 表格组件，支持编辑、排序、筛选、导出 | | VxeBasicTable | VxeTable 表格组件 | | Description | 描述列表组件 | | Tree | 树形组件 | | Excel | Excel 导出组件 |

导航组件

| 组件 | 说明 | |------|------| | BasicMenu | 侧边栏菜单 | | SimpleMenu | 顶部菜单 | | Dropdown | 下拉菜单 | | Menu | 菜单组件（含 SubMenu、MenuItem） |

权限组件

| 组件 | 说明 | |------|------| | Authority | 权限控制组件 |

基础示例

表单

<template>
  <BasicForm @register="register" />
</template>

<script setup>
import { BasicForm, useForm } from '@trasen/vben-ant-design';

const [register, { validate }] = useForm({
  schemas: [
    { field: 'name', label: '名称', component: 'Input', required: true },
    { field: 'status', label: '状态', component: 'Select', componentProps: { options: [...] } },
  ],
});
</script>

表格

<template>
  <BasicTable @register="register" />
</template>

<script setup>
import { BasicTable, useTable } from '@trasen/vben-ant-design';

const [register, { reload }] = useTable({
  api: fetchList,
  columns: [
    { title: '名称', dataIndex: 'name' },
    { title: '状态', dataIndex: 'status' },
  ],
});
</script>

模态框

<template>
  <BasicModal @register="register" title="标题">
    <p>内容</p>
  </BasicModal>
</template>

<script setup>
import { BasicModal, useModal } from '@trasen/vben-ant-design';

const [register, { openModal }] = useModal();
</script>

抽屉

<template>
  <BasicDrawer @register="register" title="标题">
    <p>内容</p>
  </BasicDrawer>
</template>

<script setup>
import { BasicDrawer, useDrawer } from '@trasen/vben-ant-design';

const [register, { openDrawer }] = useDrawer();
</script>

可选依赖

以下可选依赖也会在安装时自动安装（npm 7+），仅在使用对应组件时按需加载：

| 组件 | 依赖 | |------|------| | FlowChart | @logicflow/core @logicflow/extension | | CodeEditor | codemirror | | Cropper | cropperjs | | Tinymce | tinymce | | Markdown | showdown vditor | | Qrcode | qrcode | | Excel | exceljs xlsx | | Icon | @iconify/iconify @ant-design/icons-vue | | StrengthMeter | @zxcvbn-ts/core | | VxeTable | vxe-table vxe-table-plugin-export-xlsx xe-utils |

以上所有依赖均通过 optionalDependencies 声明，执行 npm install @trasen/vben-ant-design 时会自动安装，无需手动操作。

本地开发

环境要求

• Node.js >= 18
• pnpm >= 8（推荐）

安装依赖

pnpm install

启动开发环境

pnpm dev

本地调试（Playground）

项目内置了一个基于 Vite 的 Playground，用于组件开发和热更新调试。

启动后会打开浏览器，左侧是组件导航，右侧是组件演示区域。所有示例位于 dev/demos/ 目录下：

dev/
├── App.vue           # Playground 主页面
├── main.ts           # 入口
├── index.html        # HTML 模板
└── demos/            # 各组件示例
    ├── ButtonDemo.vue
    ├── FormDemo.vue
    ├── TableDemo.vue
    └── ...

添加新组件示例

1. 在 dev/demos/ 下新建 XxxDemo.vue
2. 在 dev/App.vue 的 demos 数组中注册导航项
3. 保存后浏览器会自动热更新

调试源码

• 修改 src/components/ 下的组件源码，Playground 会实时热更新
• 修改 src/hooks/、src/utils/ 同样会触发热更新
• 样式使用 Less，变量定义在 src/design/variables.less

在业务项目中调试

如果你想在真实业务项目中预览和调试组件效果，推荐以下两种方式：

方式一：pnpm link（实时同步修改）

在组件库目录执行：

pnpm link --global

然后在目标业务项目目录执行：

pnpm link --global @trasen/vben-ant-design

这样业务项目会直接引用本地组件库的源码/产物，修改组件库后业务项目会实时生效。

方式二：本地打包安装

先构建并打包成 tgz 文件：

pnpm build
npm pack

然后在目标业务项目中安装生成的 tgz 包：

npm install /path/to/@trasen/vben-ant-design-1.0.0.tgz

这种方式适合验证发布前的最终产物。

调试样式与类型

• 组件样式统一打包为 dist/style.css，调试时确认业务项目已引入：import '@trasen/vben-ant-design/style.css'
• 若类型提示异常，可尝试重启业务项目的 TypeScript 服务或删除 node_modules/.cache

打包构建

项目使用 Vite 的 Library Mode 构建，输出 ESM / CJS 两种格式，并自动生成类型声明文件。

pnpm build

构建产物位于 dist/ 目录：

dist/
├── index.mjs          # ESM 入口
├── index.cjs          # CJS 入口
├── index.d.ts         # 类型声明入口
├── install.d.ts       # 全局注册插件类型声明
├── style.css          # 组件样式
└── ...                # 各组件拆分产物

构建前会进行类型检查：

pnpm type:check

发布到 npm

1. 登录 npm

npm login

2. 构建并发布

prepublishOnly 脚本会在发布前自动执行构建：

npm publish --access public

3. 预览即将发布的文件

pnpm publish:check

版本管理

发布前请修改 package.json 中的 version 字段，遵循 SemVer 规范：

• major：破坏性更新
• minor：新增功能（向后兼容）
• patch：修复问题（向后兼容）

License

MIT