---
description: uvue CSS (ucss) 规则文档
globs: **/*.uvue, **/*.css, **/*.scss
alwaysApply: false
---

# uvue CSS (ucss) 规则文档

一套简洁、可执行的 CSS 规则，用于在 **uni-app x** 开发中编写 **uvue** 文件的样式。

---

## 1. 概述

uvue 使用一个受限的 CSS 子集，称为 **ucss**。
它确保在 **App（原生）、Web 和小程序** 之间保持一致的行为。

核心特性：
- **仅支持类选择器**
- **不支持样式继承**
- **Flex 优先布局**
- **跨平台 CSS 重置**
- **原生端可预测渲染**

---

## 2. 选择器规则

### 允许使用
- **仅限类选择器**

```css
.container { padding: 16px; }
.title { font-size: 18px; }
```

### 禁止使用

| 类型 | 示例 |
|------|------|
| 标签选择器 | `view {}` |
| ID 选择器 | `#box {}` |
| 属性选择器 | `[type=primary] {}` |
| 伪类选择器 | `:hover`, `:active` |
| 后代选择器 | `.a .b {}` |

---

## 3. 继承规则

ucss **不支持** 样式继承。

❌ 错误写法：
```css
.parent { font-size: 20px; color: red; }
```

✅ 正确写法：
```css
.text { font-size: 20px; color: red; }
```

---

## 4. 布局规则

### Flex 优先
始终指定方向：
```css
.row { display: flex; flex-direction: row; }
.col { display: flex; flex-direction: column; }
```

### 滚动行为
uvue 页面默认**不滚动**。需要滚动时，使用 `<scroll-view>` 包裹内容。

---

## 5. CSS 重置差异（重要）

| 属性 | Web 默认值 | ucss 默认值 |
|------|------------|-------------|
| flex-direction | row | **column** |
| box-sizing | content-box | **border-box** |
| overflow | visible | **hidden** |
| position | static | **relative** |

始终显式设置：
```css
.row { flex-direction: row; }
.scroll { overflow: scroll; }
```

---

## 6. 单位与函数

### 支持的单位
`px`, `%`, `rpx`, `vw`, `vh`, `deg`

### 支持的函数
- rgb(), rgba()
- url()
- var()
- env()

---

## 7. 不支持的特性

- `word-break: break-all` → 使用 `word-wrap: break-word`
- `gap` → 使用 margin 代替
- `background: url()` → 使用 image 组件代替
- `display: grid` → 使用 grid-view 组件代替
- `scrollbar-width`
- `overflow-y` → 使用 scroll-view 代替
- `inherit`
- `color` 属性只生效于：text、button、input、textarea

---

## 8. 最佳实践

1. **仅使用类选择器**
2. 避免依赖样式继承
3. 所有结构性 UI 使用 Flex 布局
4. 可滚动视图使用 `<scroll-view>` 包裹
5. 保持类的职责单一
6. 全局工具类放在 `App.uvue` 中
7. 不要依赖浏览器默认样式
8. 防止 iOS 中 rpx 像素渲染问题，border 边框使用 1px 作为单位