From 162b017b58effdc820ff2e8e30b1665622d6bc60 Mon Sep 17 00:00:00 2001
From: Leo <98382335+gaoziman@users.noreply.github.com>
Date: Tue, 8 Jul 2025 20:28:41 +0800
Subject: [PATCH] =?UTF-8?q?docs(project):=20=E6=96=B0=E5=A2=9E=E6=A0=87?=
 =?UTF-8?q?=E7=AD=BE=E7=BB=84=E4=BB=B6=E4=B8=BB=E9=A2=98=E8=89=B2=E7=BB=9F?=
 =?UTF-8?q?=E4=B8=80=E8=A7=84=E8=8C=83?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 新增标签组件主题色统一规范，确保与用户选择的系统主题色保持一致
- 规定所有标签必须使用 NTag 组件，严禁自定义标签样式
- 明确标签类型选择：主要标签使用 type: 'primary'，状态标签使用语义化颜色
- 详细说明 Naive UI 主题系统工作机制和动态主题色实现原理
- 提供完整的实现示例和验证标准
- 严格禁止自定义标签样式、固定颜色值等做法
---
 CLAUDE.md | 98 +++++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 95 insertions(+), 3 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 04c0bd7..7ca8111 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -346,7 +346,7 @@ coiMsgBox('确定要删除吗？', '删除确认').then(() => {
 - 小按钮：保持图标清晰可见
 
 **3. 图标样式要求**
-```vue
+```html
 <template #icon>
   <NIcon>
     <!-- 图标组件直接使用，无需额外样式 -->
@@ -752,7 +752,7 @@ const deleteDialogRef = ref()
 ```
 
 #### 3. 模板中使用
-```vue
+```html
 <template>
   <!-- 用户表单弹框示例 -->
   <CoiDialog
@@ -791,7 +791,6 @@ const deleteDialogRef = ref()
       </div>
     </template>
   </CoiDialog>
-</template>
 
   <!-- 禁用ESC键关闭的弹框示例 -->
   <CoiDialog
@@ -1107,6 +1106,99 @@ function renderStatus(row: UserVo) {
 
 **遵循此规范确保页面具有统一的视觉效果和良好的主题适配性！**
 
+## 🏷️ 标签组件主题色统一规范（强制要求）
+
+**所有新增的标签组件都必须严格遵循动态主题色统一原则，确保与用户选择的系统主题色保持一致**
+
+### 标签组件实现原则
+
+1. **强制使用 Naive UI 标准组件**：
+   - ✅ 必须使用 `NTag` 组件，严禁自定义标签样式
+   - ✅ 利用 Naive UI 的主题系统自动适配主题色
+   - ✅ 确保标签在所有主题切换时都能正确显示
+
+2. **正确的标签类型选择**：
+   - ✅ 主要标签使用 `type: 'primary'`（跟随系统主题色）
+   - ✅ 状态标签使用 `type: 'success' | 'warning' | 'error'`
+   - ✅ 信息标签使用 `type: 'info'`
+   - ❌ 严禁使用 `type: 'default'`（显示为白色背景，不符合主题）
+
+### 正确的标签实现方式
+
+**✅ 推荐实现（render函数中）**：
+```typescript
+// 文件后缀标签 - 使用主题色
+render: (row) => {
+  return h(NTag, {
+    type: 'primary', // 跟随系统主题色
+    size: 'small'
+  }, { default: () => row.fileSuffix?.toUpperCase() })
+}
+
+// 状态标签 - 使用语义化颜色
+render: (row) => {
+  const statusMap = {
+    active: { type: 'success', text: '启用' },
+    inactive: { type: 'error', text: '禁用' },
+    pending: { type: 'warning', text: '待审核' }
+  }
+  const config = statusMap[row.status]
+  return h(NTag, {
+    type: config.type,
+    size: 'small'
+  }, { default: () => config.text })
+}
+```
+
+**✅ 推荐实现（模板中）**：
+```vue
+<template>
+  <!-- 主要信息标签 -->
+  <NTag type="primary" size="small">
+    {{ data.code }}
+  </NTag>
+
+  <!-- 状态标签 -->
+  <NTag :type="getStatusType(data.status)" size="small">
+    {{ getStatusText(data.status) }}
+  </NTag>
+</template>
+```
+
+### 技术实现原理
+
+**Naive UI 主题系统工作机制**：
+1. `n-config-provider` 注入全局主题配置（`theme-overrides`）
+2. 主题配置来自 `appStore.theme.common.primaryColor`
+3. 用户选择主题色时，`setPrimaryColor()` 更新所有相关颜色变体
+4. 所有 `type: 'primary'` 的标签自动继承新的主题色
+5. 实现真正的动态主题色统一
+
+### 严格禁止的做法
+
+- ❌ 自定义标签样式：`class="custom-tag-style"`
+- ❌ 固定颜色值：`style="background-color: #18A058"`
+- ❌ 使用默认类型：`type: 'default'`
+- ❌ CSS变量覆盖：`style="--n-color: var(--primary-color)"`
+- ❌ 字符串返回：`return row.status`（应该返回标签组件）
+
+### 验证标准
+
+在添加新标签时，必须通过以下检查：
+- [ ] 标签在不同主题色下都能正确显示
+- [ ] 标签颜色与系统主题色保持一致
+- [ ] 标签在主题切换时能实时更新
+- [ ] 代码使用 Naive UI 标准组件和类型
+
+### 参考实现
+
+项目中的标准实现参考：
+- ✅ 角色管理页面：角色编码标签 `h(NTag, { type: 'primary', size: 'small' })`
+- ✅ 文件管理页面：文件后缀标签 `h(NTag, { type: 'primary', size: 'small' })`
+- ✅ 用户管理页面：用户状态标签 `h(NTag, { type: 'success/error', size: 'small' })`
+
+**遵循此规范确保所有标签组件都能与用户的主题色选择保持完美统一！** 🎨
+
 ## 📝 表单验证规范（强制要求）
 
 **所有包含表单提交的页面都必须实现统一的表单验证和错误处理机制**