列表插入

📖 节点概述

向列表中插入一个新元素到指定位置。如果插入位置为负数，则表示从末尾倒数；插入位置超出范围时会自动调整到边界（小于0时插入到开头，大于列表长度时插入到末尾）。原列表保持不变，返回插入后的新列表。该节点为纯数据节点，无执行端口。

💡 使用场景：

• 动态构建列表：根据条件在特定位置添加元素（如插入到队列头部）。
• 数据预处理：在列表开头或结尾添加哨兵元素。
• 顺序调整：将某个元素移动到指定位置（先删除再插入）。
• 批量插入：在循环中多次调用本节点，逐步构建复杂顺序的列表。
• 配置生成：在默认配置列表的指定位置插入用户自定义配置项。

🎮 实战连线指南：如何正确使用它？

节点有三个输入端口：原列表、插入位置、新元素，输出端口 新列表。

场景案例：在水果列表的第二个位置插入“橙子”

1. 准备原列表：在“原列表”多行文本框输入：

   apple
   banana
   cherry
   

   或从上游传入列表 ["apple", "banana", "cherry"]。

2. 设置插入位置：输入 1（索引从0开始，1表示第二个位置）。

3. 设置新元素：输入 "orange"（或连线传入）。

4. 获取结果：新列表 输出 ["apple", "orange", "banana", "cherry"]。

5. 后续使用：将新列表用于展示或继续处理。

负位置示例：

• 列表 [1,2,3]，插入位置 -1（末尾）→ 插入到末尾：[1,2,3,新元素]。
• 插入位置 -2（倒数第二个之前）→ 如 [1,2,3] 中插入 X 到 -2，结果 [1,X,2,3]。

边界自动调整：

• 插入位置 10（超过长度）→ 插入到末尾。
• 插入位置 -10（远小于0）→ 插入到开头。

⚙️ 引脚与参数说明

📥 输入引脚

⚙️ 控件参数

📤 输出引脚

🔧 行为说明

• 节点首先将原列表解析为 Python 列表（支持多种输入格式）。
• 根据插入位置计算实际索引：
  • 若位置 < 0，转换为正索引：pos = max(0, len(items) + pos + 1)（例如 -1 → len(items)，插入到末尾）。
  • 若位置 > len(items)，则限制为 len(items)（末尾）。
  • 最终调用 list.insert(pos, new_item)。
• 返回新列表。

⚠️ 注意事项

• 原列表不变：节点返回的是新列表，原输入列表不会被修改。
• 插入位置默认为 -1：即默认在末尾追加元素（类似 append 行为）。
• 元素类型：新元素 可以是任意类型，包括 None、列表、字典等，会原样插入。
• 列表输入格式：与【列表反转】节点相同，支持列表对象、JSON 数组、多行文本。
• 空列表：原列表为空时，插入位置无论多少，新元素都会成为唯一的元素。
• 性能：插入操作的时间复杂度为 O(n)，因为需要移动插入位置之后的元素。

💎 小贴士：

• 若需要在末尾添加元素，也可使用【列表追加】节点（如果存在），但本节点同样支持（插入位置 -1）。
• 若需要在开头插入元素，设置插入位置为 0。
• 配合【列表截取】或【列表删除】节点，可以实现元素的移动（先删除再插入）。
• 由于是纯数据节点，可以在数据流中多次调用，逐步构建复杂列表。
• 插入位置支持动态计算，例如将【列表长度】的输出作为插入位置，实现追加到末尾。