优化更新

DjangoAdmin_Flask_NaiveVue/zh/volume2/fe-view.md

@@ -1,6 +1,6 @@
 # 前端页面视图
 
-前端页面视图是用户直接交互的界面。项目使用 Vue3 + ElementPlus + Vite 构建。一个完整的 CRUD 页面由 4 个文件组成：
+前端页面视图是用户直接交互的界面。项目使用 Vue3 + NaiveUI + Vite 构建。一个完整的 CRUD 页面由 4 个文件组成：
 
 ```
 ui/src/views/system/position/
@@ -18,101 +18,92 @@ ui/src/views/system/position/
 
 ```vue
 <template>
-  <PageWrapper>
-    <el-card :bordered="false" class="pt-3 mb-3 proCard">
+  <div>
+    <n-card :bordered="false" class="pt-3 mb-3 proCard">
       <BasicForm @register="register" @submit="handleSubmit" @reset="handleReset" />
-    </el-card>
-    <el-card :bordered="false" class="proCard">
+    </n-card>
+    <n-card :bordered="false" class="proCard">
       <BasicTable
         :columns="columns"
         :request="loadDataTable"
         :row-key="(row) => row.id"
-        ref="tableRef"
+        ref="basicTableRef"
         :actionColumn="actionColumn"
-        @selection-change="onSelectionChange"
+        @update:checked-row-keys="onCheckedRow"
+        :autoScrollX="true"
       >
         <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>
+          <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>
-    </el-card>
-
+    </n-card>
     <editDialog
-      v-if="editVisible"
+      ref="createModalRef"
       :positionId="positionId"
+      v-if="editVisible"
       v-model:visible="editVisible"
       @success="reloadTable('noRefresh')"
     />
-  </PageWrapper>
+  </div>
 </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 { h, nextTick, reactive, ref } 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 } from '@vicons/antd';
-  import { message, confirm } from '@/utils/auth';
-  const editDialog = defineAsyncComponent(() => import('./edit.vue'));
-  const positionId = ref(0);
+  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 selectionData = ref([]);
-  const tableRef = ref();
+  const positionId = ref(0);
+  const rowKeys = ref([]);
 
-  /**
-   * 定义查询参数
-   */
-  const formParams = reactive({
-    name: '',
-    status: '',
-  });
+  const formParams = reactive({ name: '', status: '' });
 
-  /**
-   * 定义操作栏
-   */
   const actionColumn = reactive({
     width: 200,
-    label: '操作',
-    prop: 'action',
+    title: '操作',
+    align: 'center',
+    key: 'action',
     fixed: 'right',
     render(record) {
-      return h(TableAction, {
+      return h(TableAction as any, {
         style: 'button',
         actions: [
           {
             label: '编辑',
-            icon: 'Edit',
-            type: 'warning',
+            icon: renderIcon(FormOutlined),
+            type: 'info',
             onClick: handleEdit.bind(null, record),
             auth: ['sys:position:update'],
           },
           {
             label: '删除',
-            icon: 'Delete',
-            type: 'danger',
+            icon: renderIcon(DeleteOutlined),
+            type: 'error',
             onClick: handleDelete.bind(null, record),
             auth: ['sys:position:delete'],
           },
@@ -121,106 +112,81 @@ ui/src/views/system/position/
     },
   });
 
-  /**
-   * 加载数据列表
-   */
-  const loadDataTable = async (res: any) => {
+  const loadDataTable = async (res) => {
+    rowKeys.value = [];
     const result = await getPositionList({ ...formParams, ...res });
     return result;
   };
 
-  /**
-   * 刷新数据列表
-   */
+  function onCheckedRow(keys) {
+    rowKeys.value = keys;
+  }
+
   function reloadTable(noRefresh = '') {
-    tableRef.value.reload(noRefresh ? {} : { pageNo: 1 });
+    basicTableRef.value.reload(noRefresh ? {} : { pageNo: 1 });
+  }
+
+  function handleSubmit(values: Recordable) {
+    for (const key in formParams) { formParams[key] = ''; }
+    for (const key in values) { formParams[key] = values[key]; }
+    reloadTable();
+  }
+
+  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,
-    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;
+    await nextTick();
+    createModalRef.value.openModal();
   };
 
-  /**
-   * 执行编辑
-   */
-  const handleEdit = async (record: Recordable) => {
-    positionId.value = record.row.id;
-    await nextTick();
+  async function handleEdit(record) {
+    positionId.value = record.id;
     editVisible.value = true;
-  };
-
-  /**
-   * 执行删除（单条 + 批量）
-   */
-  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();
+    await nextTick();
+    createModalRef.value.openModal();
   }
 
-  /**
-   * 选项发生变化
-   */
-  function onSelectionChange(value) {
-    selectionData.value = value;
+  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>
 ```
 
 ### 代码解析
 
-**页面结构**：`PageWrapper` 包裹两个 `el-card`，上方是搜索表单，下方是数据表格。
+**页面结构**：`div` 包裹两个 `n-card`，上方是搜索表单，下方是数据表格。
 
 **搜索表单**：通过 `useForm` 注册，Schema 从 `querySchemas.ts` 导入。`submitOnReset: true` 表示重置时自动触发查询。
 
 **数据表格**：通过 `BasicTable` 组件渲染，`request` 属性绑定数据加载函数，`columns` 从 `columns.ts` 导入。
 
-**操作栏**：通过 `actionColumn` 的 `render` 函数使用 `h()` 渲染 `TableAction`，支持权限控制（`auth`）。
+**操作栏**：通过 `actionColumn` 的 `render` 函数使用 `h()` 渲染 `TableAction`，支持权限控制（`auth`）。图标使用 `renderIcon` 工具函数渲染 `@vicons/antd` 图标。
 
 **编辑弹窗**：使用 `defineAsyncComponent` 懒加载 `edit.vue`，通过 `v-model:visible` 控制显示，`positionId` 传入编辑记录 ID（0 表示新增）。
 
-**删除逻辑**：单条删除传入 `record`，批量删除从 `selectionData` 取已选 ID。共用同一个 `handleDelete` 方法。
+**删除逻辑**：使用 NaiveUI 的 `useDialog` 显示确认弹窗，单条删除传入 `record`，批量删除从 `rowKeys` 取已选 ID。
 
 ## 2. 编辑弹窗 `edit.vue`
 
@@ -230,99 +196,78 @@ ui/src/views/system/position/
 
 ```vue
 <template>
-  <el-dialog
-    v-model="props.visible"
-    :title="props.positionId ? '编辑' : '新增'"
-    width="500"
-    :close-on-click-modal="false"
-    :before-close="dialogClose"
+  <basicModal
+    @register="modalRegister"
+    ref="modalRef"
+    class="basicModal basicFormModal"
+    @on-ok="handleSubmit"
+    @on-close="handleClose"
   >
-    <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 #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="status">
+          <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>
-  </el-dialog>
+  </basicModal>
 </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';
+  import { onMounted, reactive, ref } from 'vue';
+  import { useMessage } from 'naive-ui';
+  import { useModal } from '@/components/Modal';
 
   const emit = defineEmits(['success', 'update:visible']);
-  const formRef = shallowRef<FormInstance>();
+  const formRef = ref();
+  const message = useMessage();
 
-  /**
-   * 定义表单参数
-   */
-  const formData = reactive({
-    id: '',
-    name: '',
-    status: 1,
-    sort: 0,
-  });
+  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,
-    },
+    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 () => {
-    await formRef.value?.validate();
-    props.positionId ? await positionUpdate(formData) : await positionAdd(formData);
-    message('操作成功');
-    emit('update:visible', false);
-    emit('success');
+    formRef.value
+      .validate()
+      .then(async () => {
+        props.positionId ? await positionUpdate(formData) : await positionAdd(formData);
+        message.success('操作成功');
+        setSubLoading(false);
+        emit('update:visible', false);
+        emit('success');
+      })
+      .catch(() => {
+        setSubLoading(false);
+      });
   };
 
-  /**
-   * 关闭窗体
-   */
-  const dialogClose = () => {
+  const handleClose = () => {
     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) {
@@ -332,14 +277,11 @@ ui/src/views/system/position/
     }
   };
 
-  /**
-   * 钩子函数
-   */
   onMounted(() => {
-    if (props.positionId) {
-      setFormData();
-    }
+    if (props.positionId) setFormData();
   });
+
+  defineExpose({ openModal });
 </script>
 ```
 
@@ -353,7 +295,7 @@ ui/src/views/system/position/
 
 **新增/编辑判断**：`props.positionId ? positionUpdate : positionAdd`，通过 ID 是否为 0 区分。
 
-**防重复提交**：`useLockFn` 包装提交函数，点击后按钮变为 loading 状态，防止重复提交。
+**防重复提交**：`useModal` 提供 `setSubLoading` 控制提交按钮 loading 状态。
 
 **数据回填**：`onMounted` 时判断如果是编辑模式，调用 `getPositionDetail` 获取数据并填充表单。
 
@@ -369,52 +311,54 @@ ui/src/views/system/position/
 
 ```typescript
 import { h } from 'vue';
-import { ElTag } from 'element-plus';
+import { NTag } from 'naive-ui';
 
 export const columns = [
   {
     type: 'selection',
+    width: 50,
+    fixed: 'left',
   },
   {
-    label: 'ID',
-    prop: 'id',
+    title: 'ID',
+    key: 'id',
     fixed: 'left',
     width: 50,
   },
   {
-    label: '岗位名称',
-    prop: 'name',
-    minWidth: 100,
+    title: '岗位名称',
+    key: 'name',
+    width: 100,
   },
   {
-    label: '岗位状态',
-    prop: 'status',
-    minWidth: 100,
+    title: '岗位状态',
+    key: 'status',
+    width: 100,
     render(record) {
       return h(
-        ElTag,
+        NTag,
         {
-          type: record.row.status == 1 ? 'success' : 'danger',
-        },
-        {
-          default: () => (record.row.status == 1 ? '正常' : '停用'),
+          style: { marginRight: '6px' },
+          bordered: false,
+          type: record.status == 1 ? 'success' : 'error',
         },
+        { default: () => (record.status == 1 ? '正常' : '停用') },
       );
     },
   },
   {
-    label: '排序',
-    prop: 'sort',
-    minWidth: 100,
+    title: '排序',
+    key: 'sort',
+    width: 100,
   },
   {
-    label: '创建人',
-    prop: 'createUser',
-    minWidth: 100,
+    title: '创建人',
+    key: 'createUser',
+    width: 100,
   },
   {
-    label: '创建时间',
-    prop: 'createTime',
+    title: '创建时间',
+    key: 'createTime',
     width: 180,
   },
 ];
@@ -422,11 +366,11 @@ export const columns = [
 
 ### 代码解析
 
-**选择列**：`type: 'selection'` 自动添加复选框列，配合 `@selection-change` 事件实现批量选择。
+**选择列**：`type: 'selection'` 自动添加复选框列，配合 `@update:checked-row-keys` 事件实现批量选择。
 
 **固定列**：`fixed: 'left'` 固定在左侧，`fixed: 'right'` 固定在右侧（操作列）。
 
-**自定义渲染**：`render(record)` 使用 Vue 的 `h()` 函数创建虚拟 DOM。状态列将 `1/2` 渲染为绿色/红色标签。
+**自定义渲染**：`render(record)` 使用 Vue 的 `h()` 函数创建虚拟 DOM。`render` 函数直接接收行数据对象，通过 `record.key` 访问字段值（如 `record.status`）。状态列将 `1/2` 渲染为绿色/红色标签。
 
 **宽度设置**：
 - `width`：固定宽度
@@ -443,7 +387,7 @@ import { FormSchema } from '@/components/Form/index';
 export const schemas: FormSchema[] = [
   {
     field: 'name',
-    component: 'Input',
+    component: 'NInput',
     label: '岗位名称',
     componentProps: {
       placeholder: '请输入岗位名称',
@@ -451,20 +395,14 @@ export const schemas: FormSchema[] = [
   },
   {
     field: 'status',
-    component: 'Select',
+    component: 'NSelect',
     label: '状态',
     componentProps: {
       placeholder: '请选择状态',
       clearable: true,
       options: [
-        {
-          label: '正常',
-          value: '1',
-        },
-        {
-          label: '禁用',
-          value: '2',
-        },
+        { label: '正常', value: '1' },
+        { label: '禁用', value: '2' },
       ],
     },
   },
@@ -478,9 +416,9 @@ export const schemas: FormSchema[] = [
 | 字段 | 说明 |
 |:----|:----|
 | `field` | 字段名，与后端查询参数对应 |
-| `component` | 表单组件类型：`Input` / `Select` / `DatePicker` 等 |
+| `component` | 表单组件类型：`NInput` / `NSelect` / `NDatePicker` 等 |
 | `label` | 标签文本 |
-| `componentProps` | 组件属性，透传给 ElementPlus 组件 |
+| `componentProps` | 组件属性，透传给 NaiveUI 组件 |
 
 **Select 组件**：`options` 定义下拉选项，`clearable: true` 允许清空选择。
 
@@ -505,8 +443,8 @@ edit.vue（编辑弹窗）
 4. **列定义使用 `h()` 渲染复杂内容**：如状态标签、操作按钮
 5. **搜索 Schema 使用 `FormSchema` 类型**：配置化定义表单字段
 6. **新增/编辑通过 `positionId` 区分**：0 为新增，非 0 为编辑
-7. **防重复提交使用 `useLockFn`**：提交时按钮 loading
+7. **删除使用 `useDialog` 确认弹窗**：NaiveUI 命令式对话框
 
 ## 总结
 
-前端页面统一使用 `PageWrapper` + `BasicForm` + `BasicTable` + `TableAction` 四件套，分页由 `BasicTable` 内置处理。每个模块包含 `index.vue`（列表页）、`edit.vue`（编辑弹窗）、`columns.ts`（列定义）、`querySchemas.ts`（搜索配置）四个文件。
+前端页面统一使用 `n-card` + `BasicForm` + `BasicTable` + `TableAction` 四件套，分页由 `BasicTable` 内置处理。每个模块包含 `index.vue`（列表页）、`edit.vue`（编辑弹窗）、`columns.ts`（列定义）、`querySchemas.ts`（搜索配置）四个文件。