396 lines
9.3 KiB
Markdown
396 lines
9.3 KiB
Markdown
# 前端扩展开发模式
|
||
|
||
> 基于 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
|
||
<script lang="ts" setup>
|
||
import type { BasicColumn } from '@jnpf/ui/vxeTable';
|
||
import { useMessage } from '@jnpf/hooks';
|
||
import { BasicVxeTable, useVxeTable } from '@jnpf/ui/vxeTable';
|
||
import { getXxxList, delXxx } from '#/api/extend/xxx';
|
||
|
||
defineOptions({ name: 'ExtendXxxDemo' });
|
||
|
||
const { createMessage, createConfirm } = useMessage();
|
||
|
||
// 列表列定义
|
||
const columns: BasicColumn[] = [
|
||
{ title: '字段1', dataIndex: 'field1', width: 120 },
|
||
{ title: '字段2', dataIndex: 'field2', width: 120 },
|
||
{ title: '创建时间', dataIndex: 'creatorTime', width: 150, format: 'date|YYYY-MM-DD' },
|
||
];
|
||
|
||
// 使用 useVxeTable
|
||
const [registerTable, { reload, getSelectRows }] = useVxeTable({
|
||
api: getXxxList, // 数据接口
|
||
columns, // 列定义
|
||
useSearchForm: true, // 启用搜索表单
|
||
formConfig: { // 搜索表单配置
|
||
schemas: [
|
||
{
|
||
field: 'keyword',
|
||
label: '关键词',
|
||
component: 'Input',
|
||
componentProps: { placeholder: '请输入' }
|
||
}
|
||
]
|
||
},
|
||
rowSelection: { type: 'checkbox' }, // 多选
|
||
});
|
||
|
||
// 操作按钮
|
||
function getTableActions(record): ActionItem[] {
|
||
return [
|
||
{ label: '编辑', onClick: handleEdit.bind(null, record) },
|
||
{ label: '删除', color: 'error', modelConfirm: { onOk: handleDel.bind(null, record.id) } }
|
||
];
|
||
}
|
||
|
||
// 编辑
|
||
function handleEdit(record) {
|
||
// 打开编辑弹窗
|
||
}
|
||
|
||
// 删除
|
||
function handleDel(id) {
|
||
delXxx(id).then(res => {
|
||
createMessage.success(res.msg);
|
||
reload();
|
||
});
|
||
}
|
||
</script>
|
||
|
||
<template>
|
||
<BasicVxeTable @register="registerTable">
|
||
<template #tableTitle>
|
||
<a-button type="primary" @click="handleAdd">新增</a-button>
|
||
</template>
|
||
<template #action="{ record }">
|
||
<TableAction :actions="getTableActions(record)" />
|
||
</template>
|
||
</BasicVxeTable>
|
||
</template>
|
||
```
|
||
|
||
### 3.2 搜索表单配置
|
||
|
||
```javascript
|
||
function getFormConfig(): Partial<FormProps> {
|
||
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
|
||
<script lang="ts" setup>
|
||
import { useModal } from '@jnpf/ui/modal';
|
||
import { BasicModal } from '@jnpf/ui/modal';
|
||
|
||
const [registerModal, { openModal, closeModal }] = useModal();
|
||
|
||
// 打开弹窗
|
||
function handleAdd() {
|
||
openModal(true, { id: null });
|
||
}
|
||
|
||
// 提交
|
||
function handleSubmit() {
|
||
const data = { /* 表单数据 */ };
|
||
createXxx(data).then(res => {
|
||
createMessage.success(res.msg);
|
||
closeModal();
|
||
emit('reload');
|
||
});
|
||
}
|
||
</script>
|
||
|
||
<template>
|
||
<BasicModal @register="registerModal" title="标题" @ok="handleSubmit">
|
||
<!-- 表单内容 -->
|
||
</BasicModal>
|
||
</template>
|
||
```
|
||
|
||
---
|
||
|
||
## 四、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
|
||
<script lang="ts" setup>
|
||
// 主表
|
||
const [registerTable, { reload, getSelectRows }] = useVxeTable({
|
||
api: getOrderList,
|
||
columns: mainColumns,
|
||
rowClick: ({ record }) => {
|
||
// 点击主表行加载子表数据
|
||
state.activeId = record.id;
|
||
getProductEntry(record.id).then(res => {
|
||
state.productList = res.data.list;
|
||
});
|
||
}
|
||
});
|
||
|
||
// 子表
|
||
const [registerProductTable] = useVxeTable({
|
||
columns: productColumns,
|
||
useSearchForm: false,
|
||
pagination: false,
|
||
});
|
||
</script>
|
||
|
||
<template>
|
||
<div class="h-full">
|
||
<!-- 主表 -->
|
||
<BasicVxeTable @register="registerTable" />
|
||
<!-- 子表 -->
|
||
<div class="footer">
|
||
<BasicVxeTable @register="registerProductTable" :data-source="productList" />
|
||
</div>
|
||
</div>
|
||
</template>
|
||
```
|
||
|
||
---
|
||
|
||
## 六、导入导出模式(参考 importAndExport)
|
||
|
||
### 6.1 导出组件
|
||
|
||
```vue
|
||
<script lang="ts" setup>
|
||
import { useModal } from '@jnpf/ui/modal';
|
||
import { exportExcel } from '#/api/extend/xxx';
|
||
import { downloadByUrl } from '@jnpf/utils';
|
||
|
||
const [registerModal, { openModal }] = useModal();
|
||
|
||
function handleExport() {
|
||
openModal(true, { listQuery: getFetchParams() });
|
||
}
|
||
|
||
function handleSubmit() {
|
||
const query = {
|
||
...listQuery.value,
|
||
selectKey: checkedList.value.join(','),
|
||
};
|
||
exportExcel(query).then(res => {
|
||
downloadByUrl({ url: res.data.url });
|
||
closeModal();
|
||
});
|
||
}
|
||
</script>
|
||
```
|
||
|
||
### 6.2 导入组件
|
||
|
||
```vue
|
||
<script lang="ts" setup>
|
||
import { importData, importPreview } from '#/api/extend/xxx';
|
||
|
||
function handleFileChange({ file }) {
|
||
if (file.response?.code === 200) {
|
||
state.fileName = file.response.data.name;
|
||
}
|
||
}
|
||
|
||
function handlePreview() {
|
||
importPreview({ fileName: state.fileName }).then(res => {
|
||
state.list = res.data.dataRow || [];
|
||
});
|
||
}
|
||
|
||
function handleImport() {
|
||
importData({ list: state.list }).then(res => {
|
||
// 处理结果
|
||
});
|
||
}
|
||
</script>
|
||
```
|
||
|
||
---
|
||
|
||
## 七、常用组件
|
||
|
||
| 组件 | 引入 | 用途 |
|
||
|------|------|------|
|
||
| `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()` |
|