设置字典键值

📖 节点概述

在一个字典中批量设置或更新多个键的值。通过“构建蓝图”多行文本定义需要设置的键路径（每行一条），节点会自动为每个路径生成对应的值输入端口（或使用合并列表模式）。支持嵌套路径（如 user/age）和数组通配符 [*]（为数组中的每个元素设置值）。可选“自动创建中间路径”（默认开启）或“忽略不存在的父级路径”。原字典不会被修改，返回新字典。该节点为纯数据节点，无执行端口。

💡 使用场景：

• 批量字段赋值：一次性设置用户信息中的多个字段，无需多个【更新字典键】节点。
• 动态构建嵌套结构：自动创建不存在的中间字典/数组，方便从零构造复杂 JSON。
• 数组内批量赋值：使用 [*] 通配符为数组中每个对象统一设置某个属性（如状态、时间戳）。
• 表单数据处理：将表单提交的多个字段按路径写入字典。
• 配置文件生成：根据模板路径和值列表，生成符合特定结构的配置字典。

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

节点有三个主要输入端口：原字典、构建蓝图（多行文本），以及根据蓝图动态生成的值输入端口（或一个 新值列表 端口）。输出为 新字典。

场景案例：为用户字典添加年龄字段并批量设置数组内元素状态

1. 准备原字典：{"user": {"name": "张三"}}

2. 编写蓝图（多行）：

   user/age
   tags/[*]/status
   

3. 提供新值：

   • 节点自动生成两个输入端口：user/age 和 tags/[*]/status。
   • 在 user/age 端口输入 25。
   • 在 tags/[*]/status 端口输入 "active"。

4. 获取结果：新字典 输出：

   {
     "user": {"name": "张三", "age": 25},
     "tags": [{"status": "active"}]
   }
   

   （注意 tags 原本不存在，被自动创建为空数组，然后每个元素都被设置 status）

合并输入模式：

• 勾选“合并输入”高级选项。
• 蓝图仍然写多行路径，但只生成一个 新值列表 端口，需传入一个列表，元素顺序与蓝图路径一一对应。
• 例如 新值列表 = [25, "active"]，效果同上。

忽略不存在的路径：

• 勾选该选项后，如果蓝图中某个路径的父级不存在（例如 a/b/c 但 a 不存在），则跳过该赋值，不会自动创建中间字典。

⚙️ 引脚与参数说明

📥 输入引脚（固定）

📥 输入引脚（动态）

⚙️ 控件参数

📤 输出引脚

🔧 路径语法与设置规则

• 斜杠分隔：a/b/c 表示在字典 a 下的键 b 下的键 c 处设置值。
• 数组索引：users/0/name 表示将 users 列表的第 0 个元素的 name 键设置为指定值。
• 数组通配符：users/[*]/status 表示为 users 列表中的每个元素设置 status 键。
  • 如果 users 不存在，节点会自动创建 users: []（空数组），然后通配符会失效？实际行为：当路径到达 [*] 时，如果当前不是列表，节点会根据上下文自动创建：若 [*] 前是一个不存在的键，会先创建一个空列表，然后对空列表做通配符赋值不会有实际效果。建议在使用通配符前确保数组存在或有元素。
  • 更好的实践：先通过其他方式确保数组有元素，或使用索引方式。
• 自动创建父级（默认）：如果路径中的某个中间节点不存在，节点会自动创建空字典或空数组（当遇到 [*] 时创建空数组），确保赋值可以完成。
• 忽略不存在的路径：开启后，若父级不存在则直接跳过，不创建任何内容，也不报错。

⚠️ 注意事项

• 原字典不变：节点返回新字典，不修改输入字典（内部进行深拷贝，注意大数据量时的内存开销）。
• 蓝图去重：如果蓝图中出现重复路径，只有第一次会生成对应的值输入端口，重复路径在运行时会再次赋值（覆盖前一次）。
• 数组通配符的适用场景：[*] 通常用于已有数组且需要批量设置每个元素的某个属性。如果数组为空，通配符赋值不会产生效果。如果数组元素不是字典，通配符赋值会将整个元素替换为新值。
• 动态端口的生命周期：修改“构建蓝图”文本或切换“合并输入”后，动态输入端口会自动增删。删除端口时，连线会自动断开，请注意。
• 值类型智能转换：在独立值模式下，如果值输入端口没有连线且手动输入了数字、布尔值等，节点会自动尝试将字符串转换为对应的 Python 类型（通过 ast.literal_eval），使得 "25" 成为整数 25。若转换失败，则保留为字符串。
• 性能：对于大型字典和复杂路径，批量设置会遍历路径并可能创建大量中间对象，注意控制数据规模。

💎 小贴士：

• 点击眼睛图标（👁️）可以打开可视化面板，预览原字典的结构，同时蓝图中已填写的路径会被高亮显示，方便核对。
• 刷新按钮（🔄）用于手动重新生成动态端口（通常在蓝图修改后自动触发，此按钮作为备用）。
• 清空按钮（🗑️）一键清空蓝图文本并删除所有动态端口。
• 使用数组通配符 [*] 可以快速为对象数组统一添加或修改字段，非常适合批量 API 响应的数据增强。
• 如果需要设置的值是一个列表或字典，可以通过 JSON 字符串的形式传入，节点会自动解析。
• 该节点是纯数据节点，无需执行信号，可在数据流中直接使用。