签入版本

2026-09-12 23:12:15 +08:00
commit 91998056ca
1841 changed files with 341325 additions and 0 deletions
@@ -0,0 +1,471 @@
+# 页面视图开发
+
+:::tip 说明
+页面视图位于 `src/views/` 目录，每个业务模块遵循 `index.vue`（列表页）+ `edit.vue`（编辑弹窗）的标准模式，辅以 `columns.ts`（列定义）和 `querySchemas.ts`（搜索表单）配置文件。
+:::
+
+## 目录结构
+
+```
+src/views/
+├── system/
+│ ├── position/
+│ │ ├── index.vue       # 岗位列表页
+│ │ ├── edit.vue        # 岗位编辑弹窗
+│ │ ├── columns.ts      # 表格列定义
+│ │ └── querySchemas.ts # 搜索表单定义
+│ ├── user/
+│ │ ├── index.vue
+│ │ └── edit.vue
+│ ├── role/
+│ │ ├── index.vue
+│ │ └── edit.vue
+│ └── ...
+├── cms/
+│ ├── article/
+│ └── ...
+└── ...
+```
+
+## 文件职责
+
+| 文件 | 职责 | 说明 |
+|------|------|------|
+| `index.vue` | 列表页 | 搜索表单 + 工具栏 + BasicTable + 编辑弹窗引用 |
+| `edit.vue` | 编辑弹窗 | el-dialog + el-form，懒加载 |
+| `columns.ts` | 表格列定义 | 定义列 prop、label、render 函数等 |
+| `querySchemas.ts` | 搜索表单定义 | FormSchema 数组，定义搜索字段 |
+
+## index.vue 列表页
+
+以岗位管理为例，完整结构如下：
+
+```vue
+<!-- src/views/system/position/index.vue -->
+<template>
+  <PageWrapper>
+    <el-card :bordered="false" class="pt-3 mb-3 proCard">
+      <BasicForm @register="register" @submit="handleSubmit" @reset="handleReset" />
+    </el-card>
+    <el-card :bordered="false" class="proCard">
+      <BasicTable
+        :columns="columns"
+        :request="loadDataTable"
+        :row-key="(row) => row.id"
+        ref="tableRef"
+        :actionColumn="actionColumn"
+        @selection-change="onSelectionChange"
+      >
+        <template #tableTitle>
+          <el-button type="primary" @click="handleAdd" v-perm="['sys:position:add']">
+            <template #icon>
+              <el-icon class="el-input__icon">
+                <PlusOutlined />
+              </el-icon>
+            </template>
+            添加岗位
+          </el-button>
+          <el-button
+            type="danger"
+            @click="handleDelete()"
+            :disabled="!selectionData.length"
+            v-perm="['sys:position:batchDelete']"
+          >
+            <template #icon>
+              <el-icon class="el-input__icon">
+                <Delete />
+              </el-icon>
+            </template>
+            删除
+          </el-button>
+        </template>
+      </BasicTable>
+    </el-card>
+
+    <editDialog
+      v-if="editVisible"
+      :positionId="positionId"
+      v-model:visible="editVisible"
+      @success="reloadTable('noRefresh')"
+    />
+  </PageWrapper>
+</template>
+
+<script lang="ts" setup>
+  import { reactive, ref, h, nextTick, defineAsyncComponent } from 'vue';
+  import { ColProps } from 'element-plus';
+  import { schemas } from './querySchemas';
+  import { useForm } from '@/components/Form/index';
+  import { TableAction } from '@/components/Table';
+  import { getPositionList, positionDelete, positionBatchDelete } from '@/api/system/position';
+  import { columns } from './columns';
+  import { PlusOutlined } from '@vicons/antd';
+  import { message, confirm } from '@/utils/auth';
+  const editDialog = defineAsyncComponent(() => import('./edit.vue'));
+  const positionId = ref(0);
+  const editVisible = ref(false);
+  const selectionData = ref([]);
+  const tableRef = ref();
+
+  /**
+   * 定义查询参数
+   */
+  const formParams = reactive({
+    name: '',
+    status: '',
+  });
+
+  /**
+   * 定义操作栏
+   */
+  const actionColumn = reactive({
+    width: 200,
+    label: '操作',
+    prop: 'action',
+    fixed: 'right',
+    render(record) {
+      return h(TableAction, {
+        style: 'button',
+        actions: [
+          {
+            label: '编辑',
+            icon: 'Edit',
+            type: 'warning',
+            onClick: handleEdit.bind(null, record),
+            auth: ['sys:position:update'],
+          },
+          {
+            label: '删除',
+            icon: 'Delete',
+            type: 'danger',
+            onClick: handleDelete.bind(null, record),
+            auth: ['sys:position:delete'],
+          },
+        ],
+      });
+    },
+  });
+
+  /**
+   * 加载数据列表
+   * @param res 参数
+   */
+  const loadDataTable = async (res: any) => {
+    const result = await getPositionList({ ...formParams, ...res });
+    return result;
+  };
+
+  /**
+   * 刷新数据列表
+   * @param noRefresh 参数
+   */
+  function reloadTable(noRefresh = '') {
+    tableRef.value.reload(noRefresh ? {} : { pageNo: 1 });
+  }
+
+  /**
+   * 注册
+   */
+  const [register, {}] = useForm({
+    labelWidth: 80,
+    layout: 'horizontal',
+    colProps: { span: 6 } as ColProps,
+    submitOnReset: true,
+    schemas,
+  });
+
+  /**
+   * 执行提交表单
+   */
+  function handleSubmit(values: Recordable) {
+    handleReset();
+    for (const key in values) {
+      formParams[key] = values[key];
+    }
+    reloadTable();
+  }
+
+  /**
+   * 执行重置
+   */
+  function handleReset() {
+    for (const key in formParams) {
+      formParams[key] = '';
+    }
+  }
+
+  /**
+   * 执行添加
+   */
+  const handleAdd = async () => {
+    positionId.value = 0;
+    await nextTick();
+    editVisible.value = true;
+  };
+
+  /**
+   * 执行编辑
+   * @param record 参数
+   */
+  const handleEdit = async (record: Recordable) => {
+    positionId.value = record.row.id;
+    await nextTick();
+    editVisible.value = true;
+  };
+
+  /**
+   * 执行删除
+   * @param record 参数
+   */
+  async function handleDelete(record: Recordable) {
+    let ids = [];
+    if (!record) {
+      ids = selectionData.value.map(({ id }) => id);
+    }
+    await confirm('确定要删除？');
+    record ? await positionDelete(record.row.id) : await positionBatchDelete(ids);
+    message('删除成功');
+    reloadTable();
+  }
+
+  /**
+   * 选项发生变化
+   * @param value 参数
+   */
+  function onSelectionChange(value) {
+    selectionData.value = value;
+  }
+</script>
+
+<style lang="scss" scoped></style>
+```
+
+## edit.vue 编辑弹窗
+
+```vue
+<!-- src/views/system/position/edit.vue -->
+<template>
+  <el-dialog
+    v-model="props.visible"
+    :title="props.positionId ? '编辑' : '新增'"
+    width="500"
+    :close-on-click-modal="false"
+    :before-close="dialogClose"
+  >
+    <el-form class="ls-form" ref="formRef" :model="formData" label-width="80px">
+      <el-form-item
+        label="岗位名称"
+        prop="name"
+        :rules="{ required: true, message: '请输入岗位名称', trigger: 'blur' }"
+      >
+        <el-input class="ls-input" v-model="formData.name" placeholder="请输入岗位名称" clearable />
+      </el-form-item>
+      <el-form-item label="岗位状态" prop="status">
+        <el-radio-group v-model="formData.status" name="status">
+          <el-radio :value="1">正常</el-radio>
+          <el-radio :value="2">停用</el-radio>
+        </el-radio-group>
+      </el-form-item>
+      <el-form-item label="排序" prop="sort">
+        <el-input-number v-model="formData.sort" />
+      </el-form-item>
+    </el-form>
+    <template #footer>
+      <span class="dialog-footer">
+        <el-button @click="dialogClose">取消</el-button>
+        <el-button :loading="subLoading" type="primary" @click="submit"> 确定 </el-button>
+      </span>
+    </template>
+  </el-dialog>
+</template>
+<script lang="ts" setup>
+  import type { FormInstance } from 'element-plus';
+  import { getPositionDetail, positionAdd, positionUpdate } from '@/api/system/position';
+  import { onMounted, reactive, shallowRef } from 'vue';
+  import { message } from '@/utils/auth';
+  import { useLockFn } from '@/utils/useLockFn';
+
+  const emit = defineEmits(['success', 'update:visible']);
+  const formRef = shallowRef<FormInstance>();
+
+  /**
+   * 定义表单参数
+   */
+  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 handleSubmit = async () => {
+    await formRef.value?.validate();
+    props.positionId ? await positionUpdate(formData) : await positionAdd(formData);
+    message('操作成功');
+    emit('update:visible', false);
+    emit('success');
+  };
+
+  /**
+   * 关闭窗体
+   */
+  const dialogClose = () => {
+    emit('update:visible', false);
+  };
+
+  const { isLock: subLoading, lockFn: submit } = useLockFn(handleSubmit);
+
+  /**
+   * 设置表单数据
+   */
+  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();
+    }
+  });
+</script>
+
+</script>
+```
+
+## 数据流
+
+```
+页面加载 → BasicForm 注册 → BasicTable request 触发 → loadDataTable → API → 渲染表格
+用户搜索 → handleSubmit → 更新 formParams → reloadTable → 重新请求
+用户新增 → handleAdd → positionId=0 → editVisible=true → edit.vue 加载 → 表单填写 → 提交
+用户编辑 → handleEdit → positionId=id → editVisible=true → edit.vue 加载详情 → 修改 → 提交
+用户删除 → confirm → API → reloadTable
+```
+
+## columns.ts
+
+```typescript
+// src/views/system/position/columns.ts
+import { h } from 'vue';
+import { ElTag } from 'element-plus';
+
+export const columns = [
+  {
+    type: 'selection',
+  },
+  {
+    label: 'ID',
+    prop: 'id',
+    fixed: 'left',
+    width: 50,
+  },
+  {
+    label: '岗位名称',
+    prop: 'name',
+    minWidth: 100,
+  },
+  {
+    label: '岗位状态',
+    prop: 'status',
+    minWidth: 100,
+    render(record) {
+      return h(
+        ElTag,
+        {
+          type: record.row.status == 1 ? 'success' : 'danger',
+        },
+        {
+          default: () => (record.row.status == 1 ? '正常' : '停用'),
+        },
+      );
+    },
+  },
+  {
+    label: '排序',
+    prop: 'sort',
+    minWidth: 100,
+  },
+  {
+    label: '创建人',
+    prop: 'createUser',
+    minWidth: 100,
+  },
+  {
+    label: '创建时间',
+    prop: 'createTime',
+    width: 180,
+  },
+];
+```
+
+## querySchemas.ts
+
+```typescript
+// src/views/system/position/querySchemas.ts
+import { FormSchema } from '@/components/Form/index';
+export const schemas: FormSchema[] = [
+  {
+    field: 'name',
+    component: 'Input',
+    label: '岗位名称',
+    componentProps: {
+      placeholder: '请输入岗位名称',
+    },
+  },
+  {
+    field: 'status',
+    component: 'Select',
+    label: '状态',
+    componentProps: {
+      placeholder: '请选择状态',
+      clearable: true,
+      options: [
+        {
+          label: '正常',
+          value: '1',
+        },
+        {
+          label: '禁用',
+          value: '2',
+        },
+      ],
+    },
+  },
+];
+```
+
+:::tip 温馨提示
+`columns.ts` 和 `querySchemas.ts` 独立为配置文件，便于维护和复用。`columns` 中的 `render` 函数使用 Vue 的 `h()` 创建虚拟 DOM，可实现任意复杂的自定义渲染。`querySchemas` 中的 `options` 硬编码或通过字典 API 动态获取。
+:::
+
+## 总结
+
+页面视图遵循 `index.vue` + `edit.vue` + `columns.ts` + `querySchemas.ts` 标准模式。列表页使用 `BasicForm` 搜索 + `BasicTable` 展示数据 + `TableAction` 操作按钮，编辑弹窗使用 `defineAsyncComponent` 懒加载 + `useLockFn` 防重复提交。数据流清晰：搜索更新参数 → 刷新表格，操作成功 → emit 事件 → 刷新表格。