medical-mall/pages/mall/admin/docs/QUICK_REFERENCE.md

快速参考卡片 - CRMEB 设计系统

🎯 5 分钟快速入门

1. 文档位置

所有文档都在 docs/ 文件夹

2. 3 个必读文档

docs/
├── README.md                          ← 从这里开始！
├── STYLE_SPECIFICATION.md             ← 样式规范
└── PAGE_STRUCTURE_SPECIFICATION.md    ← 页面模板

3. 开发时遵循的 3 个原则

✅ 原则 1: 所有颜色使用 $color-* 变量
✅ 原则 2: 所有间距使用 $space-* 变量
✅ 原则 3: 所有样式都来自 uni.scss（禁止硬编码）

---

🎨 常用设计变量速查表

颜色变量

$primary-color: #1890ff        // 主交互色
$success-color: #52c41a        // 成功绿
$warning-color: #faad14        // 警告黄
$error-color: #ff4d4f          // 错误红

$text-primary: #000000         // 主文本
$text-secondary: #666666       // 次文本
$background-primary: #ffffff   // 主背景
$border-color: #d9d9d9         // 边框色

间距变量（4px 基准）

$space-xs: 4px      // 极小
$space-sm: 8px      // 小
$space: 12px        // 标准（最常用）
$space-md: 16px     // 中
$space-lg: 24px     // 大

其他常用变量

$radius-sm: 4px     // 按钮圆角
$radius: 6px        // 卡片圆角
$shadow: ...        // 标准阴影
$font-size: 14px    // 默认字体

---

📝 代码片段速查

使用颜色

.button {
  color: $text-primary; // ✅
  background: $primary-color; // ✅
  border: 1px solid $border-color; // ✅
}

使用间距

.card {
  padding: $space-md; // 16px
  margin-bottom: $space-lg; // 24px
  gap: $space-sm; // 8px
}

使用圆角

.button {
  border-radius: $radius-sm; // 4px
}

.card {
  border-radius: $radius; // 6px
}

.avatar {
  border-radius: $radius-full; // 9999px (圆形)
}

使用阴影

.card {
  box-shadow: $shadow; // 标准阴影
}

.modal {
  box-shadow: $shadow-lg; // 强阴影
}

---

🏗️ 页面结构快速模板

最小列表页

<template>
  <AdminLayout :currentPage="pageName">
    <!-- 标题 -->
    <view class="page-header">
      <text class="page-title">{{ title }}</text>
      <button class="btn btn-primary">新增</button>
    </view>

    <!-- 搜索 -->
    <view class="search-card">
      <input v-model="searchForm.keyword" class="input" placeholder="搜索..." />
      <button @click="handleSearch">搜索</button>
    </view>

    <!-- 列表 -->
    <view class="list-card">
      <view class="list-item" v-for="item in items" :key="item.id">
        {{ item.name }}
        <button @click="handleEdit(item)">编辑</button>
      </view>
    </view>

    <!-- 分页 -->
    <view class="pagination">
      <button @click="handlePrevPage">上一页</button>
      <text>第 {{ page }} 页</text>
      <button @click="handleNextPage">下一页</button>
    </view>
  </AdminLayout>
</template>

最小表单页

<template>
  <AdminLayout :currentPage="pageName">
    <view class="form-card">
      <view class="form-item">
        <label class="form-label">名称</label>
        <input v-model="form.name" class="input" />
      </view>
      <view class="form-item">
        <label class="form-label">描述</label>
        <textarea v-model="form.description" class="textarea" />
      </view>
      <view class="form-actions">
        <button class="btn btn-primary" @click="handleSubmit">保存</button>
        <button class="btn btn-default" @click="handleCancel">取消</button>
      </view>
    </view>
  </AdminLayout>
</template>

---

📦 组件库简化版

基础组件类别

类别	组件	用途
输入	Button, Input, Select, Checkbox, Radio	用户交互
容器	Card, Modal, Pagination	页面布局
表单	Form, FormItem, Upload	数据采集
展示	Table, List, Badge, Tag	数据展示
反馈	Message, Alert, Loading	用户反馈

最常用的 3 个组件

1. Button（按钮）

<Button type="primary" label="创建" @click="handleCreate" />
<Button type="default" label="编辑" />
<Button type="danger" :disabled="true" label="删除" />

2. Input（输入框）

<input v-model="value" class="input" placeholder="请输入" />

3. Modal（模态框）

<view v-if="visible" class="modal">
  <text>确定删除吗？</text>
  <button @click="handleConfirm">确定</button>
  <button @click="visible = false">取消</button>
</view>

---

✅ 代码审查检查清单（10 秒版）

发代码前，问自己：

• 有没有硬编码颜色值？ (应该用 $color-* 变量)
• 有没有硬编码尺寸？ (应该用 $space-* 变量)
• 有没有硬编码圆角？ (应该用 $radius-* 变量)
• 有没有 console.log？ (应该删除)
• 有没有测试通过？ (应该运行测试)
• 有没有写注释？ (复杂逻辑应该有注释)

如果都检查过了，可以提交 PR！

---

🚀 常见任务 (30 秒版)

任务 1: 添加一个新页面

1. 复制 docs/PAGE_STRUCTURE_SPECIFICATION.md 中的模板
2. 修改标题和字段
3. 替换 API 调用
4. 检查变量使用
5. 完成！

任务 2: 使用一个新颜色

1. 打开 uni.scss
2. 找 $color-* 或 $text-* 或 $background-*
3. 在样式中使用该变量
4. 完成！

任务 3: 调整间距

1. 打开 uni.scss
2. 找 $space-* 变量
3. 选择合适的间距级别
4. 完成！

---

📞 遇到问题？

Q: 我想要的颜色或尺寸没有预定义怎么办？

A:

1. 首先检查 uni.scss，看看有没有接近的
2. 如果真的没有，先用最接近的顶替
3. 然后提一个 Issue 讨论是否需要添加新的变量

Q: 能不能硬编码这个值？

A: 不能。所有值都应该来自变量。如果没有合适的变量，应该添加它。

Q: 页面结构能不能和模板不一样？

A: 尽量不要。统一的结构让用户体验更好，维护也更简单。

Q: 我想创建一个新组件，应该放在哪里？

A:

• 基础组件 → components/basic/
• 容器组件 → components/container/
• 表单组件 → components/form/
• 数据展示 → components/data/
• 反馈组件 → components/feedback/
• 导航组件 → components/navigation/

---

📚 详细文档

需要更多信息？查看完整文档：

需求	文档
整体了解	README.md
样式规范	STYLE_SPECIFICATION.md
页面模板	PAGE_STRUCTURE_SPECIFICATION.md
组件规范	COMPONENT_SPECIFICATION.md
工程规范	ENGINEERING_BEST_PRACTICES.md
项目计划	IMPLEMENTATION_ROADMAP.md

---

⚡ 速记

记住这 5 点：

1️⃣ 颜色来自变量    → $primary-color, $text-primary, ...
2️⃣ 间距来自变量    → $space, $space-md, ...
3️⃣ 圆角来自变量    → $radius, $radius-sm, ...
4️⃣ 页面遵循模板    → 使用 ListPage/FormPage/DetailPage 模板
5️⃣ 组件有分类      → 放在 basic/container/form/data/feedback/navigation

违反任何一条都需要代码审查！

---

🎯 下一步

1. 打开 docs/README.md 深入了解
2. 选择一个简单任务开始（如添加新页面）
3. 遵循规范编写代码
4. 提交 PR 进行审查
5. 完成！

---

创建日期: 2026-01-31
版本: 1.0
用时: 仅需 5-10 分钟阅读本卡片即可快速上手！