CSS 编码规范

概述

本项目基于 UniApp + Vue3 + TypeScript + UnoCSS 技术栈，采用现代化的CSS开发方式。本规范旨在确保代码的一致性、可维护性和可读性。

技术栈

CSS预处理器: SCSS/Sass
原子化CSS: UnoCSS
UI组件库: Wot Design Uni
代码格式化: Prettier
代码检查: ESLint

代码格式规范

基本格式

scss

// ✅ 正确示例
.component-name {
  display: flex;
  justify-content: center;
  align-items: center;
  padding: 20rpx;
  margin: 10rpx 0;
  background-color: #ffffff;
  border-radius: 8rpx;

  &:hover {
    background-color: #f5f5f5;
  }

  .child-element {
    font-size: 28rpx;
    color: #333333;
  }
}

Prettier 配置规范

项目使用以下 Prettier 配置：

行宽: 100字符
缩进: 2个空格
分号: 不使用分号
引号: 单引号
尾随逗号: ES5标准
括号间距: 保留空格

命名规范

类名命名

采用 BEM (Block Element Modifier) 命名方法论：

scss

// ✅ 正确示例
.goods-list {
  // Block
  .goods-item {
    // Element
    &--featured {
      // Modifier
      border: 2rpx solid #007aff;
    }

    &__title {
      // Element
      font-size: 32rpx;
      font-weight: bold;
    }

    &__price {
      // Element
      color: #ff4757;

      &--discount {
        // Modifier
        text-decoration: line-through;
      }
    }
  }
}

变量命名

使用语义化的变量名：

scss

// ✅ 正确示例
$primary-color: #007aff;
$success-color: #4cd964;
$warning-color: #f0ad4e;
$error-color: #dd524d;

$text-color-primary: #333333;
$text-color-secondary: #999999;
$text-color-placeholder: #808080;

$spacing-xs: 8rpx;
$spacing-sm: 16rpx;
$spacing-md: 24rpx;
$spacing-lg: 32rpx;
$spacing-xl: 48rpx;

UnoCSS 原子化CSS规范

基本使用

优先使用 UnoCSS 原子化类名：

vue

<template>
  <!-- ✅ 推荐：使用原子化类名 -->
  <view class="flex justify-center items-center p-4 bg-white rounded-lg">
    <text class="text-lg font-bold text-gray-800">标题</text>
  </view>

  <!-- ❌ 避免：过度使用自定义样式 -->
  <view class="custom-container">
    <text class="custom-title">标题</text>
  </view>
</template>

响应式设计

使用 UnoCSS 的响应式前缀：

vue

<template>
  <view class="w-full sm:w-1/2 md:w-1/3 lg:w-1/4">
    <!-- 响应式宽度 -->
  </view>
</template>

自定义快捷方式

项目中定义的快捷方式：

scss

// 已定义的快捷方式
.center {
  @apply flex justify-center items-center;
}

// 安全区域适配
.p-safe {
  padding: env(safe-area-inset-top) env(safe-area-inset-right) env(safe-area-inset-bottom)
    env(safe-area-inset-left);
}

.pt-safe {
  padding-top: env(safe-area-inset-top);
}

.pb-safe {
  padding-bottom: env(safe-area-inset-bottom);
}

SCSS 编写规范

文件组织

scss

// 1. 导入外部依赖
@import '@/style/variables.scss';
@import '@/style/mixins.scss';

// 2. 变量定义
$component-bg: #ffffff;
$component-padding: 20rpx;

// 3. 混合器定义
@mixin button-style($bg-color, $text-color) {
  background-color: $bg-color;
  color: $text-color;
  border-radius: 8rpx;
  padding: 16rpx 32rpx;
}

// 4. 主要样式
.component {
  // 样式规则
}

嵌套规范

嵌套层级不超过 3 层
合理使用 & 符号

scss

// ✅ 正确示例
.card {
  padding: 20rpx;
  background: #fff;

  &:hover {
    box-shadow: 0 4rpx 12rpx rgba(0, 0, 0, 0.1);
  }

  .card-header {
    margin-bottom: 16rpx;

    .card-title {
      font-size: 32rpx;
      font-weight: bold;
    }
  }
}

颜色规范

主题色彩

使用项目定义的颜色变量：

scss

// 主色调
$uni-color-primary: #007aff; // 主题蓝
$uni-color-success: #4cd964; // 成功绿
$uni-color-warning: #f0ad4e; // 警告橙
$uni-color-error: #dd524d; // 错误红

// 文字颜色
$uni-text-color: #333333; // 主文字
$uni-text-color-grey: #999999; // 辅助文字
$uni-text-color-placeholder: #808080; // 占位文字

// 背景颜色
$uni-bg-color: #ffffff; // 主背景
$uni-bg-color-grey: #f8f8f8; // 灰色背景
$uni-bg-color-hover: #f1f1f1; // 悬停背景

UnoCSS 主题色

vue

<template>
  <!-- 使用主题色 -->
  <view class="bg-primary text-white">主题色背景</view>
  <text class="text-primary">主题色文字</text>
</template>

尺寸规范

单位使用

移动端: 优先使用 rpx（响应式像素）
Web端: 可使用 px、rem、em
百分比: 用于响应式布局

scss

// ✅ 正确示例
.mobile-component {
  width: 750rpx; // 移动端宽度
  height: 200rpx; // 移动端高度
  font-size: 28rpx; // 移动端字体
  padding: 20rpx 30rpx; // 移动端内边距
}

.web-component {
  width: 100%; // 响应式宽度
  max-width: 1200px; // 最大宽度限制
  font-size: 1rem; // Web端字体
  padding: 1rem 1.5rem; // Web端内边距
}

间距规范

使用统一的间距系统：

scss

// 间距变量
$spacing-xs: 8rpx;    // 极小间距
$spacing-sm: 16rpx;   // 小间距
$spacing-md: 24rpx;   // 中等间距
$spacing-lg: 32rpx;   // 大间距
$spacing-xl: 48rpx;   // 超大间距

// UnoCSS 间距类
.p-2  // padding: 8rpx
.p-4  // padding: 16rpx
.p-6  // padding: 24rpx
.p-8  // padding: 32rpx
.p-12 // padding: 48rpx

组件样式规范

Vue 单文件组件

vue

<template>
  <view class="component-container">
    <view class="component-header">
      <text class="component-title">标题</text>
    </view>
    <view class="component-content">
      <!-- 内容 -->
    </view>
  </view>
</template>

<style lang="scss" scoped>
// 使用 scoped 避免样式污染
.component-container {
  padding: 20rpx;
  background: #fff;
  border-radius: 12rpx;

  .component-header {
    margin-bottom: 16rpx;
    border-bottom: 1rpx solid #eee;
    padding-bottom: 12rpx;

    .component-title {
      font-size: 32rpx;
      font-weight: bold;
      color: $uni-text-color;
    }
  }

  .component-content {
    line-height: 1.6;
    color: $uni-text-color-grey;
  }
}
</style>

全局样式

scss

// src/style/index.scss
// 全局重置样式
* {
  box-sizing: border-box;
}

// 全局工具类
.text-ellipsis {
  overflow: hidden;
  text-overflow: ellipsis;
  white-space: nowrap;
}

.text-ellipsis-2 {
  display: -webkit-box;
  -webkit-box-orient: vertical;
  -webkit-line-clamp: 2;
  overflow: hidden;
}

// 全局动画
.fade-enter-active,
.fade-leave-active {
  transition: opacity 0.3s ease;
}

.fade-enter-from,
.fade-leave-to {
  opacity: 0;
}

性能优化

CSS 优化建议

避免深层嵌套: 控制选择器嵌套层级
合理使用原子化CSS: 减少重复样式
按需引入: 只引入需要的样式文件
使用CSS变量: 便于主题切换和维护

scss

// ✅ 推荐：使用CSS变量
:root {
  --primary-color: #007aff;
  --text-color: #333333;
  --bg-color: #ffffff;
}

.component {
  color: var(--text-color);
  background: var(--bg-color);
}

兼容性处理

多端适配

scss

// 条件编译处理不同平台
/* #ifdef H5 */
.h5-only {
  // H5 特有样式
}
/* #endif */

/* #ifdef MP-WEIXIN */
.mp-weixin-only {
  // 微信小程序特有样式
}
/* #endif */

/* #ifdef APP-PLUS */
.app-only {
  // App 特有样式
}
/* #endif */

安全区域适配

scss

// 使用安全区域变量
.safe-area-container {
  padding-top: env(safe-area-inset-top);
  padding-bottom: env(safe-area-inset-bottom);
}

代码检查

ESLint 规则

项目配置了以下CSS相关的ESLint规则：

格式化CSS、SCSS文件
检查HTML文件格式
与Prettier集成确保代码风格一致

提交前检查

使用 lint-staged 在提交前自动格式化：

json

{
  "lint-staged": {
    "*": "eslint --fix"
  }
}

最佳实践

优先使用原子化CSS: 减少自定义样式，提高开发效率
保持样式简洁: 避免过度设计和复杂的样式规则
使用语义化命名: 让代码更易读和维护
合理组织文件: 按功能模块组织样式文件
注重性能: 避免不必要的样式计算和重绘
保持一致性: 遵循团队约定的编码规范

工具推荐

VS Code插件:
- UnoCSS
- SCSS IntelliSense
- Prettier
- ESLint
浏览器工具:
- Chrome DevTools
- Vue DevTools

CSS 编码规范 ​

概述 ​

技术栈 ​

代码格式规范 ​

基本格式 ​

Prettier 配置规范 ​

命名规范 ​

类名命名 ​

变量命名 ​

UnoCSS 原子化CSS规范 ​

基本使用 ​

响应式设计 ​

自定义快捷方式 ​

SCSS 编写规范 ​

文件组织 ​

嵌套规范 ​

颜色规范 ​

主题色彩 ​

UnoCSS 主题色 ​

尺寸规范 ​

单位使用 ​

间距规范 ​

组件样式规范 ​

Vue 单文件组件 ​

全局样式 ​

性能优化 ​

CSS 优化建议 ​

兼容性处理 ​

多端适配 ​

安全区域适配 ​

代码检查 ​

ESLint 规则 ​

提交前检查 ​

最佳实践 ​

工具推荐 ​

CSS 编码规范

概述

技术栈

代码格式规范

基本格式

Prettier 配置规范

命名规范

类名命名

变量命名

UnoCSS 原子化CSS规范

基本使用

响应式设计

自定义快捷方式

SCSS 编写规范

文件组织

嵌套规范

颜色规范

主题色彩

UnoCSS 主题色

尺寸规范

单位使用

间距规范

组件样式规范

Vue 单文件组件

全局样式

性能优化

CSS 优化建议

兼容性处理

多端适配

安全区域适配

代码检查

ESLint 规则

提交前检查

最佳实践

工具推荐