AddToList 列表元素插入与动态追加节点
节点核心功能 (What is it?)
AddToList 节点是一个实用的数据列表操作工具节点，能够将单个元素项插入到现有列表的指定位置中。它支持将新元素添加到列表头部（起始位置）、尾部（末端追加）或指定的任意数字索引下标处。
典型适用场景 (When would I use it?)
在以下情况下使用 AddToList 节点：
- 向现有的数据列表中动态追加新数据项；
- 在列表的特定物理位置插入关键字段或标记元素；
- 在工作流执行期间动态构建与更新列表数据集合；
- 维护具有严格先后时序或优先级排序的有序元素集；
- 灵活调整列表结构而无需从零手工重建新列表。
使用指南 (How to use it)
基础配置流程 (Basic Setup)
- 在工作流画布中添加 AddToList 节点。
- 将现有的列表数据连接至
items输入插槽。 - 将待插入的单个元素连接至
item输入插槽。 - 在
position参数下拉菜单中选择插入策略（"start"、"end" 或 "index"）。 - 若选择了 "index" 定点插入，在
index参数框中设定具体的数字索引下标。
参数输入插槽 (Parameters)
- items：待接收新元素的母列表（
list类型输入端）。 - item：待插入列表中的目标数据元素（支持任意数据类型
any）。 - position：新元素插入的相对位置策略（可选值：
"start"头部插入、"end"尾部追加、"index"指定索引下标）。 - index：具体的插入目标位置下标（整型数值，仅当
position设为"index"时动态可见）。
输出引脚 (Outputs)
- output：整合了原始列表所有元素及新插入项的全新组合列表工件。
典型工作流示例 (Example)
向任务待办列表中动态追加一项新任务：
- 在画布中添加 AddToList 节点。
- 将上游生成的待办任务列表连入
items输入端。 - 将包含新任务名称的字符串文本节点连入
item输入端。 - 将
position设置为"end"（末尾追加）。 - 节点的
output即输出一个末尾成功追加了新任务的完整列表。
关键技术特性 (Important Notes)
- 不可变防御机制 (Immutability)：该节点底层遵循函数式不可变原则，总是克隆并返回一个全新的列表对象，绝对不会污染破坏上游原列表的数据完整性。
- 动态参数面板：
index参数输入框仅在position策略选为"index"时才会在 UI 上动态展现。 - 元素多态支持：待添加的
item可以是字符串、数值、布尔值、字典或嵌套列表等任意类型，但在向下游传递时需留意下游算子的类型兼容性。
常见问题与排查 (Common Issues)
- 索引下标越界 (Invalid Index)：使用
"index"模式时，输入的索引值必须位于当前列表的合法下标边界之内。 - 空列表保底处理 (Empty List)：当母列表为空列表时，无论选择何种位置，新元素都将被作为唯一的第 0 号首项安全压入。
- 下游类型不匹配 (Type Mismatch)：注意下游节点是否仅接受同构数据类型（如纯文本列表），避免插入不兼容数据。