List
列表控件的运行时内容、选中项、滚动位置和条目上下文
List 节点用于驱动当前私有蓝图所属列表控件的运行时内容、选中项和滚动位置。当行是在游戏运行时才决定的——存档槽、历史回顾、设置菜单——而不是在检视器里一次性写好时，就用它们。把数组和对象整理成最终形状的工作仍然留在 Data
约定
- List 渲染的是运行时条目数组。
Set List Content（设置列表内容）写入的是实例级的运行时数组；Append、Insert、Remove、Clear和Refresh更新的是同一份存储。条目按 JSON-safe 形式保存，因此撑不过一次 JSON 往返的东西在写入时就会丢掉 itemsBinding只是 fallback。 没有写入过运行时条目时才读取元素的 items binding；连 binding 也没有时，由检视器里的预览条目顶上。对运行时存储的第一次写入就终结了这条 fallback- 改写节点会把 fallback 固化下来。 除
Set List Content和Clear List之外的每个改写节点都会先读当前条目、再把整个数组写回去。在一个从未被写入过的 List 上，这次读取取自 fallback，而这次写回把该快照变成了运行时条目——从此 binding 不再生效 - 卸载会清空实例。 List 实例完全卸载时，运行时条目、选中项和待处理的滚动指令都会被丢弃。系统不会替你持久化；把内容写进变量或状态，并在 List 回来时显式恢复
- 读取是纯节点，改写是 latent。
Get系列节点可用于event、function和macro图。每个改写节点都是 latent（会挂起执行），只能用于event和macro——function 图要同步把值返回给调用者，没有地方去接一次待完成的写入 - 内容与选中项的写入会排队触发 flush，滚动节点不会。 滚动节点只是记录一个供渲染器消费的意图，因此不会重新跑那些由 flush 驱动的工作
- 这些都是 Self 节点。 它们作用于拥有当前图的 list-like 控件——
nl.list、nl.notification.list、nl.choice.list、nl.nvl.list——并且没有目标引脚。要操作另一个 List，请使用 Element 分类下的blueprint.element.list.*对应节点，它们带有list输入，且只在当前图中已存在绑定到nl.list的节点时才出现 - 条目上下文需要模板后代。 三个
Get List Item …节点、Get List Item Props与Get Item Field只出现在 List item template 内部元素所拥有的蓝图中，读取的是该元素当前渲染所处的那个条目作用域 - 字段类节点指的是已声明的字段，不是 JSON 路径。
Get Item Field、Set Item Field At、Find Item By Field与Sort List By Field从 List 为其条目声明的那些字段里挑，卡片存的是字段的稳定 id 而不是属性名——所以改属性名、调字段顺序，对图都毫无代价。深层路径仍然归Get JSON Field。两个写入节点在没选字段时拒绝运行；两个读取节点则只是什么也答不出来
Clear List 写入的是一个空的运行时数组，而空数组同样算作已写入的内容——itemsBinding 不会回来，List 会一直空着，直到你再次写入条目。唯一能恢复 fallback 的是卸载 List 实例，而它会连同选中项和滚动状态一起丢弃
Set List Content
blueprint.list.setItems · Latent
Set List Content 整体替换运行时条目数组。不是数组的值会被当成空数组写入，而不是被拒绝，因此一条接错的 items 连线会悄无声息地把 List 清空
| 引脚 | 方向 | 类型 | 说明 |
|---|---|---|---|
in | in · exec | — | |
next | out · exec | — | |
items | in · data | array | 非数组值按空数组写入 |
Append List Item
blueprint.list.appendItem · Latent
Append List Item（追加列表条目）读取当前条目，在末尾加一项，再把整个数组写回去
| 引脚 | 方向 | 类型 | 说明 |
|---|---|---|---|
in | in · exec | — | |
next | out · exec | — | |
item | in · data | any |
Insert List Item
blueprint.list.insertItem · Latent
Insert List Item（插入列表条目）在指定下标之前插入。下标会夹到 0…length，不是数字的下标则回退为末尾，因此越界位置不会抛错
| 引脚 | 方向 | 类型 | 说明 |
|---|---|---|---|
in | in · exec | — | |
next | out · exec | — | |
index | in · data | integer | 夹到 0…length。可在卡片上直接填写字面量 |
item | in · data | any |
Remove List Item
blueprint.list.removeItem · Latent
Remove List Item（移除列表条目）移除第一个与 item JSON 等价的项——比较的是序列化后的值而不是引用，所以用相同字段重新构造出来的对象照样能匹配上。没有任何匹配时数组保持不变，执行继续从 next 走
| 引脚 | 方向 | 类型 | 说明 |
|---|---|---|---|
in | in · exec | — | |
next | out · exec | — | |
item | in · data | any |
Remove List Item At
blueprint.list.removeItemAt · Latent
Remove List Item At（按下标移除列表条目）移除指定下标的项。下标落在 0…length-1 之外，或者不是数字时，数组保持不变，执行继续从 next 走
| 引脚 | 方向 | 类型 | 说明 |
|---|---|---|---|
in | in · exec | — | |
next | out · exec | — | |
index | in · data | integer | 可在卡片上直接填写字面量 |
Clear List
blueprint.list.clear · Latent
Clear List（清空列表）写入一个空的运行时数组。除执行引脚对之外它没有别的引脚
| 引脚 | 方向 | 类型 | 说明 |
|---|---|---|---|
in | in · exec | — | |
next | out · exec | — |
Refresh List Items
blueprint.list.refreshItems · Latent
Refresh List Items（刷新列表条目）把当前条目原样写回去，从而重新渲染每一行，并刷新其后代读取的条目上下文。当变的是条目内部的内容——被就地改动的对象、行从状态里读到的值——而数组本身没变时，用它
| 引脚 | 方向 | 类型 | 说明 |
|---|---|---|---|
in | in · exec | — | |
next | out · exec | — |
Set Selected Index
blueprint.list.setSelectedIndex · Latent
Set Selected Index（设置选中下标）按传入值保存选中下标。它会截断为整数但不会夹取范围：落在当前条目之外的下标照样保留，Get Selected Item 对它输出 null。不是数字的下标解析为 -1
| 引脚 | 方向 | 类型 | 说明 |
|---|---|---|---|
in | in · exec | — | |
next | out · exec | — | |
index | in · data | integer | 不会夹到条目范围内。可在卡片上直接填写字面量 |
Set Selected Item
blueprint.list.setSelectedItem · Latent
Set Selected Item（设置选中项）找到第一个与 item JSON 等价的项并选中它的下标。没有任何匹配时，当前选中项保持不动——这是一次静默的 no-op，不是错误
| 引脚 | 方向 | 类型 | 说明 |
|---|---|---|---|
in | in · exec | — | |
next | out · exec | — | |
item | in · data | any |
Scroll To Index
blueprint.list.scrollToIndex · Latent
Scroll To Index（滚动到指定条目）为该行排入一个滚动请求。负数和非数字下标解析为 0
| 引脚 | 方向 | 类型 | 说明 |
|---|---|---|---|
in | in · exec | — | |
next | out · exec | — | |
index | in · data | integer | 下限为 0。可在卡片上直接填写字面量 |
Scroll To Top
blueprint.list.scrollToTop · Latent
Scroll To Top（滚动到顶部）为 List 的开头排入一个滚动请求
| 引脚 | 方向 | 类型 | 说明 |
|---|---|---|---|
in | in · exec | — | |
next | out · exec | — |
Scroll To Bottom
blueprint.list.scrollToBottom · Latent
Scroll To Bottom（滚动到底部）为 List 的末尾排入一个滚动请求。和 Append List Item 搭配使用，可以让日志始终贴着最新一行
| 引脚 | 方向 | 类型 | 说明 |
|---|---|---|---|
in | in · exec | — | |
next | out · exec | — |
Set Visible
blueprint.list.setVisible · Latent
Set Visible（设置可见）设置控件的运行时可见性。这是 authored 的 visible 属性，不是 Displayable 的渲染开关——想让元素保持挂载、只用 display: none 藏起来时，看 Displayable 里的 Set Display
| 引脚 | 方向 | 类型 | 说明 |
|---|---|---|---|
in | in · exec | — | |
next | out · exec | — | |
visible | in · data | boolean |
Set Enabled
blueprint.list.setEnabled · Latent
Set Enabled（设置启用）打开或关闭 List 的运行时交互
| 引脚 | 方向 | 类型 | 说明 |
|---|---|---|---|
in | in · exec | — | |
next | out · exec | — | |
enabled | in · data | boolean |
Set Item Field At
blueprint.list.setItemFieldAt · Latent
写一行里的一个字段，这一行的其余部分和列表的其余部分都不动。它是把整行重写一遍而不是原地改：列表的内容是以副本形式交出去的，改你读到的那份不会让任何人渲染的东西发生变化
| 引脚 | 方向 | 类型 | 说明 |
|---|---|---|---|
in | in · exec | — | |
next | out · exec | — | |
index | in · data | integer | 可填字面量 |
value | in · data | any |
卡片字段
| 字段 | 说明 |
|---|---|
Field | 要写 List 条目的哪个字段。必填 |
行不存在时是安静的空操作而不是错误：一张图往它刚拿到的那一行里写，是最普通的情形，而列表在它脚下缩短了不该把整条链停掉
Sort List By Field
blueprint.list.sortByField · Latent
按条目的某个字段重排运行时条目并写回。排序是一次写入，所以它和其它改写节点一样会把 fallback 固化下来
| 引脚 | 方向 | 类型 | 说明 |
|---|---|---|---|
in | in · exec | — | |
next | out · exec | — |
卡片字段
| 字段 | 说明 |
|---|---|
Field | 按哪个条目字段排。必填 |
Direction | Ascending 或 Descending |
Get List Content
blueprint.list.getItems · Pure
Get List Content（获取列表内容）输出运行时条目数组；还没有写入过时，输出 itemsBinding / 预览 fallback
| 引脚 | 方向 | 类型 | 说明 |
|---|---|---|---|
items | out · data | array |
Get Selected Index
blueprint.list.getSelectedIndex · Pure
Get Selected Index（获取选中下标）输出运行时选中下标，缺省回退到元素 authored 的 selectedIndex
| 引脚 | 方向 | 类型 | 说明 |
|---|---|---|---|
index | out · data | integer |
Get Selected Item
blueprint.list.getSelectedItem · Pure
Get Selected Item（获取选中项）输出选中下标处的条目；该下标落在当前条目之外时输出 null
| 引脚 | 方向 | 类型 | 说明 |
|---|---|---|---|
item | out · data | json |
Get List Length
blueprint.list.getLength · Pure
List 当前有多少行
| 引脚 | 方向 | 类型 | 说明 |
|---|---|---|---|
length | out · data | integer |
Get Item At
blueprint.list.getItemAt · Pure
按下标取一行，不必用 Get List Content 把整个数组拽过来
| 引脚 | 方向 | 类型 | 说明 |
|---|---|---|---|
index | in · data | integer | 可填字面量 |
item | out · data | json | 下标落在当前条目之外时为 null |
Find Item By Field
blueprint.list.findItemByField · Pure
按条目的某个字段找一行——id 是 "auto" 的那个存档槽、code 与当前语言相符的那一行语言
| 引脚 | 方向 | 类型 | 说明 |
|---|---|---|---|
value | in · data | any | 该字段应当等于什么 |
index | out · data | integer | 没有命中时为 -1 |
item | out · data | json | 没有命中时为 null |
found | out · data | boolean |
卡片字段
| 字段 | 说明 |
|---|---|
Field | 按哪个条目字段匹配 |
Get Scroll Progress
blueprint.list.getScrollProgress · Pure
List 滚到了哪里，取值 0–1
Scroll 事件 Head 告诉一张图列表动了；这四个节点告诉一张图它停在哪。这个区别对那些由列表之外的东西触发的逻辑很要紧——包在它外面那一页上的滚轮处理器没人会通知它，只能自己问——而把 Head 的答案镜像进一个变量，正是那种会悄悄过期的写法
| 引脚 | 方向 | 类型 | 说明 |
|---|---|---|---|
progress | out · data | float |
Get Scroll Offset
blueprint.list.getScrollOffset · Pure
同一个位置，按像素给出，并附上总共还有多长可走
| 引脚 | 方向 | 类型 | 说明 |
|---|---|---|---|
offset | out · data | float | |
maxOffset | out · data | float | 内容装得下、没什么可滚时为 0 |
Is Scrolled To Start
blueprint.list.isScrolledToStart · Pure
| 引脚 | 方向 | 类型 | 说明 |
|---|---|---|---|
atStart | out · data | boolean | 距近端一个像素以内。内容装得下时为 true |
Is Scrolled To End
blueprint.list.isScrolledToEnd · Pure
| 引脚 | 方向 | 类型 | 说明 |
|---|---|---|---|
atEnd | out · data | boolean | 距远端一个像素以内。内容装得下时为 true |
两端都由“这条轴到头了”的同一个定义判定，所以它们和 Get Scroll Progress 不可能各说各话——这正是一个“跳到最新”按钮能在回顾已经到底时恰好把自己藏起来的原因
Get Visible
blueprint.list.getVisible · Pure
| 引脚 | 方向 | 类型 | 说明 |
|---|---|---|---|
visible | out · data | boolean |
Get Enabled
blueprint.list.getEnabled · Pure
| 引脚 | 方向 | 类型 | 说明 |
|---|---|---|---|
enabled | out · data | boolean |
Get List Item Props
blueprint.list.getItemProps · Pure
Get List Item Props（获取条目 props）输出当前行正在渲染的条目：条目本身是 object 时就是它，否则是 { value: item }，因此哪怕是一个纯字符串的 List，也照样有一个字段可读。没有条目上下文时输出 { value: null }
| 引脚 | 方向 | 类型 | 说明 |
|---|---|---|---|
props | out · data | json |
五个条目上下文节点读取的是正在渲染那一行的条目作用域，并且除事件图之外也能用于 Blueprint Value 图——模板里的一个文本元素之所以能逐行显示不同的字符串，靠的就是这个。重复渲染出来的行彼此隔离，因此每份副本都保有自己的事件 locals 和自己解析出的 Blueprint Value，尽管所有副本都来自同一个源 element id
Get List Item Index
blueprint.list.getItemIndex · Pure
Get List Item Index（获取条目下标）输出当前行的下标。没有条目上下文时输出 -1
| 引脚 | 方向 | 类型 | 说明 |
|---|---|---|---|
index | out · data | integer |
Get List Item Count
blueprint.list.getItemCount · Pure
Get List Item Count（获取条目总数）输出本次渲染的行数。没有条目上下文时输出 0
| 引脚 | 方向 | 类型 | 说明 |
|---|---|---|---|
count | out · data | integer |
Get List Item Key
blueprint.list.getItemKey · Pure
Get List Item Key（获取条目 key）输出该行的 key：List 的 itemKeyPath 指向的值是字符串或数字时用该值，否则用行下标的字符串形式。没有条目上下文时输出空字符串
| 引脚 | 方向 | 类型 | 说明 |
|---|---|---|---|
key | out · data | string |
Get Item Field
blueprint.list.getItemField · Pure
正在渲染那一行里某个已声明字段的值。它是 Get List Item Props 的窄口版本：在卡片上把字段选出来，而不是把整个条目读回来再从里面挖一个 key，图也就不再依赖那个属性碰巧叫什么
| 引脚 | 方向 | 类型 | 说明 |
|---|---|---|---|
value | out · data | any | 形状随所选字段而定 |
卡片字段
| 字段 | 说明 |
|---|---|
Field | 要读条目的哪个字段 |
和上面三个 Get List Item … 一样需要条目上下文，也和它们一样能用在 Blueprint Value 里——模板中的一个文本元素之所以能逐行显示不同的字符串，靠的就是这条路。