docs(guide): 更新组件使用规范和开发指南
- 更新组件命名规范,从Nova前缀改为Coi前缀 - 完善CoiDialog组件使用文档和属性说明 - 新增ESC键关闭和遮罩层关闭功能的文档说明 - 更新图标使用规范中的示例代码 - 修正代码格式和注释规范 - 添加更完整的使用示例和最佳实践 文档改进: - 统一组件API文档格式 - 增强代码示例的可读性 - 完善属性和事件说明
This commit is contained in:
parent
8f8a416e88
commit
c0c092cfe6
88
CLAUDE.md
88
CLAUDE.md
@ -287,7 +287,7 @@ coiMsgBox('确定要删除吗?', '删除确认').then(() => {
|
|||||||
</NButton>
|
</NButton>
|
||||||
|
|
||||||
<!-- 在组件插槽中使用 -->
|
<!-- 在组件插槽中使用 -->
|
||||||
<NovaEmpty>
|
<CoiEmpty>
|
||||||
<template #action>
|
<template #action>
|
||||||
<NButton type="primary" round>
|
<NButton type="primary" round>
|
||||||
<template #icon>
|
<template #icon>
|
||||||
@ -298,7 +298,7 @@ coiMsgBox('确定要删除吗?', '删除确认').then(() => {
|
|||||||
新增数据
|
新增数据
|
||||||
</NButton>
|
</NButton>
|
||||||
</template>
|
</template>
|
||||||
</NovaEmpty>
|
</CoiEmpty>
|
||||||
</template>
|
</template>
|
||||||
```
|
```
|
||||||
|
|
||||||
@ -477,16 +477,16 @@ icon: () => h(NIcon, {}, { default: () => h('IconParkOutlineEdit') })
|
|||||||
|
|
||||||
```typescript
|
```typescript
|
||||||
// 操作类图标
|
// 操作类图标
|
||||||
import IconParkOutlineEdit from '~icons/icon-park-outline/edit' // 编辑
|
import IconParkOutlineEdit from '~icons/icon-park-outline/edit' // 编辑
|
||||||
import IconParkOutlineDelete from '~icons/icon-park-outline/delete' // 删除
|
import IconParkOutlineDelete from '~icons/icon-park-outline/delete' // 删除
|
||||||
import IconParkOutlineRefresh from '~icons/icon-park-outline/refresh' // 刷新/重置
|
import IconParkOutlineRefresh from '~icons/icon-park-outline/refresh' // 刷新/重置
|
||||||
import IconParkOutlineSetting from '~icons/icon-park-outline/setting' // 设置/分配
|
import IconParkOutlineSetting from '~icons/icon-park-outline/setting' // 设置/分配
|
||||||
|
|
||||||
// 功能类图标
|
// 功能类图标
|
||||||
import IconParkOutlinePlus from '~icons/icon-park-outline/plus' // 新增
|
import IconParkOutlinePlus from '~icons/icon-park-outline/plus' // 新增
|
||||||
import IconParkOutlineSearch from '~icons/icon-park-outline/search' // 搜索
|
import IconParkOutlineSearch from '~icons/icon-park-outline/search' // 搜索
|
||||||
import IconParkOutlineDownload from '~icons/icon-park-outline/download' // 下载/导出
|
import IconParkOutlineDownload from '~icons/icon-park-outline/download' // 下载/导出
|
||||||
import IconParkOutlineUpload from '~icons/icon-park-outline/upload' // 上传/导入
|
import IconParkOutlineUpload from '~icons/icon-park-outline/upload' // 上传/导入
|
||||||
import IconParkOutlinePreviewOpen from '~icons/icon-park-outline/preview-open' // 查看
|
import IconParkOutlinePreviewOpen from '~icons/icon-park-outline/preview-open' // 查看
|
||||||
```
|
```
|
||||||
|
|
||||||
@ -730,17 +730,17 @@ const searchForm = ref<UserSearchForm>({})
|
|||||||
|
|
||||||
## 🔥 自定义弹框组件规范(强制要求)
|
## 🔥 自定义弹框组件规范(强制要求)
|
||||||
|
|
||||||
**在开发任何新页面或功能时,如果需要使用弹框/模态框,必须使用项目封装的 NovaDialog 组件,严禁使用 Naive UI 原生的 n-modal 组件。**
|
**在开发任何新页面或功能时,如果需要使用弹框/模态框,必须使用项目封装的 CoiDialog 组件,严禁使用 Naive UI 原生的 n-modal 组件。**
|
||||||
|
|
||||||
### NovaDialog 组件位置
|
### CoiDialog 组件位置
|
||||||
- 组件文件:`src/components/common/NovaDialog.vue`
|
- 组件文件:`src/components/common/CoiDialog.vue`
|
||||||
- 这是项目专门封装的统一弹框组件
|
- 这是项目专门封装的统一弹框组件
|
||||||
|
|
||||||
### 使用方式
|
### 使用方式
|
||||||
|
|
||||||
#### 1. 导入组件
|
#### 1. 导入组件
|
||||||
```typescript
|
```typescript
|
||||||
import NovaDialog from '@/components/common/NovaDialog.vue'
|
import CoiDialog from '@/components/common/CoiDialog.vue'
|
||||||
```
|
```
|
||||||
|
|
||||||
#### 2. 创建弹框引用
|
#### 2. 创建弹框引用
|
||||||
@ -755,15 +755,15 @@ const deleteDialogRef = ref()
|
|||||||
```vue
|
```vue
|
||||||
<template>
|
<template>
|
||||||
<!-- 用户表单弹框示例 -->
|
<!-- 用户表单弹框示例 -->
|
||||||
<NovaDialog
|
<CoiDialog
|
||||||
ref="userDialogRef"
|
ref="userDialogRef"
|
||||||
:title="modalTitle"
|
:title="modalTitle"
|
||||||
:width="800"
|
:width="800"
|
||||||
height="auto"
|
height="auto"
|
||||||
confirm-text="确定"
|
confirm-text="确定"
|
||||||
cancel-text="取消"
|
cancel-text="取消"
|
||||||
@nova-confirm="handleSubmit"
|
@coi-confirm="handleSubmit"
|
||||||
@nova-cancel="handleCancel"
|
@coi-cancel="handleCancel"
|
||||||
>
|
>
|
||||||
<template #content>
|
<template #content>
|
||||||
<div class="px-3 py-2">
|
<div class="px-3 py-2">
|
||||||
@ -773,24 +773,42 @@ const deleteDialogRef = ref()
|
|||||||
</n-form>
|
</n-form>
|
||||||
</div>
|
</div>
|
||||||
</template>
|
</template>
|
||||||
</NovaDialog>
|
</CoiDialog>
|
||||||
|
|
||||||
<!-- 仅查看类弹框示例(无确认按钮) -->
|
<!-- 仅查看类弹框示例(无确认按钮) -->
|
||||||
<NovaDialog
|
<CoiDialog
|
||||||
ref="viewDialogRef"
|
ref="viewDialogRef"
|
||||||
title="查看详情"
|
title="查看详情"
|
||||||
:width="600"
|
:width="600"
|
||||||
height="auto"
|
height="auto"
|
||||||
cancel-text="关闭"
|
cancel-text="关闭"
|
||||||
:show-confirm="false"
|
:show-confirm="false"
|
||||||
@nova-cancel="handleClose"
|
@coi-cancel="handleClose"
|
||||||
>
|
>
|
||||||
<template #content>
|
<template #content>
|
||||||
<div class="p-3">
|
<div class="p-3">
|
||||||
<!-- 查看内容 -->
|
<!-- 查看内容 -->
|
||||||
</div>
|
</div>
|
||||||
</template>
|
</template>
|
||||||
</NovaDialog>
|
</CoiDialog>
|
||||||
|
</template>
|
||||||
|
|
||||||
|
<!-- 禁用ESC键关闭的弹框示例 -->
|
||||||
|
<CoiDialog
|
||||||
|
ref="criticalDialogRef"
|
||||||
|
title="重要操作确认"
|
||||||
|
:width="600"
|
||||||
|
:close-on-esc="false"
|
||||||
|
:mask-closable="false"
|
||||||
|
@coi-confirm="handleCriticalConfirm"
|
||||||
|
@coi-cancel="handleCriticalCancel"
|
||||||
|
>
|
||||||
|
<template #content>
|
||||||
|
<div class="p-3">
|
||||||
|
<p class="text-red-600">此操作不可逆,请谨慎操作!</p>
|
||||||
|
</div>
|
||||||
|
</template>
|
||||||
|
</CoiDialog>
|
||||||
</template>
|
</template>
|
||||||
```
|
```
|
||||||
|
|
||||||
@ -801,12 +819,12 @@ function handleAdd() {
|
|||||||
modalTitle.value = '新增用户'
|
modalTitle.value = '新增用户'
|
||||||
// 初始化表单数据
|
// 初始化表单数据
|
||||||
formData.value = { /* ... */ }
|
formData.value = { /* ... */ }
|
||||||
userDialogRef.value?.novaOpen()
|
userDialogRef.value?.coiOpen()
|
||||||
}
|
}
|
||||||
|
|
||||||
// 隐藏弹框
|
// 隐藏弹框
|
||||||
function handleCancel() {
|
function handleCancel() {
|
||||||
userDialogRef.value?.novaClose()
|
userDialogRef.value?.coiClose()
|
||||||
}
|
}
|
||||||
|
|
||||||
// 提交成功后关闭弹框
|
// 提交成功后关闭弹框
|
||||||
@ -814,7 +832,7 @@ async function handleSubmit() {
|
|||||||
try {
|
try {
|
||||||
await submitForm()
|
await submitForm()
|
||||||
coiMsgSuccess('操作成功')
|
coiMsgSuccess('操作成功')
|
||||||
userDialogRef.value?.novaClose()
|
userDialogRef.value?.coiClose()
|
||||||
}
|
}
|
||||||
catch (error) {
|
catch (error) {
|
||||||
coiMsgError('操作失败')
|
coiMsgError('操作失败')
|
||||||
@ -822,31 +840,33 @@ async function handleSubmit() {
|
|||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
### NovaDialog 核心属性
|
### CoiDialog 核心属性
|
||||||
|
|
||||||
| 属性 | 类型 | 默认值 | 说明 |
|
| 属性 | 类型 | 默认值 | 说明 |
|
||||||
|------|------|--------|------|
|
|------|------|--------|------|
|
||||||
| title | string | '' | 弹框标题 |
|
| title | string | '提示' | 弹框标题 |
|
||||||
| width | number | 500 | 弹框宽度(px) |
|
| width | number | 500 | 弹框宽度(px) |
|
||||||
| height | string | 'auto' | 弹框高度 |
|
| height | string | 'auto' | 弹框高度 |
|
||||||
| confirm-text | string | '确定' | 确认按钮文字 |
|
| confirm-text | string | '确定' | 确认按钮文字 |
|
||||||
| cancel-text | string | '取消' | 取消按钮文字 |
|
| cancel-text | string | '取消' | 取消按钮文字 |
|
||||||
| show-confirm | boolean | true | 是否显示确认按钮 |
|
| show-confirm | boolean | true | 是否显示确认按钮 |
|
||||||
| show-cancel | boolean | true | 是否显示取消按钮 |
|
| show-cancel | boolean | true | 是否显示取消按钮 |
|
||||||
|
| close-on-esc | boolean | true | ESC键关闭弹框 |
|
||||||
|
| mask-closable | boolean | false | 点击遮罩层关闭 |
|
||||||
|
|
||||||
### NovaDialog 核心事件
|
### CoiDialog 核心事件
|
||||||
|
|
||||||
| 事件 | 说明 |
|
| 事件 | 说明 |
|
||||||
|------|------|
|
|------|------|
|
||||||
| @nova-confirm | 点击确认按钮时触发 |
|
| @coi-confirm | 点击确认按钮时触发 |
|
||||||
| @nova-cancel | 点击取消按钮时触发 |
|
| @coi-cancel | 点击取消按钮时触发 |
|
||||||
|
|
||||||
### NovaDialog 核心方法
|
### CoiDialog 核心方法
|
||||||
|
|
||||||
| 方法 | 说明 |
|
| 方法 | 说明 |
|
||||||
|------|------|
|
|------|------|
|
||||||
| novaOpen() | 显示弹框 |
|
| coiOpen() | 显示弹框 |
|
||||||
| novaClose() | 隐藏弹框 |
|
| coiClose() | 隐藏弹框 |
|
||||||
|
|
||||||
### 插槽支持
|
### 插槽支持
|
||||||
|
|
||||||
@ -862,9 +882,9 @@ async function handleSubmit() {
|
|||||||
### 严格禁止行为
|
### 严格禁止行为
|
||||||
- ❌ 使用 `n-modal` 组件创建新弹框
|
- ❌ 使用 `n-modal` 组件创建新弹框
|
||||||
- ❌ 使用 `v-model:show` 控制弹框显示/隐藏
|
- ❌ 使用 `v-model:show` 控制弹框显示/隐藏
|
||||||
- ❌ 忽略 NovaDialog 组件直接使用原生弹框
|
- ❌ 忽略 CoiDialog 组件直接使用原生弹框
|
||||||
|
|
||||||
### 为什么必须使用 NovaDialog?
|
### 为什么必须使用 CoiDialog?
|
||||||
1. **统一用户体验**:确保所有弹框具有一致的视觉风格和交互行为
|
1. **统一用户体验**:确保所有弹框具有一致的视觉风格和交互行为
|
||||||
2. **维护便利性**:统一的组件便于后续样式调整和功能增强
|
2. **维护便利性**:统一的组件便于后续样式调整和功能增强
|
||||||
3. **团队协作**:统一的组件API减少开发人员的学习成本
|
3. **团队协作**:统一的组件API减少开发人员的学习成本
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user