docs(claude): 新增 NovaDialog 自定义弹框组件使用规范
- 在 CLAUDE.md 中新增自定义弹框组件使用规范 - 明确禁止使用原生 n-modal，强制使用 NovaDialog - 提供完整的使用指南和代码示例 - 详细说明组件属性、事件、方法和插槽 - 列出已完成集成的页面作为参考 - 修复文档中 Vue 模板语法引起的 ESLint 错误 - 确保后续开发严格遵循统一的弹框使用规范
This commit is contained in:
Leo
parent
7c503b096e
commit
6b04e80d41
172
CLAUDE.md
172
CLAUDE.md
@ -406,6 +406,178 @@ const searchForm = ref<UserSearchForm>({})
|
|||||||
2. 自定义组件放在 `src/components/` 下
|
2. 自定义组件放在 `src/components/` 下
|
||||||
3. 使用TypeScript定义组件Props和Emits
|
3. 使用TypeScript定义组件Props和Emits
|
||||||
|
|
||||||
|
## 🔥 自定义弹框组件规范（强制要求）
|
||||||
|
|
||||||
|
**在开发任何新页面或功能时，如果需要使用弹框/模态框，必须使用项目封装的 NovaDialog 组件，严禁使用 Naive UI 原生的 n-modal 组件。**
|
||||||
|
|
||||||
|
### NovaDialog 组件位置
|
||||||
|
- 组件文件：`src/components/common/NovaDialog.vue`
|
||||||
|
- 这是项目专门封装的统一弹框组件
|
||||||
|
|
||||||
|
### 使用方式
|
||||||
|
|
||||||
|
#### 1. 导入组件
|
||||||
|
```typescript
|
||||||
|
import NovaDialog from '@/components/common/NovaDialog.vue'
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 2. 创建弹框引用
|
||||||
|
```typescript
|
||||||
|
// 为每个弹框创建独立的引用
|
||||||
|
const userDialogRef = ref()
|
||||||
|
const editDialogRef = ref()
|
||||||
|
const deleteDialogRef = ref()
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 3. 模板中使用
|
||||||
|
```vue
|
||||||
|
<template>
|
||||||
|
<!-- 用户表单弹框示例 -->
|
||||||
|
<NovaDialog
|
||||||
|
ref="userDialogRef"
|
||||||
|
:title="modalTitle"
|
||||||
|
:width="800"
|
||||||
|
height="auto"
|
||||||
|
confirm-text="确定"
|
||||||
|
cancel-text="取消"
|
||||||
|
@nova-confirm="handleSubmit"
|
||||||
|
@nova-cancel="handleCancel"
|
||||||
|
>
|
||||||
|
<template #content>
|
||||||
|
<div class="px-3 py-2">
|
||||||
|
<!-- 弹框内容 -->
|
||||||
|
<n-form ref="formRef" :model="formData">
|
||||||
|
<!-- 表单内容 -->
|
||||||
|
</n-form>
|
||||||
|
</div>
|
||||||
|
</template>
|
||||||
|
</NovaDialog>
|
||||||
|
|
||||||
|
<!-- 仅查看类弹框示例（无确认按钮） -->
|
||||||
|
<NovaDialog
|
||||||
|
ref="viewDialogRef"
|
||||||
|
title="查看详情"
|
||||||
|
:width="600"
|
||||||
|
height="auto"
|
||||||
|
cancel-text="关闭"
|
||||||
|
:show-confirm="false"
|
||||||
|
@nova-cancel="handleClose"
|
||||||
|
>
|
||||||
|
<template #content>
|
||||||
|
<div class="p-3">
|
||||||
|
<!-- 查看内容 -->
|
||||||
|
</div>
|
||||||
|
</template>
|
||||||
|
</NovaDialog>
|
||||||
|
</template>
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 4. 控制弹框显示/隐藏
|
||||||
|
```typescript
|
||||||
|
// 显示弹框
|
||||||
|
function handleAdd() {
|
||||||
|
modalTitle.value = '新增用户'
|
||||||
|
// 初始化表单数据
|
||||||
|
formData.value = { /* ... */ }
|
||||||
|
userDialogRef.value?.novaOpen()
|
||||||
|
}
|
||||||
|
|
||||||
|
// 隐藏弹框
|
||||||
|
function handleCancel() {
|
||||||
|
userDialogRef.value?.novaClose()
|
||||||
|
}
|
||||||
|
|
||||||
|
// 提交成功后关闭弹框
|
||||||
|
async function handleSubmit() {
|
||||||
|
try {
|
||||||
|
await submitForm()
|
||||||
|
coiMsgSuccess('操作成功')
|
||||||
|
userDialogRef.value?.novaClose()
|
||||||
|
} catch (error) {
|
||||||
|
coiMsgError('操作失败')
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### NovaDialog 核心属性
|
||||||
|
|
||||||
|
| 属性 | 类型 | 默认值 | 说明 |
|
||||||
|
|------|------|--------|------|
|
||||||
|
| title | string | '' | 弹框标题 |
|
||||||
|
| width | number | 500 | 弹框宽度(px) |
|
||||||
|
| height | string | 'auto' | 弹框高度 |
|
||||||
|
| confirm-text | string | '确定' | 确认按钮文字 |
|
||||||
|
| cancel-text | string | '取消' | 取消按钮文字 |
|
||||||
|
| show-confirm | boolean | true | 是否显示确认按钮 |
|
||||||
|
| show-cancel | boolean | true | 是否显示取消按钮 |
|
||||||
|
|
||||||
|
### NovaDialog 核心事件
|
||||||
|
|
||||||
|
| 事件 | 说明 |
|
||||||
|
|------|------|
|
||||||
|
| @nova-confirm | 点击确认按钮时触发 |
|
||||||
|
| @nova-cancel | 点击取消按钮时触发 |
|
||||||
|
|
||||||
|
### NovaDialog 核心方法
|
||||||
|
|
||||||
|
| 方法 | 说明 |
|
||||||
|
|------|------|
|
||||||
|
| novaOpen() | 显示弹框 |
|
||||||
|
| novaClose() | 隐藏弹框 |
|
||||||
|
|
||||||
|
### 插槽支持
|
||||||
|
|
||||||
|
| 插槽 | 说明 |
|
||||||
|
|------|------|
|
||||||
|
| #header | 自定义弹框头部内容 |
|
||||||
|
| #content | 弹框主体内容（必需） |
|
||||||
|
|
||||||
|
### 已完成的集成示例
|
||||||
|
- ✅ 角色管理页面：`src/views/system/role/index.vue`
|
||||||
|
- ✅ 用户管理页面：`src/views/system/user/index.vue`
|
||||||
|
|
||||||
|
### 严格禁止行为
|
||||||
|
- ❌ 使用 `n-modal` 组件创建新弹框
|
||||||
|
- ❌ 使用 `v-model:show` 控制弹框显示/隐藏
|
||||||
|
- ❌ 忽略 NovaDialog 组件直接使用原生弹框
|
||||||
|
|
||||||
|
### 为什么必须使用 NovaDialog？
|
||||||
|
1. **统一用户体验**：确保所有弹框具有一致的视觉风格和交互行为
|
||||||
|
2. **维护便利性**：统一的组件便于后续样式调整和功能增强
|
||||||
|
3. **团队协作**：统一的组件API减少开发人员的学习成本
|
||||||
|
4. **质量保证**：封装的组件经过充分测试，避免重复开发和潜在bug
|
||||||
|
|
||||||
|
## 📝 Vue3组件文件结构规范（强制要求）
|
||||||
|
|
||||||
|
**所有Vue3组件必须严格按照以下顺序组织代码块**
|
||||||
|
|
||||||
|
### 组件代码块排布顺序
|
||||||
|
```vue
|
||||||
|
<script setup lang="ts">
|
||||||
|
// 脚本内容
|
||||||
|
</script>
|
||||||
|
|
||||||
|
<template>
|
||||||
|
<!-- 模板内容 -->
|
||||||
|
</template>
|
||||||
|
|
||||||
|
<style scoped>
|
||||||
|
/* 样式内容 */
|
||||||
|
</style>
|
||||||
|
```
|
||||||
|
|
||||||
|
### 强制要求
|
||||||
|
- ✅ 必须按照 `template` → `script` → `style` 的顺序排布
|
||||||
|
- ✅ 使用 `<script setup lang="ts">` 语法
|
||||||
|
- ✅ 样式块使用 `scoped` 属性确保样式隔离
|
||||||
|
- ✅ 每个代码块之间保持一个空行间隔
|
||||||
|
|
||||||
|
### 严格禁止行为
|
||||||
|
- ❌ 任何其他顺序的代码块排布
|
||||||
|
- ❌ 使用 `<script>` 而非 `<script setup>`
|
||||||
|
- ❌ 省略 `lang="ts"` 属性
|
||||||
|
- ❌ 在全局组件中省略 `scoped` 属性
|
||||||
|
|
||||||
## 文档资源
|
## 文档资源
|
||||||
|
|
||||||
项目包含完整的文档系统：
|
项目包含完整的文档系统：
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user