594 lines
16 KiB
Markdown
594 lines
16 KiB
Markdown
# 前端页面视图
|
||
|
||
前端页面视图是用户直接交互的界面。项目使用 Vue3 + NaiveUI + Vite 构建。一个完整的 CRUD 页面由 4 个文件组成：
|
||
|
||
```
|
||
ui/src/views/system/position/
|
||
├── index.vue # 主页面：搜索 + 表格 + 操作
|
||
├── edit.vue # 编辑弹窗：新增/编辑表单
|
||
├── columns.ts # 表格列定义
|
||
└── querySchemas.ts # 搜索表单 Schema
|
||
```
|
||
|
||
## 1. 主页面 `index.vue`
|
||
|
||
主页面是模块的入口页面，包含搜索表单、数据表格和操作按钮。
|
||
|
||
### 完整代码
|
||
|
||
```vue
|
||
<template>
|
||
<div>
|
||
<n-card :bordered="false" class="pt-3 mb-3 proCard">
|
||
<BasicForm @register="register" @submit="handleSubmit" @reset="handleReset">
|
||
<template #statusSlot="{ model, field }">
|
||
<n-input v-model:value="model[field]" />
|
||
</template>
|
||
</BasicForm>
|
||
</n-card>
|
||
<n-card :bordered="false" class="proCard">
|
||
<BasicTable
|
||
:columns="columns"
|
||
:request="loadDataTable"
|
||
:row-key="(row) => row.id"
|
||
ref="basicTableRef"
|
||
:actionColumn="actionColumn"
|
||
@update:checked-row-keys="onCheckedRow"
|
||
:autoScrollX="true"
|
||
>
|
||
<template #tableTitle>
|
||
<n-space>
|
||
<n-button type="primary" @click="handleAdd" v-perm="['sys:position:add']">
|
||
<template #icon>
|
||
<n-icon>
|
||
<PlusOutlined />
|
||
</n-icon>
|
||
</template>
|
||
新建
|
||
</n-button>
|
||
<n-button
|
||
type="error"
|
||
@click="handleDelete"
|
||
:disabled="!rowKeys.length"
|
||
v-perm="['sys:position:batchDelete']"
|
||
>
|
||
<template #icon>
|
||
<n-icon>
|
||
<DeleteOutlined />
|
||
</n-icon>
|
||
</template>
|
||
删除
|
||
</n-button>
|
||
</n-space>
|
||
</template>
|
||
</BasicTable>
|
||
</n-card>
|
||
<editDialog
|
||
ref="createModalRef"
|
||
:positionId="positionId"
|
||
v-if="editVisible"
|
||
v-model:visible="editVisible"
|
||
@success="reloadTable('noRefresh')"
|
||
/>
|
||
</div>
|
||
</template>
|
||
|
||
<script lang="ts" setup>
|
||
import { h, nextTick, reactive, ref, unref } from 'vue';
|
||
import { useMessage, useDialog } from 'naive-ui';
|
||
import { TableAction } from '@/components/Table';
|
||
import { BasicForm, useForm } from '@/components/Form/index';
|
||
import { getPositionList, positionDelete, positionBatchDelete } from '@/api/system/position';
|
||
import { columns } from './columns';
|
||
import { PlusOutlined, DeleteOutlined, FormOutlined } from '@vicons/antd';
|
||
import editDialog from './edit.vue';
|
||
import { schemas } from './querySchemas';
|
||
import { renderIcon } from '@/utils';
|
||
|
||
/**
|
||
* 定义参数
|
||
*/
|
||
const message = useMessage();
|
||
const dialog = useDialog();
|
||
const basicTableRef = ref();
|
||
const createModalRef = ref();
|
||
const editVisible = ref(false);
|
||
const positionId = ref(0);
|
||
const rowKeys = ref([]);
|
||
|
||
/**
|
||
* 定义查询参数
|
||
*/
|
||
const formParams = reactive({
|
||
name: '',
|
||
status: '',
|
||
});
|
||
|
||
/**
|
||
* 定义操作栏
|
||
*/
|
||
const actionColumn = reactive({
|
||
width: 200,
|
||
title: '操作',
|
||
align: 'center',
|
||
key: 'action',
|
||
fixed: 'right',
|
||
render(record) {
|
||
return h(TableAction as any, {
|
||
style: 'button',
|
||
actions: [
|
||
{
|
||
label: '编辑',
|
||
icon: renderIcon(FormOutlined),
|
||
type: 'info',
|
||
onClick: handleEdit.bind(null, record),
|
||
auth: ['sys:position:update'],
|
||
},
|
||
{
|
||
label: '删除',
|
||
icon: renderIcon(DeleteOutlined),
|
||
type: 'error',
|
||
onClick: handleDelete.bind(null, record),
|
||
auth: ['sys:position:delete'],
|
||
},
|
||
],
|
||
});
|
||
},
|
||
});
|
||
|
||
/**
|
||
* 加载数据列表
|
||
* @param res 参数
|
||
*/
|
||
const loadDataTable = async (res) => {
|
||
rowKeys.value = [];
|
||
const result = await getPositionList({ ...formParams, ...res });
|
||
return result;
|
||
};
|
||
|
||
/**
|
||
* 数据行选择事件
|
||
* @param keys 参数
|
||
*/
|
||
function onCheckedRow(keys) {
|
||
rowKeys.value = keys;
|
||
}
|
||
|
||
/**
|
||
* 加载数据列表
|
||
* @param noRefresh 参数
|
||
*/
|
||
function reloadTable(noRefresh = '') {
|
||
basicTableRef.value.reload(noRefresh ? {} : { pageNo: 1 });
|
||
}
|
||
|
||
/**
|
||
* 执行提交表单
|
||
* @param values 参数
|
||
*/
|
||
function handleSubmit(values: Recordable) {
|
||
for (const key in formParams) {
|
||
formParams[key] = '';
|
||
}
|
||
for (const key in values) {
|
||
formParams[key] = values[key];
|
||
}
|
||
reloadTable();
|
||
}
|
||
|
||
/**
|
||
* 执行重置
|
||
* @param values 参数
|
||
*/
|
||
function handleReset(values: Recordable) {
|
||
for (const key in formParams) {
|
||
formParams[key] = '';
|
||
}
|
||
for (const key in values) {
|
||
formParams[key] = values[key];
|
||
}
|
||
reloadTable();
|
||
}
|
||
|
||
/**
|
||
* 执行注册
|
||
*/
|
||
const [register, {}] = useForm({
|
||
gridProps: { cols: '1 s:1 m:2 l:3 xl:4 2xl:4' },
|
||
labelWidth: 80,
|
||
schemas,
|
||
});
|
||
|
||
/**
|
||
* 执行添加
|
||
*/
|
||
const handleAdd = async () => {
|
||
positionId.value = 0;
|
||
editVisible.value = true;
|
||
await nextTick();
|
||
createModalRef.value.openModal();
|
||
};
|
||
|
||
/**
|
||
* 执行编辑
|
||
*/
|
||
async function handleEdit(record: Recordable) {
|
||
positionId.value = record.id;
|
||
editVisible.value = true;
|
||
await nextTick();
|
||
createModalRef.value.openModal();
|
||
}
|
||
|
||
/**
|
||
* 执行删除
|
||
* @param id 参数
|
||
*/
|
||
async function handleDelete(record) {
|
||
dialog.warning({
|
||
title: '提示',
|
||
content: '确定要删除？',
|
||
positiveText: '确定',
|
||
negativeText: '取消',
|
||
onPositiveClick: async () => {
|
||
record.id ? await positionDelete(record.id) : await positionBatchDelete(rowKeys.value);
|
||
message.success('删除成功');
|
||
reloadTable();
|
||
},
|
||
});
|
||
}
|
||
</script>
|
||
```
|
||
|
||
### 代码解析
|
||
|
||
**页面结构**：`div` 包裹两个 `n-card`，上方是搜索表单，下方是数据表格。
|
||
|
||
**搜索表单**：通过 `useForm` 注册，Schema 从 `querySchemas.ts` 导入。`gridProps` 控制响应式列数。
|
||
|
||
**数据表格**：通过 `BasicTable` 组件渲染，`request` 属性绑定数据加载函数，`columns` 从 `columns.ts` 导入。
|
||
|
||
**操作栏**：通过 `actionColumn` 的 `render` 函数使用 `h()` 渲染 `TableAction`，支持权限控制（`auth`）。图标通过 `renderIcon` 工具函数包装。
|
||
|
||
**编辑弹窗**：使用 `editDialog` 组件，通过 `v-model:visible` 控制显示，`positionId` 传入编辑记录 ID（0 表示新增）。通过 `ref` 调用 `openModal()` 打开弹窗。
|
||
|
||
**删除逻辑**：使用 NaiveUI 的 `useDialog` 弹出确认对话框，单条删除传入 `record`，批量删除从 `rowKeys` 取已选 ID。
|
||
|
||
**消息提示**：使用 NaiveUI 的 `useMessage` 组件，调用 `message.success()` 显示成功提示。
|
||
|
||
## 2. 编辑弹窗 `edit.vue`
|
||
|
||
编辑弹窗是独立组件，负责新增和编辑操作的表单展示与提交。
|
||
|
||
### 完整代码
|
||
|
||
```vue
|
||
<template>
|
||
<basicModal
|
||
@register="modalRegister"
|
||
ref="modalRef"
|
||
class="basicModal basicFormModal"
|
||
@on-ok="handleSubmit"
|
||
@on-close="handleClose"
|
||
>
|
||
<template #default>
|
||
<n-form
|
||
class="ls-form"
|
||
ref="formRef"
|
||
:model="formData"
|
||
label-placement="left"
|
||
label-width="85px"
|
||
>
|
||
<n-form-item
|
||
label="岗位名称"
|
||
path="name"
|
||
:rule="{ required: true, message: '请输入岗位名称', trigger: 'blur' }"
|
||
>
|
||
<n-input v-model:value="formData.name" placeholder="请输入岗位名称" clearable />
|
||
</n-form-item>
|
||
<n-form-item label="岗位状态" path="code">
|
||
<n-radio-group v-model:value="formData.status" name="status">
|
||
<n-radio :value="1">正常</n-radio>
|
||
<n-radio :value="2">停用</n-radio>
|
||
</n-radio-group>
|
||
</n-form-item>
|
||
<n-form-item label="排序" path="sort">
|
||
<n-input-number v-model:value="formData.sort" />
|
||
</n-form-item>
|
||
</n-form>
|
||
</template>
|
||
</basicModal>
|
||
</template>
|
||
<script lang="ts" setup>
|
||
import { getPositionDetail, positionAdd, positionUpdate } from '@/api/system/position';
|
||
import { onMounted, reactive, ref } from 'vue';
|
||
import { useMessage } from 'naive-ui';
|
||
import { useModal } from '@/components/Modal';
|
||
|
||
/**
|
||
* 定义参数
|
||
*/
|
||
const emit = defineEmits(['success', 'update:visible']);
|
||
const formRef = ref();
|
||
|
||
/**
|
||
* 定义表单参数
|
||
*/
|
||
const message = useMessage();
|
||
const formData = reactive({
|
||
id: '',
|
||
name: '',
|
||
status: 1,
|
||
sort: 0,
|
||
});
|
||
|
||
/**
|
||
* 定义接收的参数
|
||
*/
|
||
const props = defineProps({
|
||
visible: {
|
||
type: Boolean,
|
||
required: true,
|
||
default: false,
|
||
},
|
||
positionId: {
|
||
type: Number,
|
||
required: true,
|
||
default: 0,
|
||
},
|
||
});
|
||
|
||
/**
|
||
* 定义模态
|
||
*/
|
||
const [modalRegister, { openModal, setSubLoading }] = useModal({
|
||
title: props.positionId ? '编辑岗位' : '添加岗位',
|
||
subBtuText: '确定',
|
||
width: 600,
|
||
});
|
||
|
||
/**
|
||
* 执行提交
|
||
*/
|
||
const handleSubmit = async () => {
|
||
formRef.value
|
||
.validate()
|
||
.then(async () => {
|
||
props.positionId ? await positionUpdate(formData) : await positionAdd(formData);
|
||
message.success('操作成功');
|
||
setSubLoading(false);
|
||
emit('update:visible', false);
|
||
emit('success');
|
||
})
|
||
.catch((error) => {
|
||
setSubLoading(false);
|
||
});
|
||
};
|
||
|
||
/**
|
||
* 关闭窗体
|
||
*/
|
||
const handleClose = () => {
|
||
emit('update:visible', false);
|
||
};
|
||
|
||
/**
|
||
* 设置表单数据
|
||
*/
|
||
const setFormData = async () => {
|
||
const data = await getPositionDetail(props.positionId);
|
||
for (const key in formData) {
|
||
if (data[key] != null && data[key] != undefined) {
|
||
//@ts-ignore
|
||
formData[key] = data[key];
|
||
}
|
||
}
|
||
};
|
||
|
||
/**
|
||
* 钩子函数
|
||
*/
|
||
onMounted(() => {
|
||
if (props.positionId) {
|
||
setFormData();
|
||
}
|
||
});
|
||
|
||
/**
|
||
* 定义函数
|
||
*/
|
||
defineExpose({
|
||
openModal,
|
||
});
|
||
</script>
|
||
```
|
||
|
||
### 代码解析
|
||
|
||
**弹窗组件**：使用项目封装的 `basicModal` 组件，通过 `useModal` hook 管理弹窗状态。
|
||
|
||
**Props 接收**：
|
||
- `visible`：控制弹窗显示/隐藏，通过 `v-model:visible` 双向绑定
|
||
- `positionId`：编辑记录的 ID，为 0 时表示新增模式
|
||
|
||
**表单组件**：使用 NaiveUI 的 `n-form`、`n-form-item`、`n-input`、`n-radio-group`、`n-radio`、`n-input-number` 组件。
|
||
|
||
**表单配置**：
|
||
- `label-placement="left"`：标签在左侧显示
|
||
- `label-width="85px"`：标签宽度
|
||
- `path`：表单字段路径，用于校验
|
||
- `:rule`：校验规则
|
||
|
||
**新增/编辑判断**：`props.positionId ? positionUpdate : positionAdd`，通过 ID 是否为 0 区分。
|
||
|
||
**防重复提交**：`useModal` 的 `setSubLoading` 方法控制提交按钮 loading 状态。
|
||
|
||
**数据回填**：`onMounted` 时判断如果是编辑模式，调用 `getPositionDetail` 获取数据并填充表单。
|
||
|
||
**事件通信**：
|
||
- `emit('update:visible', false)`：关闭弹窗
|
||
- `emit('success')`：通知父页面刷新表格
|
||
|
||
**弹窗调用方式**：父页面通过 `ref` 调用 `openModal()` 打开弹窗。
|
||
|
||
## 3. 表格列定义 `columns.ts`
|
||
|
||
定义表格的列配置，包括列名、字段名、宽度和自定义渲染。
|
||
|
||
### 完整代码
|
||
|
||
```typescript
|
||
import { h } from 'vue';
|
||
import { NTag } from 'naive-ui';
|
||
|
||
export const columns = [
|
||
{
|
||
type: 'selection',
|
||
width: 50,
|
||
fixed: 'left',
|
||
},
|
||
{
|
||
title: 'ID',
|
||
key: 'id',
|
||
fixed: 'left',
|
||
width: 50,
|
||
},
|
||
{
|
||
title: '岗位名称',
|
||
key: 'name',
|
||
width: 100,
|
||
},
|
||
{
|
||
title: '岗位状态',
|
||
key: 'status',
|
||
width: 100,
|
||
render(record) {
|
||
return h(
|
||
NTag,
|
||
{
|
||
style: {
|
||
marginRight: '6px',
|
||
},
|
||
bordered: false,
|
||
type: record.status == 1 ? 'success' : 'error',
|
||
},
|
||
{
|
||
default: () => (record.status == 1 ? '正常' : '停用'),
|
||
},
|
||
);
|
||
},
|
||
},
|
||
{
|
||
title: '排序',
|
||
key: 'sort',
|
||
width: 100,
|
||
},
|
||
{
|
||
title: '创建人',
|
||
key: 'createUser',
|
||
width: 100,
|
||
},
|
||
{
|
||
title: '创建时间',
|
||
key: 'createTime',
|
||
width: 180,
|
||
},
|
||
];
|
||
```
|
||
|
||
### 代码解析
|
||
|
||
**列配置字段**：NaiveUI 表格使用 `title`（列标题）和 `key`（字段名）。
|
||
|
||
**选择列**：`type: 'selection'` 自动添加复选框列，配合 `@update:checked-row-keys` 事件实现批量选择。
|
||
|
||
**固定列**：`fixed: 'left'` 固定在左侧，`fixed: 'right'` 固定在右侧（操作列）。
|
||
|
||
**自定义渲染**：`render(record)` 使用 Vue 的 `h()` 函数创建虚拟 DOM。注意 NaiveUI 的 `render` 回调直接接收 `record` 对象，无需通过 `record.row` 访问。
|
||
|
||
**标签组件**：使用 NaiveUI 的 `NTag` 组件，`type` 属性支持 `'success'`、`'error'`、`'warning'`、`'info'` 等类型。`bordered: false` 去除边框。
|
||
|
||
**宽度设置**：
|
||
- `width`：固定宽度
|
||
|
||
## 4. 搜索表单 `querySchemas.ts`
|
||
|
||
定义搜索表单的字段配置，使用项目封装的 `FormSchema` 类型。
|
||
|
||
### 完整代码
|
||
|
||
```typescript
|
||
import { FormSchema } from '@/components/Form/index';
|
||
export const schemas: FormSchema[] = [
|
||
{
|
||
field: 'name',
|
||
component: 'NInput',
|
||
label: '岗位名称',
|
||
componentProps: {
|
||
placeholder: '请输入岗位名称',
|
||
},
|
||
},
|
||
{
|
||
field: 'status',
|
||
component: 'NSelect',
|
||
label: '状态',
|
||
componentProps: {
|
||
placeholder: '请选择状态',
|
||
clearable: true,
|
||
options: [
|
||
{
|
||
label: '正常',
|
||
value: '1',
|
||
},
|
||
{
|
||
label: '停用',
|
||
value: '2',
|
||
},
|
||
],
|
||
},
|
||
},
|
||
];
|
||
```
|
||
|
||
### 代码解析
|
||
|
||
**FormSchema 字段**：
|
||
|
||
| 字段 | 说明 |
|
||
|:----|:----|
|
||
| `field` | 字段名，与后端查询参数对应 |
|
||
| `component` | 表单组件类型：`NInput` / `NSelect` / `NDatePicker` 等（NaiveUI 组件名） |
|
||
| `label` | 标签文本 |
|
||
| `componentProps` | 组件属性，透传给 NaiveUI 组件 |
|
||
|
||
**Select 组件**：`options` 定义下拉选项，`clearable: true` 允许清空选择。
|
||
|
||
## 文件关系图
|
||
|
||
```
|
||
index.vue（主页面）
|
||
├── import schemas from './querySchemas' ← 搜索表单配置
|
||
├── import columns from './columns' ← 表格列配置
|
||
├── import editDialog from './edit.vue' ← 编辑弹窗组件
|
||
└── import API from '@/api/system/position' ← 接口请求
|
||
|
||
edit.vue（编辑弹窗）
|
||
└── import API from '@/api/system/position' ← 接口请求
|
||
```
|
||
|
||
## 开发要点
|
||
|
||
1. **一个模块一个目录**：放在 `ui/src/views/{group}/{module}/` 下
|
||
2. **4 个文件各司其职**：主页面、编辑弹窗、列定义、搜索 Schema
|
||
3. **编辑弹窗是独立组件**：通过 Props 接收 ID，通过 Emit 通知父页面，通过 `useModal` 管理弹窗状态
|
||
4. **列定义使用 `h()` 渲染复杂内容**：如状态标签、操作按钮
|
||
5. **搜索 Schema 使用 `FormSchema` 类型**：配置化定义表单字段，组件名使用 NaiveUI 组件名（`NInput`、`NSelect`）
|
||
6. **新增/编辑通过 `positionId` 区分**：0 为新增，非 0 为编辑
|
||
7. **消息提示使用 `useMessage()`**：调用 `message.success()` / `message.error()` 等
|
||
8. **确认对话框使用 `useDialog()`**：调用 `dialog.warning()` 等，通过 `onPositiveClick` 回调处理确认
|
||
9. **表格行选择使用 `@update:checked-row-keys`**：获取选中行的 key 数组
|
||
10. **列配置使用 `title` 和 `key`**：定义表格列标题和字段名
|
||
|
||
## 总结
|
||
|
||
前端页面统一使用 `n-card` + `BasicForm` + `BasicTable` + `TableAction` 组件组合，分页由 `BasicTable` 内置处理。每个模块包含 `index.vue`（列表页）、`edit.vue`（编辑弹窗）、`columns.ts`（列定义）、`querySchemas.ts`（搜索配置）四个文件。编辑弹窗使用项目封装的 `basicModal` 组件，通过 `useModal` hook 管理弹窗状态和提交按钮 loading。
|