签入版本

2026-09-16 17:25:03 +08:00
parent f953e82e09
commit 0d560e5122
46 changed files with 1106 additions and 911 deletions
@@ -1,7 +1,7 @@
 # Modal 弹窗

 :::tip 说明
-项目提供 `BasicModal` 组件（`src/components/Modal/src/BasicModal.vue`）和原生 `el-dialog` 两种弹窗用法。编辑弹窗通过 `defineAsyncComponent` 懒加载，减少首屏渲染负担。
+项目提供 `BasicModal` 组件（`src/components/Modal/src/BasicModal.vue`）和 `useModal` hook 管理弹窗状态。编辑弹窗通过 `basicModal` 组件实现，支持提交按钮 loading、标题动态设置等能力。
 :::

 ## 组件架构
@@ -9,7 +9,7 @@
 ```
 src/components/Modal/
 ├── src/
-│ ├── BasicModal.vue     # 主组件（基于 el-dialog）
+│ ├── BasicModal.vue     # 主组件
 │ ├── props.ts           # 属性定义
 │ ├── type.ts            # 类型定义（ModalProps、ModalMethods）
 │ └── hooks/
@@ -19,12 +19,20 @@ src/components/Modal/

 ## BasicModal 组件

-`BasicModal` 基于 `el-dialog` 封装，提供全屏切换、自定义头部、提交按钮等能力：
+`BasicModal` 提供全屏切换、自定义头部、提交按钮等能力：

 ```vue
-<BasicModal :title="'编辑'" :width="600" @register="registerModal" @ok="handleSubmit">
-    <BasicForm @register="registerForm" />
-</BasicModal>
+<basicModal
+    @register="modalRegister"
+    ref="modalRef"
+    class="basicModal basicFormModal"
+    @on-ok="handleSubmit"
+    @on-close="handleClose"
+>
+    <template #default>
+        <!-- 表单内容 -->
+    </template>
+</basicModal>
 ```

 核心功能：
@@ -36,89 +44,96 @@ src/components/Modal/

 ## 实际用法（position 模块）

-以岗位管理为例，实际使用原生 `el-dialog` + `defineAsyncComponent` 懒加载：
+以岗位管理为例，使用 `basicModal` + `useModal` hook 管理弹窗：

 ### 父组件（index.vue）

 ```vue
 <!-- src/views/system/position/index.vue -->
 <script setup>
-import { defineAsyncComponent } from 'vue';
-const editDialog = defineAsyncComponent(() => import('./edit.vue'));
+import editDialog from './edit.vue';

+const createModalRef = ref();
 const positionId = ref(0);
 const editVisible = ref(false);

 // 新增
 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: Recordable) {
+    positionId.value = record.id;
    editVisible.value = true;
-};
+    await nextTick();
+    createModalRef.value.openModal();
+}
 </script>

 <template>
    <editDialog
-        v-if="editVisible"
+        ref="createModalRef"
        :positionId="positionId"
+        v-if="editVisible"
        v-model:visible="editVisible"
        @success="reloadTable('noRefresh')"
    />
 </template>
 ```

-`defineAsyncComponent` 实现懒加载：首屏不加载弹窗组件，首次打开时才加载，加载完成后缓存。
-
 ### 编辑弹窗（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"
+    <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' }"
+        <template #default>
+            <n-form
+                class="ls-form"
+                ref="formRef"
+                :model="formData"
+                label-placement="left"
+                label-width="85px"
            >
-                <el-input v-model="formData.name" placeholder="请输入岗位名称" clearable />
-            </el-form-item>
-            <el-form-item label="岗位状态" prop="status">
-                <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">
-                <el-input-number v-model="formData.sort" />
-            </el-form-item>
-        </el-form>
-        <template #footer>
-            <el-button @click="dialogClose">取消</el-button>
-            <el-button :loading="subLoading" type="primary" @click="submit">确定</el-button>
+                <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>
-    </el-dialog>
+    </basicModal>
 </template>

 <script lang="ts" setup>
 import { getPositionDetail, positionAdd, positionUpdate } from '@/api/system/position';
-import { useLockFn } from '@/utils/useLockFn';
+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 });

@@ -127,20 +142,31 @@ const props = defineProps({
    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((error) => {
+            setSubLoading(false);
+        });
 };

 // 关闭弹窗
-const dialogClose = () => { emit('update:visible', false); };
-
-// useLockFn 防重复提交，isLock 绑定按钮 loading
-const { isLock: subLoading, lockFn: submit } = useLockFn(handleSubmit);
+const handleClose = () => { emit('update:visible', false); };

 // 编辑时加载数据
 const setFormData = async () => {
@@ -155,42 +181,49 @@ const setFormData = async () => {
 onMounted(() => {
    if (props.positionId) setFormData();
 });
+
+defineExpose({ openModal });
 </script>
 ```

 ## 弹窗数据流

 ```
-父组件点击编辑 → positionId = record.row.id → editVisible = true
+父组件点击编辑 → positionId = record.id → editVisible = true → openModal()
 ↓
 edit.vue onMounted → positionId != 0 → setFormData() → 获取详情填充表单
 ↓
-用户修改 → submit → useLockFn(防重复) → formRef.validate() → positionUpdate(formData)
+用户修改 → handleSubmit → formRef.validate() → positionUpdate(formData)
 ↓
 emit('success') → 父组件 reloadTable() → 表格刷新
 ```

 ## 确认弹窗

-删除等危险操作使用 `confirm` 封装函数（来自 `src/utils/auth.ts`）：
+删除等危险操作使用 NaiveUI 的 `useDialog`：

 ```typescript
-import { message, confirm } from '@/utils/auth';
+import { useMessage, useDialog } from 'naive-ui';

-async function handleDelete(record: Recordable) {
-    let ids = [];
-    if (!record) {
-        ids = selectionData.value.map(({ id }) => id);
-    }
+const message = useMessage();
+const dialog = useDialog();

-    await confirm('确定要删除？');
-    record ? await positionDelete(record.row.id) : await positionBatchDelete(ids);
-    message('删除成功');
-    reloadTable();
+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();
+        },
+    });
 }
 ```

-`confirm` 内部调用 `ElMessageBox.confirm`，返回 Promise，用户取消时抛出异常中断后续逻辑。
+`useDialog` 返回 Dialog 实例，通过 `dialog.warning()` / `dialog.error()` 等方法弹出确认框，`onPositiveClick` 回调处理确认逻辑。

 ## v-model:visible 双向绑定

@@ -203,14 +236,14 @@ async function handleDelete(record: Recordable) {
 <!-- 子组件 -->
 <script setup>
 const emit = defineEmits(['update:visible']);
-const dialogClose = () => { emit('update:visible', false); };
+const handleClose = () => { emit('update:visible', false); };
 </script>
 ```

 :::tip 温馨提示
-弹窗组件通过 `defineAsyncComponent(() => import('./edit.vue'))` 懒加载，首屏不加载弹窗代码。`useLockFn` 将 `isLock` 绑定按钮的 `:loading` 属性，防止重复提交。关闭弹窗时通过 `v-model:visible` 自动同步父子状态。
+编辑弹窗使用 `basicModal` 组件，通过 `useModal` hook 管理弹窗状态（标题、宽度、提交按钮 loading）。`setSubLoading(false)` 在提交完成后关闭 loading。`defineExpose({ openModal })` 暴露 `openModal` 方法供父组件调用。
 :::

 ## 总结

-编辑弹窗使用 `el-dialog` + `defineAsyncComponent` 懒加载，通过 `v-model:visible` 双向绑定显隐状态，`useLockFn` 防重复提交。父组件通过 `positionId` prop 传递编辑行 ID，子组件在 `onMounted` 中判断并加载详情数据。操作成功后 `emit('success')` 通知父组件刷新表格。
+编辑弹窗使用 `basicModal` + `useModal` hook 管理弹窗状态，通过 `v-model:visible` 双向绑定显隐状态，`setSubLoading` 控制提交按钮 loading 防重复提交。父组件通过 `positionId` prop 传递编辑行 ID，子组件在 `onMounted` 中判断并加载详情数据。操作成功后 `emit('success')` 通知父组件刷新表格。删除确认使用 NaiveUI 的 `useDialog`。