9.3 KiB
9.3 KiB
前端扩展开发模式
基于 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 文件模板
// #/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)
<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 搜索表单配置
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 列配置
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 弹窗表单
<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 核心方法
const [registerTable, {
reload, // 刷新数据
setColumns, // 设置列
getSelectRows, // 获取选中行
clearSelectedRowKeys, // 清空选择
getFetchParams, // 获取查询参数
}] = useVxeTable(options);
4.2 常用配置
const options = {
api: getList, // 数据接口(必填)
columns, // 列定义(必填)
useSearchForm: true, // 是否显示搜索表单
formConfig, // 搜索表单配置
rowSelection: { type: 'checkbox' }, // 行选择
pagination: { pageSize: 20 }, // 分页配置
afterFetch: (data) => { // 数据处理钩子
return data.map(item => ({
...item,
// 处理数据
}));
},
};
五、主子表模式(参考 saleOrder)
<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 导出组件
<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 导入组件
<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() |