工程端 · ATH

页面、区域与组件

页面是操作员看到的那一屏。所有内容都由「区域 + 组件」组成，组件是唯一能绑定设备输入的单位。

三层结构

层级	是什么	常用操作
页面	一屏内容，可带标题、提示语与布局。	新增、改标题与提示、删除（会连这一页自带的测试序列一起删）。
区域	页面里的一块分组，可带自己的标题与提示语。	在页面里新增区域、把组件组合进区域、解散区域。
组件	最小单位，绑定一项输入或读数，并决定在页面上怎么显示。	新增、改标签与绑定、复制、对齐、删除。

ath app page-add --title "整机测试"
ath app region-add --page <PAGE_ID> --title "左侧"
ath app component-add --page <PAGE_ID> --feature <INPUT_ID> --type button
ath app component-align --page <PAGE_ID> --mode edges-left

九种组件主体

组件主体决定它怎么画。编辑器给出的可选类型只有这九种；图片和组合不在这份列表里，它们各有一条自己的创建路径。

类型	画什么	典型输入
button	按键：按下与抬起两种状态。	普通按钮。
switch	开关：两个档位。	拨动开关、档位键。
axis	轴：一维数值与可选刻度。	单轴摇杆、模拟量。
encoder	编码器：带方向的连续数值。	旋钮、滚轮。
gyro	陀螺仪：角速度读数。	传感器三轴。
joystick	摇杆：平面上的位置与可选轨迹。	左右摇杆。
hat	方向帽：一组方向键，可整顶一起判。	十字键。
trigger	扳机：行程与模拟量。	LT / RT。
readout	读数：把设备回报的数值直接显示出来（例如固件版本、电量）。	非交互读数。

组件上能改什么

显示名（label）：组件上显示的文字。改大或改长时，盒子只会向外扩，不会把字裁掉。
输入绑定（feature_id）：指向项目里的某项输入或读数。绑定决定「它跟着什么变」。
提示语（prompt）：工位在轮到这一步时显示给操作员的话；没有时回落到区域或页面的提示语。
位置与尺寸（坐标、宽高）：保存在项目里。
层级、不透明度、文字大小、锁定状态。

ath app component-update --component <ID> --label "启动键" --opacity 80
ath app component-duplicate --component <ID>

图片

把 PNG、JPEG 或 BMP 直接拖到页面上，或从页面右键菜单选「添加图片…」。每张图片成为一个独立的图片组件，内容存在项目里：移动项目、删掉原文件都不会让图片失效。

一次导入 1–20 张；单张不超过 10 MB，合计不超过 40 MB。
支持的格式是 PNG、JPEG、BMP；其他格式请先转换。
缩放图片时始终按原始比例，不会拉变形。

把图片和输入对上

图片本身只是背景。要让操作员看清「按哪里」，用状态指示线把组件连到图片上的位置，见状态指示线。

坐标与窗口无关

页面保存自己的坐标与尺寸，和窗口大小无关。工程端按栅格编辑；产线端（ART）按屏幕可用空间把整页等比缩放，不会单独缩放某个组件，也不会裁掉页面。同一份页面在两种窗口里看起来是同一张图。