@trasen/vben-ant-design

@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';

组件列表

通用组件

布局组件

数据录入

数据展示

导航组件

权限组件

基础示例

表单

<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+），仅在使用对应组件时按需加载：

以上所有依赖均通过 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