feat: initial commit
This commit is contained in:
commit
539b115e38
232 files changed
+31223
No files matched your search
@@ -0,0 +1,395 @@
|
||||
# 前端扩展开发模式
|
||||
|
||||
> 基于 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()` |
|
||||
Reference in new issue
Block a user