# 第四步：UI 校对阶段（必做）

在完成代码生成并写入文件后，必须执行以下 UI 校对流程，确保实现与设计稿一致。

---

## 0. 前置检查：控制台错误（最先执行）

在截屏前，**必须先**通过 `get_console_logs(level: "error")` 检查控制台报错。常见的运行时错误会导致 UI 完全不渲染或部分缺失，但截屏无法体现根因：

| 常见报错 | 原因 | 修复方向 |
|---------|------|---------|
| `Invalid prop 'className' of type 'array'` | View/Text 的 className 传了数组 | 改用 `clsx()` 拼接为字符串 |
| `Cannot find module '../../res/xxx.png'` | 图片未下载到 src/res | 从 DSL paints 下载图片 |
| `xxx is not defined` | import 缺失或拼写错误 | 补充 import 语句 |

**有报错时先修复报错，再进行截屏对比**。未修复报错就截屏校对是无效循环。

---

## 1. 触发截屏

使用 **miniapp-devtools** 的 `take_screenshot` 截取当前小程序页面（需确保已打开对应页面，如通过路由进入新生成的页面后再截屏）。

### 截屏为空白页的排查

若截屏为纯白/纯黑空白页面：
1. **等待编译完成**：代码修改后 IDE 需要重新编译（通常 5-10 秒），过早截屏会得到空白页。等待后重试。
2. **检查控制台**：`get_console_logs()` 查看是否有编译错误或运行时异常。
3. **检查终端**：查看 dev server 终端输出是否有构建失败信息。
4. **空白页不视为有效截屏**，不应基于空白截屏做 UI 对比判断。

### 非首页页面的导航与截屏

当生成的页面不是首页（如编辑页、详情页）时，需要主动导航到目标页面后再截屏：

1. **导航到目标页**：使用 `service_evaluate` 执行 `ty.navigateTo({ url: '/pages/pageName/index' })`。
2. **等待渲染**：导航后等待 3-5 秒再截屏，页面需要时间加载和渲染。
3. **热更新会重置导航**：每次修改代码后，IDE 重新编译会使小程序回到首页。修改代码后需**再次执行 `ty.navigateTo` 导航到目标页**，然后再截屏。
4. **导航失败的常见原因**：
   - 页面未注册到 `app.config.ts`（自动生成文件在热更新时可能不会重新生成，需手动添加页面路径）
   - 路由路径拼写错误（必须以 `/pages/` 开头）
   - 编译尚未完成

---

## 2. 对比依据

* 以**设计稿 PNG 预览图**（若有）与**输入的 MasterGo JSON** 为设计依据，核对：
  * 节点层级与视觉顺序（从上到下、从左到右）
  * 关键区域是否存在：导航/标题、主内容区、底部 Tab、弹层/浮层等
  * 文案内容是否与 JSON 中 `text`、`name` 及 i18n 映射一致
  * 主要布局特征：行/列数、圆角、间距、是否缺失或错位
  * **背景色**：面板、列表、分段条等应与设计稿一致
* 以**截屏画面**为实际效果，逐项与上述要点对比。

---

## 2.5 辅助工具：DOM 快照诊断

当截屏显示异常（元素缺失、位置偏移、颜色不对）但无法直接定位原因时，使用 **`take_snapshot`** 获取 DOM 树结构：

* **确认元素是否存在**：截屏上看不到某元素 → DOM 快照中有该节点且尺寸正常 → 可能是颜色/透明度问题（如白字白底、深色字深色底）。
* **确认 className 是否生效**：DOM 快照会显示实际 class 属性值，可检查条件 className 是否正确拼接（`clsx` 是否生效）。
* **确认尺寸与位置**：快照中每个元素标注了 `[x,y width×height]`，可与设计稿坐标直接对比。

---

## 3. 常见差异与修复方向

* **导航栏右侧出现自定义胶囊**：小程序会自带胶囊，无需实现 → 修复：移除 NavBar 的 `slot.right`（或等效右侧自定义内容），并删除对应样式与图标引用。
* **导航栏标题不可见（深色背景页面）**：SmartUI NavBar 的文字颜色受主题变量控制 → 修复：通过 `customStyle` 注入 CSS 变量 `--nav-bar-title-text-color: '#ffffff'` 覆盖文字颜色，详见 [09-smart-ui-dark-theme.md](./09-smart-ui-dark-theme.md#navbar-深色适配)；若 CSS 变量方案不生效，再回退为自定义 View 导航头，详见 [03-quality.md](./03-quality.md#navbar-深色背景适配)。
* **元素样式全部丢失（className 传数组）**：所有条件 className 未生效，元素存在但无任何自定义样式 → 修复：将所有 `className={[a, b]}` 改为 `className={clsx(a, b)}`。
* **图片不显示（占位空白）**：Image 组件 src 正确但图片未渲染 → 检查：(1) 图片是否已下载到 src/res；(2) import 路径是否使用相对路径（`../../res/xx.png`）而非别名（`@/res/xx.png`）。
* **选中态重叠**：若设计稿中选中项有特殊样式（如蓝色边框），不要同时创建单独的绝对定位选中层和网格内的选中态样式 → 只用一种方式实现选中态，避免视觉重叠。
* **内容溢出屏幕底部**：设计稿 812px 高度但设备为 667px → 减小固定间距，使用 `flex: 1` 让内容区自适应，详见 [01-layout.md](./01-layout.md#屏幕尺寸适配)。

---

## 4. 不一致时的处理

* 若截屏与 JSON/设计稿**不一致**（如缺块、错位、文案错误、层级颠倒、样式明显不符），必须：
  * 列出具体差异（例：缺少底部「更多」按钮、情景网格少一行、标题未多语言、标签栏被挡、列表白底等）；
  * 针对每项差异**修改对应代码**（tsx / less / i18n），并保存；
  * 修改后**再次进入 Agent 循环**：调用 `take_screenshot` 复核；若仍不一致则继续修改并复核，直到**一致/差异可接受**或**无法继续优化**（见主 SKILL 中 Agent 循环机制）为止。
* 若**一致**，在回复中简要说明「已对照设计稿/JSON 与截屏，UI 一致」并结束循环即可。

---

## 5. 工具与顺序

* 校对阶段依赖：**设计稿 PNG（若有）** + **输入 JSON** + **miniapp-devtools 的 take_screenshot**。
* 顺序：在 **Agent 循环** 中，**每完成一轮代码产出或修改 → 必须执行本步骤（截屏 + 对比）→ 根据结果决定是否进入下一轮修改**，直到校对通过或无法继续优化。