优化更新

DjangoAdmin_Django_AntdVue/zh/volume2/fe-view.md

@@ -1,6 +1,6 @@
 # 前端页面视图
 
-前端页面视图是用户直接交互的界面。项目使用 Vue3 + ElementPlus + Vite 构建。一个完整的 CRUD 页面由 5 个文件组成：
+前端页面视图是用户直接交互的界面。项目使用 Vue3 + Ant Design Vue + Vite 构建。一个完整的 CRUD 页面由 5 个文件组成：
 
 ```
 ui/src/views/tool/example/
@@ -21,30 +21,52 @@ ui/src/views/tool/example/
 <template>
   <PageWrapper>
     <!-- 搜索表单卡片 -->
-    <el-card :bordered="false" class="pt-3 mb-3 proCard">
+    <a-card :bordered="false" class="pt-3 mb-3 proCard">
       <BasicForm @register="register" @submit="handleSubmit" @reset="handleReset" />
-    </el-card>
+    </a-card>
 
     <!-- 数据表格卡片 -->
-    <el-card :bordered="false" class="proCard">
+    <a-card :bordered="false" class="proCard">
       <BasicTable
         :columns="columns"
         :request="loadDataTable"
         :row-key="(row) => row.id"
         ref="tableRef"
-        :actionColumn="actionColumn"
-        @selection-change="onSelectionChange"
+        :row-selection="{ onChange: onSelectionChange }"
+        scroll-x="1200"
       >
         <template #tableTitle>
-          <el-button type="primary" @click="handleAdd" v-perm="['sys:example:add']">
-            添加案例
-          </el-button>
-          <el-button type="danger" @click="handleDelete()" :disabled="!selectionData.length">
-            批量删除
-          </el-button>
+          <a-space>
+            <a-button type="primary" @click="handleAdd" v-perm="['sys:example:add']">
+              <template #icon><PlusOutlined /></template>
+              添加案例
+            </a-button>
+            <a-button type="danger" @click="handleDelete()" :disabled="!selectionData.length" v-perm="['sys:example:batchDelete']">
+              <template #icon><DeleteOutlined /></template>
+              批量删除
+            </a-button>
+          </a-space>
+        </template>
+        <template #bodyCell="{ column, record }">
+          <template v-if="column.key === 'action'">
+            <a-space>
+              <a-button type="primary" @click="handleEdit(record)" v-perm="['sys:example:update']">
+                <template #icon><EditOutlined /></template>
+                编辑
+              </a-button>
+              <a-button type="primary" @click="handleDetail(record)" v-perm="['sys:example:detail']">
+                <template #icon><EyeOutlined /></template>
+                详情
+              </a-button>
+              <a-button type="primary" danger @click="handleDelete(record)" v-perm="['sys:example:delete']">
+                <template #icon><DeleteOutlined /></template>
+                删除
+              </a-button>
+            </a-space>
+          </template>
         </template>
       </BasicTable>
-    </el-card>
+    </a-card>
 
     <!-- 编辑对话框 -->
     <editDialog v-if="editVisible" :id="currentId" v-model:visible="editVisible" @success="reloadTable('noRefresh')" />
@@ -58,12 +80,13 @@ ui/src/views/tool/example/
 
 ```vue
 <script lang="ts" setup>
-  import { reactive, ref, h, nextTick, defineAsyncComponent } from 'vue';
+  import { reactive, ref, nextTick, defineAsyncComponent } from 'vue';
+  import { PlusOutlined, EditOutlined, DeleteOutlined, EyeOutlined } from '@ant-design/icons-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, Modal } from 'ant-design-vue';
 
   // 动态导入弹窗组件
   const editDialog = defineAsyncComponent(() => import('./edit.vue'));
@@ -79,24 +102,6 @@ ui/src/views/tool/example/
   // 查询参数
   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) => {
     return await getExamplePage({ ...formParams, ...params });
@@ -104,10 +109,15 @@ ui/src/views/tool/example/
 
   // 注册搜索表单
   const [register, {}] = useForm({
-    labelWidth: 80,
-    layout: 'horizontal',
-    colProps: { span: 6 },
-    submitOnReset: true,
+    rowProps: { gutter: [16, 0] },
+    colProps: {
+      xs: 24,
+      sm: 24,
+      md: 12,
+      lg: 8,
+      xl: 6,
+    },
+    labelCol: { span: 6, offset: 0 },
     schemas,
   });
 
@@ -127,22 +137,27 @@ ui/src/views/tool/example/
   const handleAdd = async () => { currentId.value = 0; await nextTick(); editVisible.value = true; };
 
   // 编辑
-  const handleEdit = async (record: Recordable) => { currentId.value = record.row.id; await nextTick(); editVisible.value = true; };
+  const handleEdit = async (record: Recordable) => { currentId.value = record.id; await nextTick(); editVisible.value = true; };
 
   // 详情
-  const handleDetail = async (record: Recordable) => { currentId.value = record.row.id; await nextTick(); detailVisible.value = true; };
+  const handleDetail = async (record: Recordable) => { currentId.value = record.id; await nextTick(); detailVisible.value = true; };
 
   // 删除
   async function handleDelete(record: Recordable) {
     let ids = [];
     if (!record) {
       ids = selectionData.value.map(({ id }) => id);
-      if (!ids.length) { message('请选择要删除的数据', 'warning'); return; }
+      if (!ids.length) { message.warning('请选择要删除的数据'); return; }
     }
-    await confirm('确定要删除选中的案例吗？');
-    record ? await exampleDelete(record.row.id) : await exampleBatchDelete(ids);
-    message('删除成功');
-    reloadTable();
+    Modal.confirm({
+      title: '提示',
+      content: '确定要删除选中的案例吗？',
+      onOk: async () => {
+        record ? await exampleDelete(record.id) : await exampleBatchDelete(ids);
+        message.success('删除成功');
+        reloadTable();
+      },
+    });
   }
 </script>
 ```
@@ -152,8 +167,9 @@ ui/src/views/tool/example/
 - **PageWrapper**：页面容器，提供统一的页面布局
 - **BasicForm**：搜索表单组件，通过 `useForm` 注册
 - **BasicTable**：数据表格组件，内置分页功能
-- **TableAction**：操作栏组件，支持权限控制
+- **bodyCell 插槽**：操作列通过 `bodyCell` 插槽 + `v-perm` 指令实现权限控制
 - **defineAsyncComponent**：懒加载弹窗组件，优化首屏加载
+- **Modal.confirm**：Ant Design Vue 的确认弹窗
 - **v-perm**：权限指令，控制按钮显示
 
 ## 2. 编辑弹窗 edit.vue
@@ -164,40 +180,42 @@ ui/src/views/tool/example/
 
 ```vue
 <template>
-  <el-dialog
-    v-model="props.visible"
+  <a-modal
+    v-model:visible="props.visible"
     :title="props.id ? '编辑案例' : '新增案例'"
-    width="500"
-    :close-on-click-modal="false"
-    :before-close="dialogClose"
+    width="500px"
+    @cancel="dialogClose"
+    :mask-closable="false"
   >
-    <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 v-model="formData.name" placeholder="请输入案例名称" clearable />
-      </el-form-item>
-      <el-form-item label="案例图片" prop="avatar">
+    <a-form class="ls-form" ref="formRef" :model="formData" :label-col="{ style: { width: '80px' } }">
+      <a-form-item label="案例名称" name="name" :rules="{ required: true, message: '请输入案例名称', trigger: 'blur' }">
+        <a-input v-model:value="formData.name" placeholder="请输入案例名称" allow-clear />
+      </a-form-item>
+      <a-form-item label="案例图片" name="avatar">
         <UploadImg v-model:image-url="formData.avatar" name="example" />
-      </el-form-item>
-      <el-form-item label="案例类型" prop="type" :rules="{ required: true, message: '请选择案例类型', trigger: 'change' }">
-        <el-select v-model="formData.type" placeholder="请选择" clearable filterable>
-          <el-option v-for="item in optionsData.typeList" :key="item.id" :label="item.name" :value="item.id" />
-        </el-select>
-      </el-form-item>
-      <el-form-item label="案例状态" prop="status" :rules="{ required: true, message: '请选择状态', trigger: 'change' }">
-        <el-radio-group v-model="formData.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" :rules="{ required: true, message: '请输入排序', trigger: 'blur' }">
-        <el-input-number v-model="formData.sort" :min="0" :max="99999" />
-      </el-form-item>
-    </el-form>
+      </a-form-item>
+      <a-form-item label="案例类型" name="type" :rules="{ required: true, message: '请选择案例类型', trigger: 'change' }">
+        <a-select v-model:value="formData.type" placeholder="请选择" allow-clear show-search :filter-option="filterOption">
+          <a-select-option v-for="item in optionsData.typeList" :key="item.id" :value="item.id">{{ item.name }}</a-select-option>
+        </a-select>
+      </a-form-item>
+      <a-form-item label="案例状态" name="status" :rules="{ required: true, message: '请选择状态', trigger: 'change' }">
+        <a-radio-group v-model:value="formData.status">
+          <a-radio :value="1">正常</a-radio>
+          <a-radio :value="2">禁用</a-radio>
+        </a-radio-group>
+      </a-form-item>
+      <a-form-item label="排序" name="sort" :rules="{ required: true, message: '请输入排序', trigger: 'blur' }">
+        <a-input-number v-model:value="formData.sort" :min="0" :max="99999" />
+      </a-form-item>
+    </a-form>
     <template #footer>
-      <el-button @click="dialogClose">取消</el-button>
-      <el-button :loading="subLoading" type="primary" @click="submit">确定</el-button>
+      <span class="dialog-footer">
+        <a-button @click="dialogClose">取消</a-button>
+        <a-button :loading="subLoading" type="primary" @click="submit">确定</a-button>
+      </span>
     </template>
-  </el-dialog>
+  </a-modal>
 </template>
 ```
 
@@ -205,15 +223,17 @@ ui/src/views/tool/example/
 
 ```vue
 <script lang="ts" setup>
+  import type { FormInstance } from 'ant-design-vue';
   import { getExampleDetail, exampleAdd, exampleUpdate } from '@/api/tool/example';
   import { onMounted, reactive, shallowRef, watch } from 'vue';
+  import { message } from 'ant-design-vue';
   import { useLockFn } from '@/utils/useLockFn';
 
   const emit = defineEmits(['success', 'update:visible']);
   const formRef = shallowRef<FormInstance>();
 
   const formData = reactive({
-    id: '', name: '', avatar: '', type: 0, status: 0, sort: 0,
+    id: '', name: '', avatar: '', type: 1, status: 1, sort: 0,
   });
 
   const props = defineProps({
@@ -225,11 +245,14 @@ ui/src/views/tool/example/
   const handleSubmit = async () => {
     await formRef.value?.validate();
     props.id ? await exampleUpdate(formData) : await exampleAdd(formData);
-    message('操作成功');
+    message.success('操作成功');
     emit('update:visible', false);
     emit('success');
   };
 
+  // 关闭弹窗
+  const dialogClose = () => { emit('update:visible', false); };
+
   // 防重复提交
   const { isLock: subLoading, lockFn: submit } = useLockFn(handleSubmit);
 
@@ -244,6 +267,11 @@ ui/src/views/tool/example/
   onMounted(() => {
     if (props.id) { setFormData(); } else { resetForm(); }
   });
+
+  watch(() => props.visible, (newVal) => {
+    if (newVal && props.id) { setFormData(); }
+    else if (newVal && !props.id) { resetForm(); }
+  });
 </script>
 ```
 
@@ -257,35 +285,35 @@ ui/src/views/tool/example/
 
 ## 3. 详情弹窗 detail.vue
 
-详情弹窗用于展示记录的详细信息，使用 ElementPlus 的 `el-descriptions` 组件。
+详情弹窗用于展示记录的详细信息，使用 Ant Design Vue 的 `a-descriptions` 组件。
 
 ### 核心结构
 
 ```vue
 <template>
-  <el-dialog v-model="props.visible" title="案例详情" width="750" :close-on-click-modal="false">
-    <el-descriptions column="2" border>
-      <el-descriptions-item label="案例名称:">{{ formData.name || '-' }}</el-descriptions-item>
-      <el-descriptions-item label="案例图片:">
-        <el-image v-if="formData.avatar" :src="formData.avatar" :preview-src-list="[formData.avatar]" fit="cover" style="width: 80px; height: 80px" />
+  <a-modal v-model:visible="props.visible" title="案例详情" width="750px" @cancel="dialogClose" :mask-closable="false">
+    <a-descriptions :column="2" bordered>
+      <a-descriptions-item label="案例名称">{{ formData.name || '-' }}</a-descriptions-item>
+      <a-descriptions-item label="案例图片">
+        <a-image v-if="formData.avatar" :src="formData.avatar" :width="80" :height="80" fit="cover" />
         <span v-else>-</span>
-      </el-descriptions-item>
-      <el-descriptions-item label="案例类型:">{{ getChoiceLabel('type', formData.type) }}</el-descriptions-item>
-      <el-descriptions-item label="案例状态:">{{ getChoiceLabel('status', formData.status) }}</el-descriptions-item>
-      <el-descriptions-item label="排序:">{{ formData.sort || '-' }}</el-descriptions-item>
-    </el-descriptions>
+      </a-descriptions-item>
+      <a-descriptions-item label="案例类型">{{ getChoiceLabel('type', formData.type) }}</a-descriptions-item>
+      <a-descriptions-item label="案例状态">{{ getChoiceLabel('status', formData.status) }}</a-descriptions-item>
+      <a-descriptions-item label="排序">{{ formData.sort || '-' }}</a-descriptions-item>
+    </a-descriptions>
     <template #footer>
-      <el-button @click="dialogClose">关闭</el-button>
+      <a-button @click="dialogClose">关闭</a-button>
     </template>
-  </el-dialog>
+  </a-modal>
 </template>
 ```
 
 ### 关键点
 
-- **el-descriptions**：ElementPlus 的描述列表组件，用于展示详情
+- **a-descriptions**：Ant Design Vue 的描述列表组件，用于展示详情
 - **getChoiceLabel**：将枚举值转换为中文标签
-- **图片预览**：使用 `el-image` 的 `preview-src-list` 实现图片预览
+- **图片预览**：使用 `a-image` 实现图片预览
 
 ## 4. 表格列定义 columns.ts
 
@@ -295,54 +323,89 @@ ui/src/views/tool/example/
 
 ```typescript
 import { h } from 'vue';
-import { ElAvatar, ElTag } from 'element-plus';
+import { Tag, Image } from 'ant-design-vue';
 
 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' });
+    title: 'ID',
+    dataIndex: 'id',
+    fixed: 'left',
+    width: 50,
+  },
+  {
+    title: '案例名称',
+    dataIndex: 'name',
+    width: 150,
+  },
+  {
+    title: '案例图片',
+    dataIndex: 'avatar',
+    width: 150,
+    customRender({ record }) {
+      return record.avatar
+        ? h(Image, { src: record.avatar, width: 48, height: 48, fit: 'cover', preview: true })
+        : h('span', '-');
     },
   },
   {
-    label: '案例类型', prop: 'type', minWidth: 100,
-    render(record) {
+    title: '案例类型',
+    dataIndex: 'type',
+    width: 100,
+    customRender({ record }) {
       const statusMap = {
-        1: { text: '类型1', type: 'success' },
-        2: { text: '类型2', type: 'danger' },
-        3: { text: '类型3', type: 'warning' },
-        4: { text: '类型4', type: 'info' },
+        1: { text: '类型1', color: 'success' },
+        2: { text: '类型2', color: 'error' },
+        3: { text: '类型3', color: 'warning' },
+        4: { text: '类型4', color: 'default' },
       };
-      const status = statusMap[record.row.type];
-      return h(ElTag, { type: status?.type || 'info' }, { default: () => status?.text || record.row.type });
+      const status = statusMap[record.type];
+      return h(Tag, { color: status?.color || 'default' }, { default: () => status?.text || record.type });
     },
   },
   {
-    label: '案例状态', prop: 'status', minWidth: 100,
-    render(record) {
+    title: '案例状态',
+    dataIndex: 'status',
+    width: 100,
+    customRender({ record }) {
       const statusMap = {
-        1: { text: '正常', type: 'success' },
-        2: { text: '禁用', type: 'danger' },
+        1: { text: '正常', color: 'success' },
+        2: { text: '禁用', color: 'error' },
       };
-      const status = statusMap[record.row.status];
-      return h(ElTag, { type: status?.type || 'info' }, { default: () => status?.text || record.row.status });
+      const status = statusMap[record.status];
+      return h(Tag, { color: status?.color || 'default' }, { default: () => status?.text || record.status });
     },
   },
-  { label: '排序', prop: 'sort', minWidth: 100 },
-  { label: '创建人', prop: 'createUser', minWidth: 100 },
-  { label: '创建时间', prop: 'createTime', width: 180 },
+  {
+    title: '排序',
+    dataIndex: 'sort',
+    width: 100,
+  },
+  {
+    title: '创建人',
+    dataIndex: 'createUser',
+    width: 100,
+  },
+  {
+    title: '创建时间',
+    dataIndex: 'createTime',
+    width: 180,
+  },
+  {
+    title: '操作',
+    fixed: 'right',
+    dataIndex: 'action',
+    key: 'action',
+    width: 200,
+  },
 ];
 ```
 
 ### 关键点
 
-- **type: 'selection'**：自动添加复选框列
-- **render 函数**：使用 Vue 的 `h()` 函数创建虚拟 DOM
-- **ElTag 组件**：将状态值渲染为彩色标签
-- **ElAvatar 组件**：将图片 URL 渲染为缩略图
+- **title / dataIndex**：Ant Design Vue 的列定义字段
+- **customRender 函数**：使用 Vue 的 `h()` 函数创建虚拟 DOM
+- **Tag 组件**：将状态值渲染为彩色标签（`color: 'success'` / `'error'`）
+- **Image 组件**：将图片 URL 渲染为缩略图
 
 ## 5. 搜索表单 querySchemas.ts
 
@@ -355,18 +418,19 @@ import { FormSchema } from '@/components/Form/index';
 
 export const schemas: FormSchema[] = [
   {
-    field: 'name',
+    name: 'name',
     component: 'Input',
     label: '案例名称',
-    componentProps: { placeholder: '请输入案例名称', clearable: true },
+    componentProps: { placeholder: '请输入案例名称', clearable: true, allowClear: true },
   },
   {
-    field: 'type',
+    name: 'type',
     component: 'Select',
     label: '案例类型',
     componentProps: {
       placeholder: '请输入案例类型',
       clearable: true,
+      allowClear: true,
       options: [
         { label: '类型1', value: 1 },
         { label: '类型2', value: 2 },
@@ -376,12 +440,13 @@ export const schemas: FormSchema[] = [
     },
   },
   {
-    field: 'status',
+    name: 'status',
     component: 'Select',
     label: '案例状态',
     componentProps: {
       placeholder: '请输入案例状态',
       clearable: true,
+      allowClear: true,
       options: [
         { label: '正常', value: 1 },
         { label: '禁用', value: 2 },
@@ -393,9 +458,10 @@ export const schemas: FormSchema[] = [
 
 ### 关键点
 
-- **field**：字段名，与后端查询参数对应
+- **name**：字段名，与后端查询参数对应
 - **component**：表单组件类型：`Input` / `Select` / `DatePicker` 等
-- **componentProps**：组件属性，透传给 ElementPlus 组件
+- **componentProps**：组件属性，透传给 Ant Design Vue 组件
+- **allowClear**：Ant Design Vue 的清除属性
 - **options**：Select 组件的下拉选项
 
 ## 文件关系图
@@ -424,7 +490,10 @@ detail.vue（详情弹窗）
 5. **搜索 Schema 使用 `FormSchema` 类型**：配置化定义表单字段
 6. **新增/编辑通过 `id` 区分**：0 为新增，非 0 为编辑
 7. **防重复提交使用 `useLockFn`**：提交时按钮 loading
+8. **操作列使用 `bodyCell` 插槽**：通过插槽自定义操作按钮
+9. **确认弹窗使用 `Modal.confirm`**：Ant Design Vue 的确认弹窗
+10. **消息提示使用 `message.success()`**：Ant Design Vue 的消息提示
 
 ## 总结
 
-前端页面统一使用 `PageWrapper` + `BasicForm` + `BasicTable` + `TableAction` 四件套，分页由 `BasicTable` 内置处理。每个模块包含 `index.vue`（列表页）、`edit.vue`（编辑弹窗）、`detail.vue`（详情弹窗）、`columns.ts`（列定义）、`querySchemas.ts`（搜索配置）五个文件。
+前端页面统一使用 `PageWrapper` + `BasicForm` + `BasicTable` + `bodyCell` 插槽四件套，分页由 `BasicTable` 内置处理。每个模块包含 `index.vue`（列表页）、`edit.vue`（编辑弹窗）、`detail.vue`（详情弹窗）、`columns.ts`（列定义）、`querySchemas.ts`（搜索配置）五个文件。