Vben Frontend Dev

Vben Admin 前端开发技能

概述

指导 AI 开发者使用 Vben Admin 5.x 框架构建标准化前端页面。确保代码模式一致、组件使用规范、架构可维护。

何时使用

触发此技能的场景：

• 创建新页面（列表、详情、表单）
• 使用 VbenForm、VxeGrid、Modal 组件
• 配置主题或布局
• 添加路由或权限
• 任何 Vue 3 + Vben Admin 前端开发工作

输入参数

输入优先级

YAML 页面规格 > HTML 线框图 > 关键词推断

YAML → Schema 转换

当输入包含 YAML 页面规格时，直接读取生成 Schema：

// 读取 YAML 页面规格
const pageSpec = parseYaml(input.yaml_page_spec);

// 直接生成 Schema（无需推断）
// 搜索区 → formOptions.schema
const searchSchema = pageSpec.config.search.fields.map(f => ({
  fieldName: f.field,
  label: f.name,
  component: f.component,
  placeholder: f.placeholder,
}));

// 表格列 → gridOptions.columns
const tableColumns = pageSpec.config.table.columns.map(c => ({
  field: c.field,
  title: c.title,
  width: c.width,
  align: c.align,
  component: c.component,
}));

// 表单字段 → VbenForm schema
const formSchema = pageSpec.config.form.fields.map(f => ({
  fieldName: f.field,
  label: f.name,
  component: f.component,
  rules: f.required ? 'required' : undefined,
}));

HTML 线框图解析

当输入包含 HTML+CSS 线框图时，解析 class → 组件映射：

// 从 HTML class 推断组件
const classMap = {
  'field input': 'Input',
  'field select': 'Select',
  'field date': 'DatePicker',
  'field number': 'InputNumber',
  'field textarea': 'TextArea',
  'tag': 'Tag',
  'btn btn-primary': 'Button(primary)',
  'table': 'VxeGrid',
  'modal': 'VbenModal',
};

// 从占位文字提取字段名
// [商品名称] → fieldName: 'name', label: '商品名称'
const fieldName = html.match(/\[(.*?)\]/)?.[1];

// 从组件标注确认类型
// <div class="label">组件：搜索表单</div> → search area
const componentLabel = html.match(/组件：(\w+)/)?.[1];

HTML class → 组件映射表

CSS 样式处理

注意：HTML 线框图的 CSS 样式是灰色示意，不是真实样式。

/* 线框图 CSS - 不应用 */
.wireframe { border: 1px dashed #999; background: #f5f5f5; }
.field { border: 1px solid #999; background: #fff; color: #999; }
.btn-primary { background: #aaa; }  /* 灰色，不是真实主色 */

/* 真实样式 - 使用 Vben 框架默认或 saas-ui-design 约束 */
.btn-primary { 
  /* 使用框架默认样式，自动符合约束 */
}

线框图 CSS 只用于识别结构，不直接应用到生成的代码中。

UI 约束应用

生成的代码自动应用内置约束（无需显式调用 saas-ui-design）：

开发流程（改进版）

Step 0：读取输入（新增）

// 检测输入类型
if (input.yaml_page_spec) {
  // YAML 直接读取
  pageType = parseYaml(input.yaml_page_spec).type;
  schema = generateSchemaFromYaml(input.yaml_page_spec);
} else if (input.html_wireframe) {
  // HTML 解析
  pageType = inferPageTypeFromHtml(input.html_wireframe);
  schema = generateSchemaFromHtml(input.html_wireframe);
} else {
  // 关键词推断（兜底）
  pageType = inferPageType(input.keywords);
}

Step 1：定义 Schema

根据输入类型生成 Schema：

• YAML → 直接读取
• HTML → class 映射
• 关键词 → 推断

task_type 优先级

new_page > route_add > theme_config > modal_add > field_change

组合场景

项目结构

{project_root}/                       # Vben Admin 5.x 项目（从当前工作目录推断）
├── apps/web-antd/
│   ├── src/
│   │   ├── views/                     # 页面目录
│   │   ├── api/                       # API 定义
│   │   └── preferences.ts             # 主题/布局配置
│   └── tailwind.config.mjs            # Tailwind 扩展
└── packages/
    ├── @core/ui-kit/shadcn-ui/        # UI 组件库
    └── effects/plugins/vxe-table/     # 表格组件

注意: {project_root} 从当前工作目录推断。禁止硬编码绝对路径。

页面开发模式

标准结构

views/module/feature/
├── index.vue           # 主页面（列表/详情）
├── data.ts             # Schema 定义
└── modules/
    └── form.vue        # 表单弹窗

开发流程

1. 定义 Schema → data.ts（表单 schema、列定义）
2. 创建 API → api/module/feature.ts（CRUD 函数）
3. 构建列表页 → index.vue（VxeGrid + 搜索表单）
4. 构建表单弹窗 → modules/form.vue（VbenForm + VbenModal）
5. 添加路由 → router/routes/modules/（如果是新页面）
6. 测试验证 → 检查渲染、验证、API 调用

核心组件

1. VbenForm（Schema 驱动表单）

import { useVbenForm } from '#/adapter/form';

const [Form, formApi] = useVbenForm({
  schema: [
    { fieldName: 'username', label: '用户名', component: 'Input', rules: 'required' },
    { fieldName: 'status', label: '状态', component: 'RadioGroup' },
  ],
});

关键API: formApi.getValues() / formApi.validate() / formApi.resetForm()

完整API文档 → references/02-form.md

2. VxeGrid（带搜索的表格）

import { useVbenVxeGrid } from '#/adapter/vxe-table';

const [Grid, gridApi] = useVbenVxeGrid({
  formOptions: { schema: [...] },      // 搜索表单
  gridOptions: {
    columns: [...],                     // 列定义
    proxyConfig: { ajax: { query: async ({ page }) => { return { list, total } } } },
  },
});

关键API: gridApi.query() / gridApi.reload() / gridApi.getSelectRows()

完整API文档 → references/03-grid.md

3. VbenModal

import { useVbenModal } from '@vben/common-ui';

const [FormModal, formModalApi] = useVbenModal({
  connectedComponent: () => import('./modules/form.vue'),
  destroyOnClose: true,
});

// 使用方式
formModalApi.setData({ id: 1 }).open();  // 编辑模式
formModalApi.setData(null).open();        // 创建模式

配置

主题与布局

// apps/web-antd/src/preferences.ts
export const overridesPreferences = defineOverridesPreferences({
  theme: {
    colorPrimary: 'hsl(25 95% 54%)',  // Brand color
    mode: 'light',
    radius: '0.5',
  },
  app: {
    name: 'System Name',
    watermark: true,
    watermarkContent: 'Watermark Text',
  },
});

内置主题

API 模式

// api/module/feature.ts
import { defHttp } from '#/utils/http/axios';

export namespace FeatureApi {
  export interface Item { id?: number; name: string; status: number }
}

// 分页查询 - 必须返回 { list: [], total: 0 }
export function getFeaturePage(params: any) {
  return defHttp.get<{ list: FeatureApi.Item[]; total: number }>({ url: '/feature/page', params });
}

// CRUD 操作
export function createFeature(data: FeatureApi.Item) { /* ... */ }
export function updateFeature(data: FeatureApi.Item) { /* ... */ }
export function deleteFeature(id: number) { /* ... */ }

完整API模式示例 → references/05-page-patterns.md

常用表单组件

验证规则

import { z } from '#/adapter/form';

// 内置规则
rules: 'required'
rules: 'mobile'

// Zod 规则
rules: z.string().min(2, '至少2个字符')
rules: z.string().email('邮箱格式不正确')
rules: z.number().min(0).max(100)

UI 设计规范

设计原则

遵循 SaaS 专业克制设计风格（Linear/Notion风格），内置约束自动应用：

内置约束

线框图输入说明

当输入是 HTML+CSS 线框图时：

• 线框图的灰色样式只是结构示意
• 生成的代码使用 Vben 框架默认样式
• 框架样式自动符合上述约束
• 不需要额外调用 UI 设计 skill

与测试 Skill 协作

前端开发阶段调用测试能力确保组件质量：

前端测试规范

Vben Admin 5.x 使用 Vitest 进行组件测试：

开发流程集成测试

开发表单组件：
Step 1: 定义 schema → data.ts
Step 2: TDD 先写测试 → test-driven-development
        - 测试表单验证规则
        - 测试提交/取消事件
        - 测试 loading/error 状态
Step 3: 实现组件 → modules/form.vue
Step 4: 补充测试 → test-generation
        - 边缘情况（空值、边界值）
        - 异步操作测试

测试覆盖率标准

PRD 验收标准转化为 E2E 测试

PRD验收标准：
Given 用户在商品列表页
When 点击新增按钮
Then 打开新增表单弹窗

转化为 Playwright 测试：
test('新增商品流程', async ({ page }) => {
    // Given
    await page.goto('/product/list');
    
    // When
    await page.click('[data-testid="add-btn"]');
    
    // Then
    await expect(page.locator('.vben-modal')).toBeVisible();
});

约束总表

架构约束 (C-VBEN-ARCH)

代码规范 (C-VBEN-CODE)

组件使用 (C-VBEN-COMP)

按需加载指引

根据任务类型读取对应文档：

强制规则：实现前必须读取对应 references 文档，禁止猜测 API。

知识库

读取这些文档获取详细 API：

故障排查

输出清单

输出验证: 每个输出文件必须通过 TypeScript 类型检查，无 any 类型。

检查清单

完成工作前确认：

• Schema 已在 data.ts 中定义
• API 函数遵循规范模式
• 表格返回正确格式
• 表单验证工作正常
• 弹窗正常打开/关闭
• 路由已添加（如果是新页面）
• 权限已设置（如需要）
• 无 TypeScript 错误
• 页面正确渲染

页面模板

完整页面模板（列表页/表单页/详情页）见 references/05-page-patterns.md，包含：

• 标准文件结构（index.vue + data.ts + modules/form.vue）
• 完整代码示例
• API 集成模式

最后规则

知识库存在的意义 → 实现前先阅读
禁止猜测 API → 先查文档
遵循模式 → 一致性优于创造性

版本

• v2.4
• 更新: 2026-04-11
• 变更: 协同开发指南拆分为多个小文件，按需加载
• v2.0: YAML 页面规格输入解析、HTML 线框图解析、输入优先级、内置 UI 约束