From c0c092cfe67b4f119b4b3565e9cb606aafed6721 Mon Sep 17 00:00:00 2001
From: Leo <98382335+gaoziman@users.noreply.github.com>
Date: Mon, 7 Jul 2025 15:55:35 +0800
Subject: [PATCH] =?UTF-8?q?docs(guide):=20=E6=9B=B4=E6=96=B0=E7=BB=84?=
 =?UTF-8?q?=E4=BB=B6=E4=BD=BF=E7=94=A8=E8=A7=84=E8=8C=83=E5=92=8C=E5=BC=80?=
 =?UTF-8?q?=E5=8F=91=E6=8C=87=E5=8D=97?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

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

文档改进：
- 统一组件API文档格式
- 增强代码示例的可读性
- 完善属性和事件说明
---
 CLAUDE.md | 112 ++++++++++++++++++++++++++++++++----------------------
 1 file changed, 66 insertions(+), 46 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 4cdc19c..da46da1 100644
--- a/CLAUDE.md
+++ b/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减少开发人员的学习成本