Files
aibridge/docs/codedev/02-frontend-pattern.md
T
2026-05-18 09:28:15 +08:00

396 lines
9.3 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 前端扩展开发模式
> 基于 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()` |