# 前端扩展开发模式
> 基于 views/extend 示例的 Vue 3 + TypeScript 前端开发指南
> 源码分析时间:2026-04-01
---
## 一、前端目录结构
```
web/apps/jnpf-web-apps-main/src/
├── views/extend/ # 扩展示例
│ ├── barCode/ # 条形码
│ ├── importAndExport/ # 导入导出 ★
│ ├── tableDemo/ # 表格示例 ★
│ └── ...
└── api/extend/ # API 接口定义
├── employee.ts
├── table.ts
└── ...
```
---
## 二、API 接口定义
### 2.1 API 文件模板
```typescript
// #/api/extend/xxx.ts
import { defHttp } from '#/api/request';
enum Api {
Prefix = '/api/extend/Xxx', // 后端接口路径
}
// 获取列表
export function getXxxList(data) {
return defHttp.get({ url: Api.Prefix, data });
}
// 获取详情
export function getInfo(id) {
return defHttp.get({ url: `${Api.Prefix}/${id}` });
}
// 创建
export function createXxx(data) {
return defHttp.post({ url: Api.Prefix, data });
}
// 更新
export function updateXxx(data: { id }) {
return defHttp.put({ url: `${Api.Prefix}/${data.id}`, data });
}
// 删除
export function delXxx(id) {
return defHttp.delete({ url: `${Api.Prefix}/${id}` });
}
// 导出Excel
export function exportExcel(data) {
return defHttp.get({ url: `${Api.Prefix}/ExportData`, data });
}
// 导入预览
export function importPreview(data) {
return defHttp.get({ url: `${Api.Prefix}/ImportPreview`, data });
}
// 导入数据
export function importData(data) {
return defHttp.post({ url: `${Api.Prefix}/ImportData`, data });
}
```
### 2.2 HTTP 方法对应
| 操作 | 前端方法 | 后端注解 |
|------|----------|----------|
| 获取列表 | `defHttp.get({ url: Prefix, data })` | `@GetMapping` |
| 获取详情 | `defHttp.get({ url: `${Prefix}/${id}` })` | `@GetMapping("/{id}")` |
| 创建 | `defHttp.post({ url: Prefix, data })` | `@PostMapping` |
| 更新 | `defHttp.put({ url: `${Prefix}/${id}`, data })` | `@PutMapping("/{id}")` |
| 删除 | `defHttp.delete({ url: `${Prefix}/${id}` })` | `@DeleteMapping("/{id}")` |
---
## 三、Vue 组件模式
### 3.1 基础列表页面(使用 useVxeTable)
```vue
新增
```
### 3.2 搜索表单配置
```javascript
function getFormConfig(): Partial {
return {
schemas: [
{
field: 'field1',
label: '字段1',
component: 'Input',
componentProps: { placeholder: '请输入' }
},
{
field: 'field2',
label: '字段2',
component: 'Select',
componentProps: {
placeholder: '请选择',
options: [
{ id: 1, fullName: '选项1' },
{ id: 2, fullName: '选项2' }
]
}
}
]
};
}
```
### 3.3 列配置
```typescript
const columns: BasicColumn[] = [
{ title: '序号', dataIndex: 'index', width: 60, customRender: ({ index }) => index + 1 },
{ title: '编码', dataIndex: 'code', width: 150, fixed: 'left' },
{ title: '名称', dataIndex: 'name', minWidth: 150 },
{ title: '金额', dataIndex: 'amount', width: 120, format: 'money' },
{ title: '日期', dataIndex: 'date', width: 120, format: 'date|YYYY-MM-DD' },
{ title: '状态', dataIndex: 'status', width: 80, slots: { default: 'status' } },
{ title: '操作', dataIndex: 'action', width: 150, fixed: 'right' },
];
```
### 3.4 弹窗表单
```vue
```
---
## 四、useVxeTable 钩子
### 4.1 核心方法
```typescript
const [registerTable, {
reload, // 刷新数据
setColumns, // 设置列
getSelectRows, // 获取选中行
clearSelectedRowKeys, // 清空选择
getFetchParams, // 获取查询参数
}] = useVxeTable(options);
```
### 4.2 常用配置
```typescript
const options = {
api: getList, // 数据接口(必填)
columns, // 列定义(必填)
useSearchForm: true, // 是否显示搜索表单
formConfig, // 搜索表单配置
rowSelection: { type: 'checkbox' }, // 行选择
pagination: { pageSize: 20 }, // 分页配置
afterFetch: (data) => { // 数据处理钩子
return data.map(item => ({
...item,
// 处理数据
}));
},
};
```
---
## 五、主子表模式(参考 saleOrder)
```vue
```
---
## 六、导入导出模式(参考 importAndExport)
### 6.1 导出组件
```vue
```
### 6.2 导入组件
```vue
```
---
## 七、常用组件
| 组件 | 引入 | 用途 |
|------|------|------|
| `BasicVxeTable` | `@jnpf/ui/vxeTable` | 高级表格 |
| `useVxeTable` | `@jnpf/ui/vxeTable` | 表格状态管理 |
| `TableAction` | `@jnpf/ui/vxeTable` | 表格操作按钮 |
| `BasicModal` | `@jnpf/ui/modal` | 弹窗 |
| `useModal` | `@jnpf/ui/modal` | 弹窗状态管理 |
| `useMessage` | `@jnpf/hooks` | 消息提示 |
| `usePopup` | `@jnpf/ui/popup` | 弹出页面 |
| `downloadByUrl` | `@jnpf/utils` | 文件下载 |
---
## 八、关键配置
| 配置 | 说明 |
|------|------|
| API 路径前缀 | `/api/extend/Xxx` |
| 组件 name | `ExtendXxxDemo` |
| 表格列配置 | `BasicColumn[]` |
| 搜索表单 | `formConfig.schemas` |
| 操作按钮 | `getTableActions()` |