可显示对象
每个可视控件共有的几何与外观接口——属性、Appearance Variant 和属性动画
每个可视控件都是一个 Displayable：它有位置、尺寸、旋转、不透明度，定义了 Appearance Variant 的控件还有变体。这些节点在控件自己的蓝图里读写这套共有接口，因此同一个节点对 Text、Image 或 Container 一样有效
约定
- 只有 Self 节点。 本分类下没有任何节点带
Element输入，目标永远是拥有该蓝图的控件。作用于连入元素的版本放在 Element 分类，叫Get Element Property、Set Element Variant等。Stop Element Animation也归在那里，尽管它没有Element输入——一个AnimationToken已经指明了某个控件上的某个动画，没有别的目标可指 - 出现位置。 出现在每一种可显示控件的
widgetMain或componentWidgetMain蓝图中：nl.container、nl.text、nl.image、nl.button、nl.textInput、nl.switch、nl.slider、nl.list、nl.frame、nl.video、nl.puppet，以及五个舞台控件nl.dialog.sentence、nl.notification.list、nl.choice.list、nl.nvl.list、nl.nvl.texts。Set Variant和Get Variant更窄：只有nl.container、nl.text、nl.image和nl.button拥有 Appearance Variant - 读取节点是纯节点，写入节点是 latent。 Blueprint Value 的宿主是
widgetValue，不提供读取节点；要在 Blueprint Value 中读取控件，请配合Element字面量使用 Element 版本。写入节点会挂起执行，直到写入完成 - 写入落在运行时 patch 层，不改 authored UI document。没有真正改变任何值的写入不会排队 flush
- 坐标使用 Surface 设计坐标系——和检视器 Position
X/Y显示的是同一组数字 - 单位。 卡片会在每个数字输入框旁标出单位：
x/y/offsetX/offsetY/width/height用px，rotation用deg，scale用x，时长用s，opacity用%。除不透明度外，其它属性按输入原样保存。不透明度在卡片上是百分比，在运行时是0–1的小数，所有读取节点返回的也是0–1 - 无法使用的输入会回退到当前值。 布尔输入不接受卡片字面量，因此未接线的
display或visible解析为空，节点会把已有的值原样写回。数字属性收到非数值时同理
两个写不透明度的节点对百分比的理解并不一致。Animate Property总是把From / To除以 100，所以那里的1表示 1%。Set Property只在值大于 1 时才除，所以那里的1表示完全不透明，1% 无法表达。这个不对称是有意的：它让把不透明度存成0–1小数的旧图继续照常运行
Get Property
blueprint.displayable.getProperty · Pure
Get Property（获取属性）读取拥有该蓝图的控件的某个属性。属性键在卡片上选择，因此这一个节点取代了本页末尾那些固定读取节点
| 引脚 | 方向 | 类型 | 说明 |
|---|---|---|---|
value | out · data | any | 类型随所选键而定，见下表：position 与 size 为 Vector2D，bounds 为 Rect，visible 为 boolean，其余为 float |
卡上字段
| 字段 | 说明 |
|---|---|
property | 要读取的属性键 |
属性键
| 键 | 读取 |
|---|---|
position | { x, y }——控件左上角 |
size | Vector2D，x 为宽、y 为高；值中也带有 width 和 height |
bounds | { x, y, width, height } |
x、y | 左上角的两个分量，数值 |
offsetX、offsetY | 相对 authored layout 的视觉位移 |
width、height | 尺寸的两个分量，数值 |
rotation | 角度 |
opacity | 0–1，不是百分比 |
visible | boolean |
Set Property
blueprint.displayable.setProperty · Latent
Set Property（设置属性）写入所属控件的某个属性。可写的属性键是x、y、offsetX、offsetY、width、height、rotation、opacity和visible——position、size和bounds是只读的聚合值，也没有variant键，因为变体有自己的节点
| 引脚 | 方向 | 类型 | 说明 |
|---|---|---|---|
in | in · exec | — | |
next | out · exec | — | |
value | in · data | any | 类型随所选键而定：visible 为 boolean，其余为 float。接线后卡片上的 Value 控件会禁用，以连线值为准 |
卡上字段
| 字段 | 说明 |
|---|---|
property | 要写入的属性键 |
value | 属性值，在value引脚未接线时使用。visible是 Visible / Hidden 下拉，opacity按百分比输入，其它属性使用数字输入 |
offsetX和offsetY保存在控件持久的运行时 transform 中，而不是一次性的 motion 槽里，因此之后接管该控件的动画不会把位移丢掉
Get Measured Rect
blueprint.displayable.getMeasuredRect · Pure
控件最后实际落在哪里，是从画出来的东西上量出来的，而不是从文档里读出来的。
这就是它和 Get Property 取 bounds 键的全部差别。bounds 是 authored layout 加上写在它上面的运行时 patch，所以连还没被画过的控件它也答得出来。这一个量的是 Surface 设计坐标系里真实的那个盒子，也就是一个位于 Container 里、List 行里或组件实例里的控件真正占据的位置。
| 引脚 | 方向 | 类型 | 说明 |
|---|---|---|---|
rect | out · data | Rect | { x, y, width, height }。控件没被画出来时为 null |
Get Center
blueprint.displayable.getCenter · Pure
量出来的那个矩形的中心点。Move Mouse To Element 瞄准的就是这同一次测量；这里给的是那个点本身，而不是那次移动。
| 引脚 | 方向 | 类型 | 说明 |
|---|---|---|---|
center | out · data | Vector2D | 控件没被画出来时为 null |
Get Display
blueprint.displayable.getDisplay · Pure
Get Display（获取显示状态）
| 引脚 | 方向 | 类型 | 说明 |
|---|---|---|---|
display | out · data | boolean | 默认为true，直到有节点改写它 |
Set Display
blueprint.displayable.setDisplay · Latent
Set Display（设置显示状态）
| 引脚 | 方向 | 类型 | 说明 |
|---|---|---|---|
in | in · exec | — | |
next | out · exec | — | |
display | in · data | boolean |
display = false用 CSS display: none隐藏控件及其子树，同时保持挂载。这正是它和visible的全部区别：visible = false的控件会连同子树一起从渲染树中移除
Set Variant
blueprint.displayable.setVariant · Latent
Set Variant（设置变体）为所属控件应用运行时 Appearance Variant 覆盖
| 引脚 | 方向 | 类型 | 说明 |
|---|---|---|---|
in | in · exec | — | |
next | out · exec | — |
卡上字段
| 字段 | 说明 |
|---|---|
Variant | 目标变体，从该控件已有的变体中按名称选择 |
Wait For Animation | No立即继续。Yes会等目标变体上最长的那条字段 transition 结束后才进入Next；没有 transition 时无需等待 |
节点没有variantId数据引脚，也无法手动输入 id：卡片把变体的内部 id 作为隐藏值写入，作者只会看到名称。对不支持 Appearance Variant 的控件执行该节点会提交图执行错误，而不是静默忽略
设置变体还会清理旧的运行时不透明度覆盖，让新变体自己决定透明度。这正是「先Set Variant切到透明变体，再Animate Property opacity 0 → 100」能正常工作的原因：淡入从变体的透明状态开始，而不会被过期的覆盖值锁住
Get Variant
blueprint.displayable.getVariant · Pure
Get Variant（获取变体）在创建浮窗中隐藏，保留是为了让当前变体卡片之前保存的旧图继续运行
| 引脚 | 方向 | 类型 | 说明 |
|---|---|---|---|
variantId | out · data | string | 有运行时覆盖时返回覆盖值，否则返回 authored 默认变体，再否则返回第一个变体。控件没有变体时为"" |
Animate Property
blueprint.displayable.animateProperty · Latent
Animate Property（动画属性）对单个属性做补间。它是基础节点而不是动画库：没有 Fade、Shake 或 Pulse 节点，那些要基于本节点搭建
| 引脚 | 方向 | 类型 | 说明 |
|---|---|---|---|
in | in · exec | — | |
next | out · exec | — | 动画自然结束或被停止后触发 |
animation | out · data | AnimationToken | 传给Stop Animation可提前结束动画 |
卡上字段
| 字段 | 说明 |
|---|---|
property | opacity、offsetX、offsetY、x、y、scale或rotation |
from | 可选起始值。留空表示从控件当前运行时状态开始 |
to | 目标值 |
duration | 秒。默认0.3 |
delay | 秒 |
easing | linear、easeIn、easeOut、easeInOut、circIn、circOut或circInOut。默认easeOut |
after | hold保持最终值，reset回到 authored layout 与 appearance。默认hold |
offsetX和offsetY动画的是相对 authored layout 的视觉位移。x和y动画的是绝对布局位置：hold模式下最终位置会写回运行时 layout patch，并清理残留位移，因此不会回弹。scale是缩放倍率，1为原始大小；opacity在卡片上按百分比输入
animation token 在动画启动的那一刻就发布，早于Next触发。由于节点自己的执行链会挂起到动画结束，这也是停止它的唯一途径：同一蓝图中的另一条执行链在动画进行中读取该引脚
对x和y来说，只有你亲手输入的From = 0才算数——卡片会记录这次输入。旧图里继承下来的0会当作留空处理，动画从当前位置开始，这也正是那些旧图原本的意思
Stop Animation
blueprint.displayable.stopAnimation · Latent
Stop Animation（停止动画）
| 引脚 | 方向 | 类型 | 说明 |
|---|---|---|---|
in | in · exec | — | |
next | out · exec | — | |
animation | in · data | AnimationToken | 来自Animate Property或Animate Element Property的 token |
只停止 token 指明的那一个动画，并释放正在等待它的Animate Property，让后者立即进入自己的Next。传入缺失的 token、其它类型的 token，或对应动画已经结束的 token 时静默 no-op；无论哪种情况执行都会从next继续
Get Position
blueprint.displayable.getPosition · Pure
Get Position（获取位置）已由Get Property的position键取代；在创建浮窗中隐藏，但已有该节点的图仍能运行
| 引脚 | 方向 | 类型 | 说明 |
|---|---|---|---|
position | out · data | Vector2D | { x, y }，控件左上角 |
Get Size
blueprint.displayable.getSize · Pure
Get Size（获取尺寸）已由Get Property的size键取代；在创建浮窗中隐藏，但已有该节点的图仍能运行
| 引脚 | 方向 | 类型 | 说明 |
|---|---|---|---|
size | out · data | Vector2D | { x, y, width, height }：x 与 width 为宽，y 与 height 为高 |
Get Bounds
blueprint.displayable.getBounds · Pure
Get Bounds（获取边界）已由Get Property的bounds键取代；在创建浮窗中隐藏，但已有该节点的图仍能运行
| 引脚 | 方向 | 类型 | 说明 |
|---|---|---|---|
bounds | out · data | Rect | { x, y, width, height } |
Get Rotation
blueprint.displayable.getRotation · Pure
Get Rotation（获取旋转）已由Get Property的rotation键取代；在创建浮窗中隐藏，但已有该节点的图仍能运行
| 引脚 | 方向 | 类型 | 说明 |
|---|---|---|---|
rotation | out · data | float | 角度 |
Get Opacity
blueprint.displayable.getOpacity · Pure
Get Opacity（获取不透明度）已由Get Property的opacity键取代；在创建浮窗中隐藏，但已有该节点的图仍能运行
| 引脚 | 方向 | 类型 | 说明 |
|---|---|---|---|
opacity | out · data | float | 0–1，不是百分比 |
Get Visible
blueprint.displayable.getVisible · Pure
Get Visible（获取可见性）已由Get Property的visible键取代；在创建浮窗中隐藏，但已有该节点的图仍能运行
| 引脚 | 方向 | 类型 | 说明 |
|---|---|---|---|
visible | out · data | boolean |