NarraLeaf

可显示对象

每个可视控件共有的几何与外观接口——属性、Appearance Variant 和属性动画

每个可视控件都是一个 Displayable：它有位置、尺寸、旋转、不透明度，定义了 Appearance Variant 的控件还有变体。这些节点在控件自己的蓝图里读写这套共有接口，因此同一个节点对 Text、Image 或 Container 一样有效

约定

  • 只有 Self 节点。 本分类下没有任何节点带Element输入，目标永远是拥有该蓝图的控件。作用于连入元素的版本放在 Element 分类，叫Get Element Property、Set Element Variant等。Stop Element Animation也归在那里，尽管它没有Element输入——一个AnimationToken已经指明了某个控件上的某个动画，没有别的目标可指
  • 出现位置。 出现在每一种可显示控件的widgetMain蓝图中：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
  • 图类型。 读取节点是纯节点，可用于event、function和macro图，也可用于 Blueprint Value。写入节点是 latent（会挂起执行），只能用于event和macro
  • 写入落在运行时 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（获取属性）读取拥有该蓝图的控件的某个属性。属性键在卡片上选择，因此这一个节点取代了本页末尾那些固定读取节点

引脚方向类型说明
valueout · dataany形状取决于所选的属性键

卡上字段

字段说明
property要读取的属性键

属性键

键读取
position{ x, y }——控件左上角
size{ width, height }
bounds{ x, y, width, height }
x、y左上角的两个分量，数值
offsetX、offsetY相对 authored layout 的视觉位移
width、height尺寸的两个分量，数值
rotation角度
opacity0–1，不是百分比
visibleboolean

Set Property

blueprint.displayable.setProperty · Latent

Set Property（设置属性）写入所属控件的某个属性。可写的属性键是x、y、offsetX、offsetY、width、height、rotation、opacity和visible——position、size和bounds是只读的聚合值，也没有variant键，因为变体有自己的节点

引脚方向类型说明
inin · exec—
nextout · exec—
valuein · dataany接线后卡片上的 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 行里或组件实例里的控件真正占据的位置。

引脚方向类型说明
rectout · dataRect{ x, y, width, height }。控件没被画出来时为 null

Get Center

blueprint.displayable.getCenter · Pure

量出来的那个矩形的中心点。Move Mouse To Element 瞄准的就是这同一次测量；这里给的是那个点本身，而不是那次移动。

引脚方向类型说明
centerout · dataVector2D控件没被画出来时为 null

Get Display

blueprint.displayable.getDisplay · Pure

Get Display（获取显示状态）

引脚方向类型说明
displayout · databoolean默认为true，直到有节点改写它

Set Display

blueprint.displayable.setDisplay · Latent

Set Display（设置显示状态）

引脚方向类型说明
inin · exec—
nextout · exec—
displayin · databoolean

display = false用 CSS display: none隐藏控件及其子树，同时保持挂载。这正是它和visible的全部区别：visible = false的控件会连同子树一起从渲染树中移除

Set Variant

blueprint.displayable.setVariant · Latent

Set Variant（设置变体）为所属控件应用运行时 Appearance Variant 覆盖

引脚方向类型说明
inin · exec—
nextout · exec—

卡上字段

字段说明
Variant目标变体，从该控件已有的变体中按名称选择
Wait For AnimationNo立即继续。Yes会等目标变体上最长的那条字段 transition 结束后才进入Next；没有 transition 时无需等待

节点没有variantId数据引脚，也无法手动输入 id：卡片把变体的内部 id 作为隐藏值写入，作者只会看到名称。对不支持 Appearance Variant 的控件执行该节点会提交图执行错误，而不是静默忽略

设置变体还会清理旧的运行时不透明度覆盖，让新变体自己决定透明度。这正是「先Set Variant切到透明变体，再Animate Property opacity 0 → 100」能正常工作的原因：淡入从变体的透明状态开始，而不会被过期的覆盖值锁住

Get Variant

blueprint.displayable.getVariant · Pure

Get Variant（获取变体）在创建浮窗中隐藏，保留是为了让当前变体卡片之前保存的旧图继续运行

引脚方向类型说明
variantIdout · datastring有运行时覆盖时返回覆盖值，否则返回 authored 默认变体，再否则返回第一个变体。控件没有变体时为""

Animate Property

blueprint.displayable.animateProperty · Latent

Animate Property（动画属性）对单个属性做补间。它是基础节点而不是动画库：没有 Fade、Shake 或 Pulse 节点，那些要以宏的形式基于本节点搭建

引脚方向类型说明
inin · exec—
nextout · exec—动画自然结束或被停止后触发
animationout · dataAnimationToken传给Stop Animation可提前结束动画

卡上字段

字段说明
propertyopacity、offsetX、offsetY、x、y、scale或rotation
from可选起始值。留空表示从控件当前运行时状态开始
to目标值
duration秒。默认0.3
delay秒
easinglinear、easeIn、easeOut、easeInOut、circIn、circOut或circInOut。默认easeOut
afterhold保持最终值，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（停止动画）

引脚方向类型说明
inin · exec—
nextout · exec—
animationin · dataAnimationToken来自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键取代；在创建浮窗中隐藏，但已有该节点的图仍能运行

引脚方向类型说明
positionout · dataVector2D{ x, y }，控件左上角

Get Size

blueprint.displayable.getSize · Pure

Get Size（获取尺寸）已由Get Property的size键取代；在创建浮窗中隐藏，但已有该节点的图仍能运行

引脚方向类型说明
sizeout · dataVector2D引脚类型是Vector2D，但值的键是width和height

Get Bounds

blueprint.displayable.getBounds · Pure

Get Bounds（获取边界）已由Get Property的bounds键取代；在创建浮窗中隐藏，但已有该节点的图仍能运行

引脚方向类型说明
boundsout · dataRect{ x, y, width, height }

Get Rotation

blueprint.displayable.getRotation · Pure

Get Rotation（获取旋转）已由Get Property的rotation键取代；在创建浮窗中隐藏，但已有该节点的图仍能运行

引脚方向类型说明
rotationout · datafloat角度

Get Opacity

blueprint.displayable.getOpacity · Pure

Get Opacity（获取不透明度）已由Get Property的opacity键取代；在创建浮窗中隐藏，但已有该节点的图仍能运行

引脚方向类型说明
opacityout · datafloat0–1，不是百分比

Get Visible

blueprint.displayable.getVisible · Pure

Get Visible（获取可见性）已由Get Property的visible键取代；在创建浮窗中隐藏，但已有该节点的图仍能运行

引脚方向类型说明
visibleout · databoolean

本页目录

约定Get PropertySet PropertyGet Measured RectGet CenterGet DisplaySet DisplaySet VariantGet VariantAnimate PropertyStop AnimationGet PositionGet SizeGet BoundsGet RotationGet OpacityGet Visible