签入版本

2026-09-12 23:12:15 +08:00
commit 91998056ca
1841 changed files with 341325 additions and 0 deletions
@@ -0,0 +1,246 @@
+# 页面视图开发
+
+<!-- Copyright (c) 2021-2026 小蚂蚁云团队 版权所有 -->
+
+:::tip 说明
+页面视图位于 `src/views/` 目录，每个业务模块遵循 `index.vue`（列表页）+ `edit.vue`（编辑弹窗）+ `detail.vue`（详情弹窗）的标准模式，辅以 `columns.ts`（列定义）和 `querySchemas.ts`（搜索表单）配置文件。
+:::
+
+## 目录结构
+
+```
+src/views/
+├── tool/
+│ ├── example/
+│ │ ├── index.vue       # 案例列表页
+│ │ ├── edit.vue        # 案例编辑弹窗
+│ │ ├── detail.vue      # 案例详情弹窗
+│ │ ├── columns.ts      # 表格列定义
+│ │ └── querySchemas.ts # 搜索表单定义
+│ └── ...
+└── ...
+```
+
+## 文件职责
+
+| 文件 | 职责 | 说明 |
+|------|------|------|
+| `index.vue` | 列表页 | 搜索表单 + 工具栏 + BasicTable + 编辑弹窗引用 |
+| `edit.vue` | 编辑弹窗 | el-dialog + el-form，懒加载 |
+| `detail.vue` | 详情弹窗 | el-dialog 展示详情，懒加载 |
+| `columns.ts` | 表格列定义 | 定义列 prop、label、render 函数等 |
+| `querySchemas.ts` | 搜索表单定义 | FormSchema 数组，定义搜索字段 |
+
+## index.vue 列表页
+
+以案例管理为例，完整结构如下：
+
+```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:example:add']">
+            添加案例
+          </el-button>
+          <el-button type="danger" @click="handleDelete()" :disabled="!selectionData.length"
+            v-perm="['sys:example:batchDelete']">
+            批量删除
+          </el-button>
+        </template>
+      </BasicTable>
+    </el-card>
+
+    <!-- 编辑对话框组件 -->
+    <editDialog v-if="editVisible" :id="currentId" v-model:visible="editVisible" @success="reloadTable('noRefresh')" />
+    <!-- 查看详情对话框组件 -->
+    <detailDialog v-if="detailVisible" :id="currentId" v-model:visible="detailVisible" @success="reloadTable('noRefresh')" />
+  </PageWrapper>
+</template>
+
+<script lang="ts" setup>
+  import { reactive, ref, h, nextTick, defineAsyncComponent } from 'vue';
+  import { schemas } from './querySchemas';
+  import { useForm } from '@/components/Form/index';
+  import { TableAction } from '@/components/Table';
+  import { getExamplePage, exampleDelete, exampleBatchDelete } from '@/api/tool/example';
+  import { columns } from './columns';
+  import { message, confirm } from '@/utils/auth';
+
+  const editDialog = defineAsyncComponent(() => import('./edit.vue'));
+  const detailDialog = defineAsyncComponent(() => import('./detail.vue'));
+
+  const currentId = ref(0);
+  const editVisible = ref(false);
+  const detailVisible = ref(false);
+  const selectionData = ref([]);
+  const tableRef = ref();
+
+  const formParams = reactive({ name: '', type: '', status: '' });
+
+  const actionColumn = reactive({
+    width: 300,
+    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:example:update'] },
+          { label: '详情', icon: 'View', type: '', onClick: handleDetail.bind(null, record), auth: ['sys:example:detail'] },
+          { label: '删除', icon: 'Delete', type: 'danger', onClick: handleDelete.bind(null, record), auth: ['sys:example:delete'] },
+        ],
+      });
+    },
+  });
+
+  const loadDataTable = async (params: any) => {
+    const result = await getExamplePage({ ...formParams, ...params });
+    return result;
+  };
+
+  function reloadTable(noRefresh = '') {
+    tableRef.value.reload(noRefresh ? {} : { pageNo: 1 });
+  }
+
+  const [register, {}] = useForm({
+    labelWidth: 80,
+    layout: 'horizontal',
+    colProps: { span: 6 },
+    submitOnReset: true,
+    schemas,
+  });
+
+  function handleSubmit(values) {
+    handleReset();
+    for (const key in values) { formParams[key] = values[key]; }
+    reloadTable();
+  }
+
+  function handleReset() {
+    for (const key in formParams) { formParams[key] = ''; }
+  }
+
+  const handleAdd = async () => { currentId.value = 0; await nextTick(); editVisible.value = true; };
+  const handleEdit = async (record) => { currentId.value = record.row.id; await nextTick(); editVisible.value = true; };
+  const handleDetail = async (record) => { currentId.value = record.row.id; await nextTick(); detailVisible.value = true; };
+
+  async function handleDelete(record) {
+    let ids = [];
+    if (!record) {
+      ids = selectionData.value.map(({ id }) => id);
+      if (!ids.length) { message('请选择要删除的数据', 'warning'); return; }
+    }
+    await confirm('确定要删除选中的案例吗？');
+    record ? await exampleDelete(record.row.id) : await exampleBatchDelete(ids);
+    message('删除成功');
+    reloadTable();
+  }
+
+  function onSelectionChange(value) { selectionData.value = value; }
+</script>
+```
+
+## columns.ts
+
+```typescript
+import { h } from 'vue';
+import { ElAvatar, ElTag } from 'element-plus';
+
+export const columns = [
+  { type: 'selection' },
+  { label: 'ID', prop: 'id', fixed: 'left', width: 50 },
+  { label: '案例名称', prop: 'name', minWidth: 120 },
+  {
+    label: '案例图片', prop: 'avatar', minWidth: 120,
+    render(record) {
+      return h(ElAvatar, { size: 48, src: record.row.avatar, shape: 'square', fit: 'fill' });
+    },
+  },
+  {
+    label: '案例类型', prop: 'type', minWidth: 100,
+    render(record) {
+      const statusMap = { 1: { text: '类型1', type: 'success' }, 2: { text: '类型2', type: 'danger' } };
+      const status = statusMap[record.row.type];
+      return h(ElTag, { type: status?.type || 'info' }, { default: () => status?.text || record.row.type });
+    },
+  },
+  {
+    label: '案例状态', prop: 'status', minWidth: 100,
+    render(record) {
+      const statusMap = { 1: { text: '正常', type: 'success' }, 2: { text: '禁用', type: 'danger' } };
+      const status = statusMap[record.row.status];
+      return h(ElTag, { type: status?.type || 'info' }, { default: () => status?.text || record.row.status });
+    },
+  },
+  { label: '排序', prop: 'sort', minWidth: 100 },
+  { label: '创建人', prop: 'createUser', minWidth: 100 },
+  { label: '创建时间', prop: 'createTime', width: 180 },
+];
+```
+
+## querySchemas.ts
+
+```typescript
+import { FormSchema } from '@/components/Form/index';
+
+export const schemas: FormSchema[] = [
+  {
+    field: 'name', component: 'Input', label: '案例名称',
+    componentProps: { placeholder: '请输入案例名称', clearable: true },
+  },
+  {
+    field: 'type', component: 'Select', label: '案例类型',
+    componentProps: {
+      placeholder: '请输入案例类型', clearable: true,
+      options: [
+        { label: '类型1', value: 1 },
+        { label: '类型2', value: 2 },
+      ],
+    },
+  },
+  {
+    field: 'status', component: 'Select', label: '案例状态',
+    componentProps: {
+      placeholder: '请输入案例状态', clearable: true,
+      options: [
+        { label: '正常', value: 1 },
+        { label: '禁用', value: 2 },
+      ],
+    },
+  },
+];
+```
+
+## 数据流
+
+```
+页面加载 → BasicForm 注册 → BasicTable request 触发 → loadDataTable → API → 渲染表格
+用户搜索 → handleSubmit → 更新 formParams → reloadTable → 重新请求
+用户新增 → handleAdd → currentId=0 → editVisible=true → edit.vue 加载 → 表单填写 → 提交
+用户编辑 → handleEdit → currentId=id → editVisible=true → edit.vue 加载详情 → 修改 → 提交
+用户删除 → confirm → API → reloadTable
+```
+
+:::tip 温馨提示
+`columns.ts` 和 `querySchemas.ts` 独立为配置文件，便于维护和复用。`columns` 中的 `render` 函数使用 Vue 的 `h()` 创建虚拟 DOM，可实现任意复杂的自定义渲染。`querySchemas` 中的 `options` 硬编码或通过字典 API 动态获取。
+:::
+
+## 总结
+
+页面视图遵循 `index.vue` + `edit.vue` + `detail.vue` + `columns.ts` + `querySchemas.ts` 标准模式。列表页使用 `BasicForm` 搜索 + `BasicTable` 展示数据 + `TableAction` 操作按钮，编辑弹窗使用 `defineAsyncComponent` 懒加载 + `useLockFn` 防重复提交。