# 格式校验

[← 返回 README](../README.md) · [文档索引](./index.md)

编辑器**每次渲染都扫一遍**样式表，结果体现在状态行上。校验分三层：结构（括号 / 注释）、
声明（每条能否解析）、值（引擎认不认）。读完本文你能看懂状态行上任何一句红字。

---

## 状态行怎么读

正常时状态行保持中性色。有问题时变红，格式是**行首问题 + 总数**，最多列 5 处：

```
第 3 行 color 的值无效：notacolor
第 73 行 syntax 必须是带引号的字符串，例如 '<color>' 等 3 处
```

- 冒号前面是**位置与属性**，冒号后面是**具体哪里不对**。
- 「等 N 处」说明还有更多没列出来 —— 先修能看见的，再保存，它会继续报下一批。

## 三层判据

| 层 | 判什么 | 典型错法 |
| --- | --- | --- |
| 结构 | 括号与注释必须闭合 | 少一个 `}`、`/*` 没闭合 |
| 声明 | 每条声明必须可解析 | `color red`（缺冒号）、粘连的两条声明 |
| 值 | 每个值必须被**引擎**接受（`CSS.supports`） | `color: notacolor`、`width: abc`、`gap: 8`（缺单位） |

值这一层用的是浏览器自己的判断，不是插件维护的白名单 —— 所以引擎新增的属性天生就支持，
补全列表与校验两边**看的是同一份事实**。

---

## 变量体检

停顿 **600ms** 后跑一次（需要读文档，所以是异步的）。

自定义属性是**继承**的，所以「这个变量有没有值」是个关于**元素**的问题，不是关于文本的问题。
编辑器把每条规则的选择器在页面里匹配一遍，再从命中的元素上读该属性，读不到就报：

```
变量 --dsl-g-shadow-card 在这条规则命中的元素上读不到
```

别的插件在**自己卡片上**定义的令牌，在卡片外面用就是这么静默失效的 ——
这条检查专门抓这个。

**两种情况故意不报**：

- 规则**没命中任何元素** —— 没得问（页面里根本没有这个元素，谈不上变量有没有值）。
- `var(--x, 备用值)` —— **有备用值就没有可丢的**。

同一次巡检也产出**规则大纲**里那个「命中 N 个」的数字（见 [控件](./controls.md)）。

---

## 描述符块走自己的规则

`@property --x { syntax: '<color>'; inherits: true; initial-value: … }` 里的
`syntax` / `inherits` / `initial-value` 是 **descriptor 而不是 CSS 属性**，
`CSS.supports()` 一律不认。

早期版本就是把它们当声明判的，于是一个**完全合法**的 `@property` 被报成 3 处错误。
现在按块类型分流：

| 块类型 | 怎么校 |
| --- | --- |
| `@property` | 用描述符规则：`syntax` 必须带引号、`inherits` 只能 `true`/`false` |
| `@font-face` · `@page` · `@counter-style` · `@viewport` · `@font-palette-values` · `@font-feature-values` | 整块交给引擎 |
| 其余 | 照旧逐条过 `CSS.supports` |

这也是 [已知坑](./known-issues.md) 里「描述符不是属性」那一条的来源。

## 相关

- [编辑器](./editor.md) —— 格式化与校验的分工（格式化只动行的排布）
- [规则面板](./rule-panel.md) —— 面板里的值字段也有自己的即时判断（失焦时描红）
- [已知限制](./known-issues.md) —— 规则面板只认顶层规则