docs(guide): 更新组件使用规范和开发指南

- 更新组件命名规范,从Nova前缀改为Coi前缀
- 完善CoiDialog组件使用文档和属性说明
- 新增ESC键关闭和遮罩层关闭功能的文档说明
- 更新图标使用规范中的示例代码
- 修正代码格式和注释规范
- 添加更完整的使用示例和最佳实践

文档改进:
- 统一组件API文档格式
- 增强代码示例的可读性
- 完善属性和事件说明
This commit is contained in:
Leo 2025-07-07 15:55:35 +08:00
parent 8f8a416e88
commit c0c092cfe6

View File

@ -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减少开发人员的学习成本