---
name: page-composition
description: 使用已有组件和图像制作页面布局，检查分组、文字、不同显示场景和构建依赖。组件外观修改转到 PhotoCraft 制作流程。
---

# 使用已有资产组合页面

页面组合管理实例、位置、尺寸、层级和文字，组件制作管理可复用外观。先读 `project_context`，查询当前组件产物、图像和组合，再决定缺少什么。已有资产能够满足任务时直接引用，不因需要完整页面而启动整页基础 UI 绘制，也不用共享绘制函数重新生成已有组件。

用 `project_save_layout` 保存定义，`project_get_layout` 读取当前定义，`project_build_layout` 构建离线 HTML 与同页 PNG，`project_get_page_build` 读取当前构建。布局在结构化定义中编辑，浏览器用于查看、缩放和检查。调用前阅读[可更新的页面布局](../../docs/project-tools.md#可更新的页面布局)。

## 选择修改入口

| 任务 | 处理方式 |
| --- | --- |
| 移动按钮、调整间距、修改文案或层级 | 保留资产 ID，修改布局节点、保存定义并重建 |
| 排列已有 Unity 控件或修改其实例文案 | 在正式页面使用 `control` 节点，按控件设计尺寸安排位置，通过公开参数设置本页文案 |
| 修改文字字号、填色、描边或投影 | 更新项目文字规范中的角色样式，查看使用位置后重建受影响页面 |
| 比较不同尺寸、安全区、译文、字体角色或组件状态 | 用 `project_preview_layout_variants` 构建本机场景，打开批次索引比较 |
| 修改材质、轮廓或某个组件状态 | 用 [photocraft-drawing](../photocraft-drawing/SKILL.md) 修改对应源组件，再组合检查受影响实例 |
| 生成或编辑独立图标 | 用 [icon-assets](../icon-assets/SKILL.md) 制作和登记图像，组合时引用当前资产 ID |
| 判断目标风格或定位视觉偏差 | 用 [reference-style](../reference-style/SKILL.md) 查看依据，区分资产外观、导出、布局、文字和运行时问题 |

尺寸变化先检查当前资产声明的内容区域、伸缩方式和最小尺寸。正式导出支持等比、显式拉伸、九宫格及单轴伸缩；未声明几何的独立图像按完整原图等比居中。不能为达到目标尺寸而擅自改变资产伸缩规则或压平独立文字。所需外观超出声明的伸缩能力时，才制作合适变体。

## 引用与检查

开工时用 `project_search_reusable` 按用途查询公共 Prefab 和图素。
先查看匹配项的预览、尺寸、伸缩约束和状态，再用已有 `control_id` 或 `asset_id`。
图素来源过期、文件异常或控件登记无效时，先处理返回的原因。

开工时先核对 `project_context` 中的风格规则、文字角色、组件使用约定与 `ui_settings`。
有参考尺寸要求时确认 `reference_size`，涉及滚动时确认 `scroll`，按项目约定补齐相关缺项。
滚动列表继承项目的滚动模式和短内容拖动约定。特殊需求在对应列表的交付记录中写明覆盖值和原因。

1. 确定参考分辨率、目标背景和图文关系。用行、列、叠放或相对定位分组表达实际关系。需要跟随画布或安全区时，为根分组设置 `region` 并按需声明 `safe_area`。弹性区域用 `fill`，随短文案伸缩的单行文字用 `content`。需要共享内边距、文字范围、点击范围、枢轴或检查所需状态时，将分组绑定到声明了 `spec.usage` 的组件。
2. 已登记图像通过 `project_get_image` 校验和查看。需要从组件交付正式 PNG 时，按[正式导出约定](../../docs/project-tools.md#正式-png-导出)调用 `project_export_assets`，使用返回的资产 ID。已有未登记 PNG 用 `project_register_image` 的 `imported` 来源登记真实说明。布局节点使用 `asset_id` 引用当前文件。组件预览仍可用于检查，但不等于经过明确区域及几何声明的正式导出。
3. 新页面可以使用任务明确允许的业务占位，但应在项目资料中记录占位范围、用途和替换需求，汇报时明确指出。已声明的正式资产缺失或摘要不符必须报错，不能自动换成占位。
4. 用 `project_save_layout` 保存最多 512 个节点，分组计入总数。同一资产的多个实例使用不同节点 ID，复用同一 `asset_id`。按用途选择 `text_style_id`，独立指定文案、文本框、对齐、换行和溢出策略。通常先调整布局、留白和换行。业务需要保留限定空间时，明确选择 `clip` 或 `shrink`，缩字时必须指定 `min_font_size`，并检查实际字号。需要限制行数时设 `max_lines`。缺少适用角色时按参考建立规范。字体须在工程内持久目录，缺字、摘要变化或非法参数会报错。
5. 查看返回的 PNG，在 HTML 中按问题开启安全区、布局框、内容框、可见范围或文字基线。检查实际字号和警告，复查目标尺寸下的留白、文字可读性、状态辨识和视觉层次。用实际译文、对应文字角色和目标尺寸检查显示场景。对比组件状态时，为同一图像节点指定各状态的当前资产，按状态命名场景。索引指向最近一次成功批次，修改前后的正式产物用 Git 对应版本复查。分别记录自动检查、视觉判断和用户美术确认。
6. 布局反馈修改定义，文字样式反馈修改角色，资产外观反馈修改来源。用 `project_page_dependencies` 找到使用位置和过期原因，按提示先处理需要重画或重新导出的资产，再用 `project_rebuild_pages` 集中重建相关页面。运行批次前读取当前 revision。

有浏览器预览定义的 Unity 控件可通过 `control_id` 复用。同一控件出现多次时，每个实例使用独立的节点 ID 和 `parameters`。沿用默认值时省略对应参数键。浏览器快照中的 `实例ID/内部节点ID` 用于定位图文，修改实例时编辑正式页面或控件定义。控件及其依赖变化后，通过页面依赖查询定位需要重建的预览。

## 对照参考与集中修正

完成页面后执行[设计稿检查](../../docs/ui-delivery-checklists.md#设计稿)，记录不适用及待验证项。

交付页面设计稿或整页预览供用户审阅时，主动展示同一次 `project_build_layout` 返回的干净稿和适配标注图，
并附上 `files.inputs` 中的 `inputs.json`。标注图同时用于设计审阅和指导 Unity 落地。
按英文图例核对元素范围、贴边锚定、枢轴、拉伸方向和安全区。查看 `files.annotated.missing`，
说明未声明的适配约束。默认展示刘海和手势区示意；已知设备时传入实际尺寸和用途。
已有快照缺少标注图时，交付前重新构建。仅内部快速预览或用户明确只要干净稿时可传 `annotate=false`。

基础组件校准只组合能验证图文关系的典型小区域，可复用已有组合；完整页面检查随实际页面任务进行，不为了前置检查补做场景、全部图标或未来交互。任务范围内缺少的内容如实记录，占位不能证明完整风格匹配，也不能把占位造成的差异归因于基础组件。

将参考的可比区域或整页与当前 PNG 按可比显示尺度查看，先判断视觉重心、明暗面积、疏密及图文比例，再定位到布局、文字、导出伸缩或资产外观。无变化时用 `project_get_page_build` 复查现有快照，不再次构建。核对构建实际使用的资产和布局是否对应本轮目标。

先汇总影响大的偏差，集中修改相关定义或资产，再构建一次并与参考、修改前产物复查。默认不固定修正轮数，局部放大及其他尺寸检查按问题需要使用。主要偏差已消除且受影响实例无退步时结束；没有明确改法或修正无收益时保留未解决项，不宣称通过。完整结束条件和耗时记录见[参考匹配与按需修正流程](../../docs/style-reproduction-validation.md)。

现有组件反馈接口不能直接接收页面构建 ID。页面观察沿用业务项目现有的非受管工作记录，简短保存参考区域、构建 ID、实际资产及其摘要、偏差、改法及复查结果；定位到源组件后再用组件对照和反馈工具。不手改 项目索引 或受管 Markdown，不为每轮另建长报告。

展示布局 ID、构建 ID、HTML/PNG 路径、实际资产及其摘要和未完成项。使用的资产、技术校验、模型视觉结论和用户确认分别表达；流程不增加逐步骤用户审批。需要简单的当前组件产物裁切对照时，`project_create_composition` 和 `project_get_composition` 仍可创建、读取只含等比图像和单行文字的静态快照，不能向该接口传入页面布局的九宫格或换行能力。

## 锚点、枢轴与代表条目标注

区块根节点按页面适配关系锚定边角或拉伸；块内图标、文字、按钮通常相对所属区块中心锚定，
即 `anchor_min = anchor_max = [0.5, 0.5]`，通过相对位置保持排版。先建立真实父子分组，
不能将所有子元素直接锚定页面边角。只有明确的边缘跟随或拉伸需求才使用例外，并记录理由。
`pivot` 独立于锚点决定缩放与旋转中心，默认 `[0.5, 0.5]`，按钮尤其需要保持中心；
即使按钮贴边锚定，也不能据此把 pivot 改到边角。特殊旋转轴、进度填充等按实际需求单独声明。
修正锚点或 pivot 时保持参考尺寸下的视觉位置，再检查不同尺寸及按钮缩放效果。

重复列表保留各条目的外框，内部元素通常只标注一个完整代表条目；其他状态出现新增元素或不同约束时补充标注。
内部元素密集时可将标记分散到多个条目，但须合起来覆盖完整结构与状态差异。
通过 `unity_adaptation.<节点ID>.annotate=false` 隐藏重复内部节点的标记；默认 true，只影响该节点，
不递归隐藏子节点，不改变布局、Unity 属性或约束缺项检查。不得仅按图像或文字相似度自动去重。

## 必须执行的层级与交付要求

先定义真实语义层级，再排列元素：页面 → 功能区块 → 列表／条目／复合控件 → 内部图文。
无背景、透明的区块也必须有 group／RectTransform 容器。归属同一区块的元素放入其子层级，
禁止把大量内部图标、文字、按钮平铺在页面第一层；不以命名分组或标注框代替真实父子关系。
层级按共同移动、适配、显隐和复用边界划分，不为每个单元素机械加容器。
Unity 制作前核对布局树，交付前读取实际 Prefab 层级，确认父子关系与区块归属；平坦结构不能判为完成。
标注图必须显示不可见区块边界。紫色虚线 Layout Group 表示真实布局分组，即使关闭该组其他标记也保留边界。
没有分组数据时先修正来源层级，不能在截图上虚构分区。

正式交付必须在回复中同时展示同次构建的干净稿、标注图，并链接 inputs.json；只有工具返回或磁盘存在不算展示。
发送回复前逐项核对两张图均已嵌入、标注含区块划分及刘海和手势区示意。缺图或旧快照缺设备区域时先重建。
未指定设备时工具按设计宽度的 6%／4% 扩展顶部／底部，并标明 Illustrative device；这是示意尺寸，不是真实机型验收。
已知设备参数时显式传入 annotation_device。仅用户明确要求无设备示意时将 top、bottom 均设为 0。
内部快速预览可关闭标注，但不得将这种预览直接作为正式交付；用户明确只要干净稿时除外。