vibe_coding/docs/guides/ui-specs-admin.md

🖥️ UI 规范 — 管理端（Case-Database-Frontend-admin）

管理端设计规范。AI 在 Case-Database-Frontend-admin/ 中新建页面或组件时参考本文档。 核心原则：桌面优先、功能完整、Element Plus 标准优先

---

1. 设计系统

项目	选型
UI 组件库	Element Plus（优先使用标准组件，不自定义重复造轮子）
CSS 方案	Tailwind CSS（辅助布局，不覆盖 Element Plus 样式）
图标	Element Plus Icons（@element-plus/icons-vue）
字体	系统字体栈
布局框架	侧边导航 + 顶部栏 + 内容区（标准后台布局）

---

2. 色彩系统

:root {
  /* 主色（Element Plus 默认蓝） */
  --el-color-primary: #409EFF;

  /* 管理端背景层级 */
  --admin-bg-sidebar:  #001529;   /* 深色侧边栏 */
  --admin-bg-header:   #FFFFFF;   /* 白色顶栏 */
  --admin-bg-content:  #F0F2F5;   /* 内容区浅灰 */
  --admin-bg-card:     #FFFFFF;   /* 卡片/表格白 */

  /* 状态色 */
  --status-active:   #52C41A;  /* 启用/正常 */
  --status-inactive: #D9D9D9;  /* 停用/禁用 */
  --status-pending:  #FAAD14;  /* 待处理 */
  --status-danger:   #FF4D4F;  /* 危险/错误 */
}

Element Plus 主题色配置（src/styles/element-vars.scss）：

@forward 'element-plus/theme-chalk/src/common/var.scss' with (
  $colors: (
    'primary': ('base': #409EFF),
  )
);

---

3. 布局规范

整体框架

┌─────────────────────────────────────────────────────────┐
│  顶栏（60px 固定）：Logo + 面包屑 + 用户信息 + 通知     │
├──────────────┬──────────────────────────────────────────┤
│              │  内容区（padding: 16px）                  │
│  侧边栏      │  ┌──────────────────────────────────────┐ │
│  （220px）   │  │  页面标题 + 操作按钮（顶部工具栏）    │ │
│              │  ├──────────────────────────────────────┤ │
│  折叠后      │  │  主内容（表格/表单/卡片）             │ │
│  → 64px     │  │                                      │ │
│              │  └──────────────────────────────────────┘ │
└──────────────┴──────────────────────────────────────────┘

响应式

管理端以桌面端为主，但需支持：

• ≥ 1280px：完整布局（侧边栏展开）
• 1024px ~ 1279px：侧边栏折叠（64px 图标模式）
• < 1024px：侧边栏收起为抽屉（移动端兜底）

---

4. Element Plus 组件使用规范

数据表格（el-table）

<el-table
  v-loading="loading"
  :data="tableData"
  stripe
  border
  highlight-current-row
  style="width: 100%"
>
  <!-- 数据列 -->
  <el-table-column prop="id" label="ID" width="80" sortable />
  <el-table-column prop="name" label="名称" min-width="180" show-overflow-tooltip />
  
  <!-- 状态列（Tag） -->
  <el-table-column label="状态" width="100">
    <template #default="{ row }">
      <el-tag :type="row.status === 1 ? 'success' : 'danger'">
        {{ row.status === 1 ? '启用' : '停用' }}
      </el-tag>
    </template>
  </el-table-column>

  <!-- 操作列（固定右侧） -->
  <el-table-column label="操作" fixed="right" width="160">
    <template #default="{ row }">
      <el-button v-permission="'module:edit'" link type="primary" @click="handleEdit(row)">编辑</el-button>
      <el-popconfirm title="确定删除？" @confirm="handleDelete(row.id)">
        <template #reference>
          <el-button v-permission="'module:delete'" link type="danger">删除</el-button>
        </template>
      </el-popconfirm>
    </template>
  </el-table-column>
</el-table>

<!-- 分页（固定格式） -->
<el-pagination
  v-model:current-page="query.page"
  v-model:page-size="query.page_size"
  :page-sizes="[10, 20, 50, 100]"
  :total="total"
  layout="total, sizes, prev, pager, next, jumper"
  class="mt-4 justify-end"
  @change="fetchData"
/>

搜索表单

<!-- 搜索栏（折叠设计，超过 3 个条件可折叠） -->
<el-card class="mb-4" shadow="never">
  <el-form :model="query" inline @keyup.enter="handleSearch">
    <el-form-item label="关键词">
      <el-input v-model="query.keyword" placeholder="请输入" clearable style="width: 200px" />
    </el-form-item>
    <el-form-item>
      <el-button type="primary" @click="handleSearch">搜索</el-button>
      <el-button @click="handleReset">重置</el-button>
    </el-form-item>
  </el-form>
</el-card>

弹窗表单

<el-dialog v-model="dialogVisible" :title="isEdit ? '编辑' : '新建'" width="600px" @close="handleDialogClose">
  <el-form ref="formRef" :model="form" :rules="rules" label-width="80px">
    <el-form-item label="名称" prop="name">
      <el-input v-model="form.name" />
    </el-form-item>
  </el-form>
  <template #footer>
    <el-button @click="dialogVisible = false">取消</el-button>
    <el-button type="primary" :loading="submitting" @click="handleSubmit">确定</el-button>
  </template>
</el-dialog>

规则：

• 弹窗宽度：简单表单 500px，复杂表单 700-900px
• 弹窗关闭时必须调用 formRef.value?.resetFields()
• 提交按钮加 :loading 防重复提交

---

5. 页面标准结构

每个管理端页面遵循以下结构：

<template>
  <div class="admin-page">
    <!-- 页面头部：标题 + 主要操作按钮 -->
    <div class="mb-4 flex items-center justify-between">
      <h2 class="text-lg font-semibold text-gray-800">页面标题</h2>
      <el-button v-permission="'module:create'" type="primary" @click="handleCreate">
        <el-icon><Plus /></el-icon> 新建
      </el-button>
    </div>

    <!-- 搜索区 -->
    <!-- 表格区 -->
    <!-- 分页区 -->
    <!-- 弹窗区 -->
  </div>
</template>

<script setup>
// 1. 导入
// 2. 响应式状态
// 3. 表单/验证规则
// 4. 数据获取
// 5. 事件处理（CRUD）
// 6. 生命周期
</script>

---

6. 间距规范

场景	间距
内容区内边距	p-4（16px）
卡片间距	mb-4（16px）
表单项间距	Element Plus 默认（el-form 管理）
操作按钮间距	ml-2（8px，同行按钮）

---

7. 状态规范

状态	实现方式
加载中	v-loading="loading"（el-table、el-card）
空状态	el-empty（有描述、有图）
错误状态	el-result type="error"（提供重试按钮）
操作成功	ElMessage.success('操作成功')
操作失败	ElMessage.error(error.message)
危险操作确认	el-popconfirm（行内）/ ElMessageBox.confirm（批量）

---

最后更新: 2026-02-26