275 lines
6.1 KiB
Plaintext
275 lines
6.1 KiB
Plaintext
---
|
||
alwaysApply: true
|
||
---
|
||
|
||
# CSS样式与UnoCSS使用规范
|
||
|
||
## 样式选择原则
|
||
|
||
### UnoCSS原子类使用规则
|
||
|
||
- **≤5个原子类**: 直接使用UnoCSS原子类
|
||
- **>5个原子类**: 必须提取为语义化CSS类，避免模板膨胀
|
||
|
||
```vue
|
||
<!-- ✅ 好的做法：5个以内原子类 -->
|
||
<view class="flex items-center p-20rpx text-center bg-white"></view>
|
||
```
|
||
|
||
### 优先使用UnoCSS预设shortcuts
|
||
|
||
参考 [unocss.config.ts](mdc:unocss.config.ts) 中定义的shortcuts：
|
||
|
||
```typescript
|
||
// 已定义的shortcuts，优先使用
|
||
"flex-center": "flex justify-center items-center"
|
||
"flex-start": "flex justify-start items-center"
|
||
"flex-between": "flex justify-between items-center"
|
||
"flex-col-center": "flex flex-col items-center"
|
||
```
|
||
|
||
## CSS类命名规范
|
||
|
||
### BEM命名规范
|
||
|
||
严格遵循BEM (Block\_\_Element--Modifier) 命名规范：
|
||
|
||
```scss
|
||
// Block: 独立的功能组件
|
||
.user-profile {
|
||
}
|
||
|
||
// Element: Block的子元素
|
||
.user-profile__avatar {
|
||
}
|
||
.user-profile__action {
|
||
}
|
||
.user-profile__badge {
|
||
}
|
||
|
||
// Modifier: Block或Element的状态/变体
|
||
.user-profile--dark {
|
||
}
|
||
.user-profile__action--active {
|
||
}
|
||
```
|
||
|
||
### 命名要求
|
||
|
||
1. **使用简短、易理解的英文单词**
|
||
2. **符合业务场景语义**
|
||
3. **避免缩写，除非是通用缩写**
|
||
|
||
```scss
|
||
// ✅ 好的命名
|
||
.user-profile__action
|
||
.stats-card
|
||
.service-icon
|
||
.tool-item
|
||
|
||
// ❌ 坏的命名
|
||
.up-act
|
||
.sc
|
||
.si
|
||
.ti
|
||
```
|
||
|
||
## 样式组织原则
|
||
|
||
### 1. 复用性判断
|
||
|
||
- 同一组合在项目中出现 >3次 → 提取为语义化类
|
||
- 具备明确语义的区域 → 提取为语义化类
|
||
- 需要主题适配的样式 → 提取为语义化类
|
||
|
||
### 2. 常用组合添加到shortcuts
|
||
|
||
当发现重复的原子类组合时，添加到 [unocss.config.ts](mdc:unocss.config.ts)：
|
||
|
||
```typescript
|
||
shortcuts: [
|
||
{
|
||
// 现有shortcuts...
|
||
|
||
// 新增常用组合
|
||
"card-container": "mx-30rpx my-20rpx bg-white rounded-16rpx shadow-sm",
|
||
"action-button": "flex-center w-70rpx h-70rpx bg-white bg-opacity-90 rounded-full",
|
||
},
|
||
];
|
||
```
|
||
|
||
### 3. 主题适配
|
||
|
||
使用wot-design-uni的CSS变量或自定义变量：
|
||
|
||
```scss
|
||
// ✅ 使用主题变量
|
||
.service-icon {
|
||
background-color: var(--wot-color-bg-light, #f3f4f6);
|
||
}
|
||
|
||
// ✅ 响应式主题色
|
||
:color="themeStore.isDark ? '#fff' : '#333'";
|
||
```
|
||
|
||
### 4. 暗黑模式适配规则
|
||
|
||
#### 优先级顺序
|
||
|
||
1. **优先使用wot-design-uni内置变量** - 自动适配暗黑模式
|
||
2. **使用项目 [theme.scss](mdc:src/styles/theme.scss) 定义的变量** - 统一管理主题色
|
||
3. **最后考虑组件内部定义** - 仅用于特殊场景
|
||
|
||
#### 自定义主题变量定义
|
||
|
||
当需要自定义颜色时，必须在 [theme.scss](mdc:src/styles/theme.scss) 中定义：
|
||
|
||
```scss
|
||
/* 在 theme.scss 中添加自定义变量 */
|
||
:root,
|
||
page {
|
||
--custom-text-color: #333333;
|
||
--custom-bg-color: #ffffff;
|
||
--custom-border-color: #e5e7eb;
|
||
}
|
||
|
||
.wot-theme-dark {
|
||
--custom-text-color: #ffffff;
|
||
--custom-bg-color: #1a1a1a;
|
||
--custom-border-color: #374151;
|
||
}
|
||
```
|
||
|
||
#### 组件中使用主题变量
|
||
|
||
```scss
|
||
// ✅ 推荐：使用wot内置变量
|
||
.my-component {
|
||
background-color: var(--wot-card-bg);
|
||
color: var(--wot-color-text);
|
||
}
|
||
|
||
// ✅ 推荐：使用theme.scss定义的变量
|
||
.my-component {
|
||
background-color: var(--custom-bg-color);
|
||
border-color: var(--custom-border-color);
|
||
}
|
||
|
||
// ❌ 避免：组件内部硬编码暗黑模式
|
||
.my-component {
|
||
background-color: #ffffff;
|
||
}
|
||
.wot-theme-dark .my-component {
|
||
background-color: #1a1a1a;
|
||
}
|
||
```
|
||
|
||
#### 图标和文字颜色适配
|
||
|
||
```vue
|
||
<template>
|
||
<!-- ✅ 推荐：使用计算属性适配 -->
|
||
<wd-icon :color="iconColor" />
|
||
|
||
<!-- ✅ 推荐：使用CSS变量 -->
|
||
<text style="color: var(--wot-color-text)">文本</text>
|
||
</template>
|
||
|
||
<script setup>
|
||
// 图标颜色适配
|
||
const iconColor = computed(() => (themeStore.isDark ? "#ffffff" : "#333333"));
|
||
</script>
|
||
```
|
||
|
||
## 实践示例
|
||
|
||
### 数据统计卡片
|
||
|
||
```vue
|
||
<!-- 使用wot组件 + 少量原子类 -->
|
||
<wd-card custom-class="mx-30rpx my-20rpx">
|
||
<wd-grid :column="3" border>
|
||
<wd-grid-item class="flex-col-center py-20rpx">
|
||
<view class="text-36rpx font-600">0.00</view>
|
||
<view class="text-26rpx text-gray-500">我的余额</view>
|
||
</wd-grid-item>
|
||
</wd-grid>
|
||
</wd-card>
|
||
```
|
||
|
||
### 用户操作按钮
|
||
|
||
```vue
|
||
<template>
|
||
<view class="user-profile__action" @click="handleClick">
|
||
<wd-icon name="setting1" :color="iconColor" />
|
||
</view>
|
||
</template>
|
||
|
||
<style scoped>
|
||
.user-profile__action {
|
||
display: flex;
|
||
align-items: center;
|
||
justify-content: center;
|
||
width: 70rpx;
|
||
height: 70rpx;
|
||
background-color: rgba(255, 255, 255, 0.9);
|
||
border-radius: 50%;
|
||
}
|
||
</style>
|
||
```
|
||
|
||
## 禁止项
|
||
|
||
❌ **不要在SCSS中重复定义UnoCSS已提供的工具类**
|
||
❌ **不要使用 `@apply` 指令**
|
||
❌ **不要把一次性样式放到全局**
|
||
❌ **不要使用非语义化的类名**
|
||
❌ **不要在模板中堆叠超过5个原子类**
|
||
❌ **不要混用UnoCSS原子类和自定义CSS类** - 一个元素应该只使用原子类或只使用自定义类，避免样式管理混乱
|
||
|
||
### 混用问题示例
|
||
|
||
```vue
|
||
<!-- ❌ 错误：混用原子类和自定义类 -->
|
||
<view class="flex-col-center py-20rpx tool-item">内容</view>
|
||
<wd-card custom-class="mx-30rpx my-20rpx stats-card">内容</wd-card>
|
||
|
||
<!-- ✅ 正确：只使用原子类（≤5个） -->
|
||
<view class="flex-col-center py-20rpx">内容</view>
|
||
|
||
<!-- ✅ 正确：只使用自定义类 -->
|
||
<view class="tool-item">内容</view>
|
||
<wd-card custom-class="stats-card">内容</wd-card>
|
||
```
|
||
|
||
### 解决方案
|
||
|
||
当需要混用时，选择以下方案之一：
|
||
|
||
1. **原子类数量≤5个**：移除自定义类，只使用原子类
|
||
2. **原子类数量>5个**：将所有样式合并到自定义类中
|
||
3. **语义明确的区域**：优先使用自定义类，将原子类样式合并进去
|
||
|
||
## 组件库样式覆盖
|
||
|
||
使用wot-design-uni组件时：
|
||
|
||
- 使用 `custom-class` 传入类名
|
||
- 使用 `:deep()` 进行样式穿透
|
||
- 添加 `!important` 提升优先级
|
||
|
||
```vue
|
||
<wd-button custom-class="logout-button" @click="logout">
|
||
退出登录
|
||
</wd-button>
|
||
|
||
<style scoped>
|
||
:deep(.logout-button) {
|
||
width: 100% !important;
|
||
height: 80rpx !important;
|
||
border-radius: 40rpx !important;
|
||
}
|
||
</style>
|
||
```
|