设计稿 - 自动布局文本适配规范

一、扫描范围

搜索目标节点下所有文本节点时，必须同时展开 INSTANCE 内部子树（设置 resolveInstances: true），一次性获取普通文本和 INSTANCE 内部文本。

• 普通文本 ID 格式为 "nodeId"（如 "123:456"），INSTANCE 内部文本 ID 格式为 "instanceId;childId"（分号分隔）
• 修复 INSTANCE 内部节点时，使用分号路径格式引用

> 禁止遗漏：最终分类表格必须同时包含普通文本节点和 INSTANCE 内部文本节点。

二、全局 height 规则

> 🚨 每次修改文本/容器 width 时，必须同步处理 height。所有容器（包括INSTANCE）的 height 统一设置为 hug_contents。若容器原为 FIXED 高度（layoutSizingVertical: "FIXED"），改为 hug_contents 时必须添加 padding 补偿：

> ```

> paddingTop = paddingBottom = (容器原 FIXED 高度 - hug 后内容高度) / 2

> ```

> - 单文本容器：hug 后内容高度 ≈ 文本 lineHeight

> - 多子元素容器：累加子元素高度和间距

> - 容器原本已有 padding（paddingTop > 0）→ 保留不变，不覆盖

> - 容器原本已是 HUG（layoutSizingVertical: "HUG"）→ 无需修改

>

> 操作模板：

> ```javascript

> // 容器原 FIXED 高度 40px，文本 lineHeight 22px，原无 padding

> U("containerId", {height: "hug_contents", paddingTop: 9, paddingBottom: 9})

> ```

> 🚫 禁止只改 width 不改 height。 在第四章每条规则的操作清单中已内联此要求。

三、分类判定（⚠️ 修复前必须先完成）

对每个可见文本节点，按以下优先级判定类型。先机械匹配父容器名称，再语义判断。

> ⚠️ 强制数据校验：分类表中所有父容器属性（layoutSizingHorizontal、width 等）必须来自 batch_read 实际返回值，禁止推断。未获取到的必须补充读取。

> 🚫 INSTANCE 容器和普通 FRAME 容器必须同等对待，不得因为"是 INSTANCE"而跳过属性读取。

> 输出格式（每行"父容器宽度模式"必须填 batch_read 返回的实际值）：

>

> | TEXT ID | 内容（前20字） | 父容器名称 | 父容器宽度模式(实际值) | 来源 | 命中关键词 | 类型 | 修复方式 |

> |---------|--------------|-----------|---------------------|------|----------|------|---------|

四、修复规则

规则 A — 填充式文本（多行段落、单行导航项、表格、描述性/标题类文本）

• 容器（水平）：width → fill_container
• 容器（垂直）：height → hug_contents（⚠️ 若原为 FIXED 且无 padding，需补偿：paddingTop = paddingBottom = (原高度 - 文本lineHeight) / 2）
• 文本：width → fill_container，textAutoResize → "HEIGHT"

> ```

> INSTANCE 内部文本节点：修复方式完全相同，区别仅在于使用分号路径引用。

> - 若 INSTANCE 的属性可通过 U() 修改 → 直接修复

> - 若被组件源锁定（U() 返回空 updated: {}）→ 在外层包裹 FRAME 补偿

规则 B — 独立标签/Tag/按钮（容器随文本伸缩）

• 容器（水平）：width → hug_contents
• 容器（垂直）：height → hug_contents（⚠️ 若原为 FIXED 且无 padding，需补偿：paddingTop = paddingBottom = (原高度 - 文本lineHeight) / 2）
• 文本不改，保持 textAutoResize: "WIDTH_AND_HEIGHT"

> ⚠️ 前提校验：必须通过 batch_read 验证容器 layoutSizingHorizontal 和 layoutSizingVertical 实际值：

> - 水平已是 HUG → 无需修复水平

> - 垂直已是 HUG → 无需修复垂直

> - 为 FIXED → 必须修复为 HUG，否则翻译后文本变长会溢出

规则 C — 左右布局（表单：标签 + 内容区）

• 行容器：width → fill_container，layoutMode → "HORIZONTAL"，height → hug_contents（+ padding 补偿）
• 标签容器：width → 固定值，height → hug_contents（+ padding 补偿）
• 标签文本：width → fill_container，textAutoResize → "HEIGHT"
• 内容容器/文本：同上

规则 D — 跳过不可见节点

对 visible: false 的文本节点及其父容器，跳过检测和修复。

规则 E — 容器级溢出修复（HUG 文本超出 FIXED 父容器）

当 textAutoResize: "WIDTH_AND_HEIGHT" 的文本实际宽度超出父容器 FIXED 宽度时：

检测方式：对每个 HUG 模式文本，检查其直接父容器：

• 父容器 layoutSizingHorizontal: "FIXED" 且 clipsContent: false
• 文本 width > 父容器 width → 确认溢出
• 文本 width > 父容器可用宽度 × 0.85 → 预防性修复（可用宽度 = 父容器 width - paddingLeft - paddingRight - 同级 icon/元素宽度 - itemSpacing）

修复方式（按场景二选一）：

• 伸缩容器（占位符、提示文本等）：父容器 width → fill_container，height → hug_contents（+ padding 补偿），文本 width → fill_container
• 填充容器（卡片内容区等）：按规则 A 处理（含 height + padding 补偿）
• 判断标准：父容器在 auto-layout 中且应占满空间 → 填充；否则 → 伸缩

> ⚠️ 必须同时修改父容器和文本节点，写在同一个 batch_edit 中。

五、修复流程

1. 修复前截图：capture_screenshot 保存基线图
2. 容器链同步修复（每批最多 25 个操作）：
• 垂直：所有容器 height → hug_contents + padding 补偿（见 5.2）
• 水平：FIXED 宽度 → fill_container（见 5.1）
3. 容器链水平宽度检查（5.1）
4. 容器链垂直高度检查（5.2）

5.1 容器链水平宽度检查（🚨 强制执行，不可跳过）

文本 width: fill_container 后，若 parent 链上存在 layoutSizingHorizontal: "FIXED" 的中间容器，文本 fill 空间会被该容器限制，导致不必要的折行。

> ⚠️ 这是最容易遗漏的问题来源。INSTANCE 组件内部常有多层嵌套，中间容器可能是 FIXED 宽度（如侧导航组件内的 Frame 80px），即使文本和直接父容器都已设为 fill，中间层的 FIXED 宽度仍会成为瓶颈。

强制操作步骤：

1. 遍历每个已修复的文本节点，从文本的直接父容器开始，沿 parent 链逐层向上检查，直到遇到 layoutSizingHorizontal: "FILL" 或到达设计稿根节点
2. 对路径上每个容器，检查 layoutSizingHorizontal 的实际值：
• 若为 "FIXED" 且该容器的父级有 auto-layout（layoutMode 为 HORIZONTAL 或 VERTICAL）→ 必须改为 width: "fill_container"
• 若为 "FIXED" 但该容器的父级无 auto-layout（layoutMode: "NONE"）→ 跳过（绝对定位场景）
• 若为 "HUG" 且该容器的父级有 auto-layout → 也必须改为 width: "fill_container"（HUG 容器会被文本撑大，可能超出父级空间）
• 若为 "FILL" → 停止向上遍历，该路径检查完成
3. 同步修复高度：每个被修改为 fill 的容器，若 layoutSizingVertical: "FIXED"，必须同步改为 height: "hug_contents" + padding 补偿
4. INSTANCE 实例节点：INSTANCE 本身也可能是 FIXED 高度/宽度，必须同等检查和修复，不得跳过

输出格式（每条路径的检查结果）：

> 示例（通用结构）：

> ```

> 文本 "Translated Text" (instanceId;textId)

> → 直接父容器 Frame (instanceId;frameId) — FIXED 80px → fill_container

> → INSTANCE 组件实例 (instanceId) — FILL, FIXED h40 → hug_contents + padding

> → 外层列表容器 (listId) — FILL → 停止

> ```

> 常见于：侧导航菜单、表格行组件、卡片内嵌组件等 INSTANCE 内部有多层 Frame 包裹的结构。

>

> ```javascript

> U("instanceId;frameId", {width: "fill_container"})

> U("instanceId", {height: "hug_contents", paddingTop: 9, paddingBottom: 9})

> ```

跳过条件（仅以下情况可跳过）：

• 表格行/单元格等需保持固定宽度的结构
• 父级无 auto-layout（绝对定位场景）
• 容器已是 FILL 模式

5.2 容器链垂直高度检查

padding 补偿计算：

paddingTop = paddingBottom = (容器原 FIXED 高度 - hug 后内容高度) / 2

六、验证流程

1. 修复后全局截图
2. 逐区域扫描：对比基线图，检查截断、溢出、塌陷
3. 问题修正（最多 2 轮）：定位问题节点 → 重新修复 → 再截图验证
4. 输出适配报告：修复节点详情 + padding 补偿值 + 跳过节点及原因 + 验证结果