Modal Organize

命令式弹窗代码组织规范

什么时候用

当需要新增弹窗、重构弹窗结构、或询问弹窗代码应该放在哪里时使用。

核心原则

每个弹窗 = 一个文件夹 = Vue 组件 + openXxx.ts 打开函数

高内聚、易维护、按业务归属就近放置。

推荐结构：页面内部聚合

假设页面是 UserManagement，有新增、编辑、详情、分配角色等弹窗。

src/
├── views/
│   └── user-management/
│       ├── index.vue                  # 主页面，只调用 openXxx 函数
│       ├── modals/                    # 该页面专属弹窗聚合目录
│       │   ├── add-edit-user/
│       │   │   ├── UserForm.vue       # 表单组件（纯UI+逻辑）
│       │   │   └── openUserForm.ts    # 打开新增/编辑弹窗的命令式函数
│       │   ├── user-detail/
│       │   │   ├── UserDetail.vue     # 详情组件
│       │   │   └── openUserDetail.ts
│       │   ├── assign-role/
│       │   │   ├── AssignRole.vue
│       │   │   └── openAssignRole.ts
│       │   └── confirm-delete/
│       │       ├── ConfirmDelete.vue
│       │       └── openConfirmDelete.ts
│       └── hooks/                     # 页面级通用 hooks（可选）
│           └── useUserActions.ts

文件内容示例

1. 打开函数（openUserForm.ts）

import { useModal } from '@newlifex/cube-vue/core/composables/useModal';
import UserForm from './UserForm.vue';
import type { UserFormData } from './UserForm.vue';

/**
 * 打开新增用户弹窗
 */
export function openAddUser(): Promise<UserFormData | null> {
  return new Promise((resolve) => {
    const { openModal } = useModal();
    openModal({
      title: '新增用户',
      width: '600px',
      component: UserForm,
      componentProps: { mode: 'add' },
      onConfirm: async (data: UserFormData) => {
        // 调用新增 API
        await createUserApi(data);
        resolve(data);
      },
      onCancel: () => resolve(null),
      onClosed: () => resolve(null),
    });
  });
}

/**
 * 打开编辑用户弹窗
 */
export function openEditUser(user: User): Promise<UserFormData | null> {
  return new Promise((resolve) => {
    const { openModal } = useModal();
    openModal({
      title: '编辑用户',
      width: '600px',
      component: UserForm,
      componentProps: { mode: 'edit', modelValue: user },
      componentEvents: {
        'update:modelValue': (val: UserFormData) => { /* 可选：实时同步 */ },
      },
      onConfirm: async (data: UserFormData) => {
        await updateUserApi(user.id, data);
        resolve(data);
      },
      onCancel: () => resolve(null),
      onClosed: () => resolve(null),
    });
  });
}

2. 表单组件（UserForm.vue）

<template>
  <el-form :model="formData" label-width="80px">
    <el-form-item label="用户名" prop="name">
      <el-input v-model="formData.name" />
    </el-form-item>
    <el-form-item label="邮箱" prop="email">
      <el-input v-model="formData.email" />
    </el-form-item>
  </el-form>
</template>

<script setup lang="ts">
import { computed } from 'vue';

export interface UserFormData {
  name: string;
  email: string;
}

const props = defineProps<{
  mode: 'add' | 'edit';
  modelValue?: Partial<UserFormData>;
}>();

const emit = defineEmits<{
  'update:modelValue': [value: UserFormData];
}>();

const formData = computed<UserFormData>({
  get: () => ({
    name: props.modelValue?.name ?? '',
    email: props.modelValue?.email ?? '',
  }),
  set: (val) => emit('update:modelValue', val),
});
</script>

3. 主页面调用（index.vue）

<script setup lang="ts">
import { openAddUser, openEditUser } from './modals/add-edit-user/openUserForm';
import { openConfirmDelete } from './modals/confirm-delete/openConfirmDelete';

/**
 * 新增用户
 */
async function handleAdd() {
  const result = await openAddUser();
  if (result) {
    // 新增成功，刷新列表
    await fetchList();
  }
}

/**
 * 编辑用户
 */
async function handleEdit(row: User) {
  const result = await openEditUser(row);
  if (result) {
    await fetchList();
  }
}

/**
 * 删除用户
 */
async function handleDelete(row: User) {
  const confirmed = await openConfirmDelete(row);
  if (confirmed) {
    await deleteUserApi(row.id);
    await fetchList();
  }
}
</script>

为什么这样组织？

跨页面复用：提升到公共组件

当弹窗需要在多个页面使用时，将其提升为公共弹窗组件：

src/
├── components/
│   └── modals/                  # 全局共享弹窗
│       ├── confirm-delete/
│       │   ├── ConfirmDelete.vue
│       │   └── openConfirmDelete.ts
│       └── import-excel/
│           ├── ImportExcel.vue
│           └── openImportExcel.ts
├── views/
│   └── user-management/
│       ├── index.vue
│       └── modals/              # 页面专属弹窗仍保留
│           └── add-edit-user/
│               ├── UserForm.vue
│               └── openUserForm.ts

调用时从公共路径导入即可：

import { openConfirmDelete } from '@/components/modals/confirm-delete/openConfirmDelete';

Promise 化 vs 回调式

两种调用风格都支持，根据场景选择：

Promise 化（推荐）

适合简单的确认/表单场景，调用方代码更简洁：

const result = await openAddUser();
if (result) {
  // 处理成功逻辑
}

回调式

适合复杂场景（需要实时控制弹窗状态、loading 等）：

const modal = openModal({
  title: '新增',
  component: UserForm,
  onConfirm: async () => {
    modal.setConfirmLoading(true);
    try {
      await save();
      modal.close();
    } finally {
      modal.setConfirmLoading(false);
    }
  },
});

命名约定

三种内容模式

useModal 支持三种内容模式，按复杂度选择：

component 模式（最常用）

openModal({
  title: '新增用户',
  component: UserForm,
  componentProps: { mode: 'add' },
  onConfirm: async (data) => { /* ... */ },
});

config 模式（简单表单）

openModal({
  title: '新增产品',
  type: 'auto',
  config: [
    { prop: 'name', label: '产品名称', required: true, component: 'input' },
    { prop: 'categoryId', label: '类别', component: 'select', props: { options: categoryOptions } },
  ],
  modelValue: formData,
  onSubmitSuccess: (data) => { /* ... */ },
});

支持的组件类型：input、select、textarea（input + type）、switch、inputNumber、radioGroup、checkboxGroup、datePicker

检查清单

新增/重构弹窗时，确认以下几点：

1. ✅ 弹窗放在最近的业务归属目录下（页面内 modals/ 或 components/modals/）
2. ✅ 每个弹窗有自己的文件夹，包含 .vue 和 openXxx.ts
3. ✅ 主页面只导入 openXxx 函数，不直接引用弹窗组件
4. ✅ 表单数据类型从 Vue 组件导出，打开函数复用类型
5. ✅ 返回 Promise 的函数，取消/关闭时 resolve(null)