企业官网建设流程全解析

• 音视频
• 图形学
• 桌面应用

JoinLists 是 TiXL 运算符库Lib.numbers.data.utils中用于数据整理的实用运算符，其职责是把多条结构化列表（StructuredList）纵向拼接为一条新列表，并同时输出合并后的元素数量。本文以该运算符的参考文档为主体，结合其在 JoinLists.cs 中的真实实现与底层StructuredList.Join逻辑，完整讲解输入输出语义、边界行为、类型兼容规则及在项目中的实际用法。

运算符速览

JoinLists 属于Lib.numbers.data.utils（数字数据类型工具库），该库收录了列表项属性读取、字典取值转换等数据整理类运算符，详见 utils 库说明。参考文档 JoinLists.md 由运算符库自动生成，其中记录的运算符接口如下：

参考文档当前标注为No description yet，此类占位说明表明该运算符的描述文本尚未在 TiXL 编辑器中补充——在编辑器中编辑运算符描述即可自动回填到文档页。不过运算符的实际行为完全可以由其源码与底层数据结构确认。

输入与输出详解

输入：Lists（多输入槽）

在 JoinLists.cs 中，Lists被声明为MultiInputSlot<StructuredList>，即一个多输入槽：同一时刻可以接入任意数量的结构化列表数据源。它与普通单输入槽的区别在于可以动态收集所有已连接分支的值，更新逻辑中通过Lists.CollectedInputs枚举全部输入。

输出：Result（合并结果列表）

Result的类型是T3.Core.DataTypes.StructuredList（见参考文档 Outputs 表）。它保存合并后的完整列表：

• 仅一条有效输入时，输出该输入列表的类型化克隆副本（TypedClone()），原始列表不受影响；
• 多条有效输入时，输出将这些列表按接入顺序纵向拼接后的新列表；
• 没有任何有效输入时，Result保持上一次的值，不会被清空。

输出：Length（元素数量）

Length的类型为System.Int32，用于告知下游"合并结果有多大"，常用于驱动循环次数、采样数或数组分配等逻辑。需要特别注意的是，从 Update 逻辑 看，Length的取值在不同输入数量下语义并不完全一致，详见下一节。

合并规则与边界行为

Update方法中的核心分支展示了 JoinLists 在三种输入场景下的完整行为：

var connectedLists = Lists.CollectedInputs.Select(c => c.GetValue(context)).Where(c => c != null).ToList(); Lists.DirtyFlag.Clear(); if (connectedLists.Count == 0) { Length.Value = 0; return; } if (connectedLists.Count == 1) { Result.Value = connectedLists[0].TypedClone(); Length.Value = 1; return; } Result.Value = connectedLists[0].Join(connectedLists.GetRange(1, connectedLists.Count - 1).ToArray()); Length.Value = Result.Value.NumElements;

（节选自 JoinLists.cs）

场景一：没有任何有效输入

当Lists上没有连接任何输入，或所有输入求值结果为null时，Length被置为0，Result不做更新（保留上一次输出值）。这在图被部分断线时仍能保持稳定的数据流输出。

场景二：仅有一条有效输入

此时不会触发真正的合并，而是对唯一的列表执行TypedClone()返回一份拷贝，避免下游修改污染上游数据源；Length此时被设置为1。从源码结构看，这里的语义是"成功接收到的列表数量"而非该列表的元素个数，这一点与多输入场景下的语义存在差异，使用时需留意。

场景三：多条有效输入（核心合并路径）

多条输入时，以第一条列表为基准，将剩余列表通过Join(...)纵向拼接。注意排序规则：最终结果中元素的先后顺序与接入顺序一致——先接入的列表元素在前。此时Length等于合并后新列表的元素总数（Result.Value.NumElements）。

底层实现：StructuredList.Join

JoinLists 的数据合并能力最终落在StructuredList的Join方法上。StructuredList在 StructuredList.cs 中声明了抽象方法public abstract StructuredList Join(params StructuredList[] other)，其泛型实现StructuredList<T>位于同一文件：

1. 预计算总长度：累加所有参与合并列表的元素数（StructuredList.cs）；
2. 类型兼容检查：若某条列表的Type与基准列表不同，则跳过该列表并记录警告日志StructuredList.Join: trying to join different structure types, skipping at index {i}.，不会抛出异常中断流程；
3. 分配新数组并拷贝：创建新的StructuredList<T>，通过Array.Copy依次将各列表的元素拷贝到目标数组的连续区间（StructuredList.cs）。

由此可以确认两个重要的实用结论：

• JoinLists 不会修改任何输入列表，输出始终是一份全新分配的结果，适合在数据流图中放心复用上游数据；
• 只应合并元素类型一致的列表。若误接入了不同类型的结构化列表（例如把 Float 列表与 Vec2 列表接在一起），类型不匹配的列表会被静默跳过，Length与Result将只反映兼容部分——因此在实际布线前应确认各输入的列表类型一致。

在真实项目中的使用方式

库内实际案例：WaveForm 运算符

JoinLists 并非孤立存在，Operators/Lib库内的WaveForm（波形分析）运算符就引用了该符号，见 WaveForm.t3 中的"SymbolId": "0b99ab8b-5d61-49da-9851-9ad723cad3ae"，与 JoinLists.cs 中声明的 GUID 一一对应。这说明在多段音频数据、多通道采样列表需要合并后统一处理时，JoinLists 是 TiXL 官方符号库自身采用的常规做法。

在图中的典型接线

在实际 TiXL 编辑器中，典型用法如下：

1. 从库浏览器定位Lib.numbers.data.utils分类下的JoinLists，拖入画布；
2. 将两条或更多相同元素类型的列表数据源（例如多个 Point 列表、Float 列表）分别连接到Lists多输入槽；
3. 从Result输出引出合并后的完整列表，供下游的循环、采样或数据绘制运算符使用；
4. 从Length输出引出元素总数，用于设置循环次数或初始化数组。

如需查看Lists输入槽的序列化默认值，可参考符号定义文件 JoinLists.t3，其中Inputs[0]的DefaultValue为null，即未连接时无默认列表。

相关运算符与延伸阅读

在Lib.numbers.data.utils分类下，与 JoinLists 配套的数据整理运算符还包括：

• GetListItemAttribute — 通过反射获取列表项属性中的 Float 值（文档注明较慢，谨慎使用）；
• GetPointDataFromList — 从点数据列表中取出 Position、Rotation 与 W 分量；
• SelectFloatFromDict — 解析字典并将单个值转换为 Float；
• SelectVec2FromDict 与 SelectVec3FromDict — 字典到向量类型的取值转换；
• SelectBoolFromFloatDict — 将字典中的 Float 值转换为布尔值的辅助运算符。

想继续深入，可阅读 utils 分类说明、data 数据运算符目录、Lib 运算符总览 或运算符索引，并结合 StructuredList.cs 理解 TiXL 底层列表数据模型的设计。

• 音视频
• 图形学
• 桌面应用