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