属性参数体系全解 (Parameters)

参数 (Parameters) 共同构成了算子节点的输入端口 (Inputs)、输出端口 (Outputs) 以及内部属性面板 (Properties)。本篇文档系统覆盖了 Parameter 核心类的全部属性字典、控件特征 (Traits) 扩展机制、内置辅助快捷类、容器数据结构，以及驱动动态自适应参数界面的进阶工业级架构范式。

如需查阅参数类型与前端 Widget 控件的映射规则、ui_options 完整键值清单以及 Traits 体系，请参阅前端 UI 控件渲染参考 (Parameter UI Reference)。

参数核心属性字典 (Parameter Attributes)

Parameter 构造函数暴露的所有核心属性：

name (str)：参数唯一标识符，严禁包含空格等非法字符；
tooltip (str 或 list[dict])：在前端 UI 悬停时呈现的富文本提示说明；
default_value (Any)：参数出厂默认缺省值；
type (str)：底层核心强类型标识（如 "str"、"list[str]" 或 ParameterTypeBuiltin.STR.value）；
input_types (list[str])：作为输入端口时，允许接入的上游数据类型白名单；
output_type (str)：作为输出端口时，对外广播的标准数据类型；
allowed_modes (set[ParameterMode])：允许的工作模式集合（{INPUT, OUTPUT, PROPERTY}）；
ui_options (dict)：用于微调前端渲染细节的高级配置字典；
converters (list[Callable[[Any], Any]])：数据注入时按序执行的数据转换器管道函数列表；
validators (list[Callable[[Parameter, Any], None]])：数据赋值前执行的合法性静态校验器列表；
hide / hide_label / hide_property (bool)：快捷 UI 显隐标记（亦可在 ui_options 中定义；冲突时以 ui_options 字典为准）；
allow_input / allow_property / allow_output (bool)：声明模式的便捷语法糖（若显式传递了 allowed_modes 则忽略此类语法糖）；
settable (bool，默认 True)：是否允许被外部赋值；只读输出或计算派生属性通常设为 False；
serializable (bool，默认 True)：是否参与工作流序列化存盘。若承载的是驱动句柄、底层进程或打开的文件对象，必须显式设为 False。作为输出端口时，设为 False 还能指导引擎将大对象保存在本地进程内存中，仅向跨进程 Worker 广播轻量访问 Key——详见非序列化数据传递；
user_defined (bool，默认 False)：是否为用户在前端动态创建的参数；
private (bool，默认 False)：是否对常规用户折叠隐藏（面向库内部私有调度）；
exclude_from_metadata (bool，默认 False)：指示引擎将该参数值从明文元数据输出中彻底剥离（如导出的 .json 伴生文件与嵌入式 PNG 文本块）。参数名仍会记录在 parameters_omitted 清单中以供审计追溯。适用于承载密码、API Token 等强敏感数据的字段；
parent_container_name (str | None)：声明该参数为某个 ParameterContainer（如 ParameterList 或 ParameterDictionary）的子成员，用于列表式数据聚合；
parent_element_name (str | None)：声明该参数在 UI 上挂载于某个 ParameterGroup 可折叠分组组件下方，用于界面视觉分块组织。

控件特征扩展体系 (Traits)

通过 add_trait() 或在构造函数中以内联集合传递 traits={...}，可以无侵入式为参数赋予高阶交互逻辑：

Options：下拉枚举菜单 Options(choices=list[str] | list[tuple[str, Any]], show_search: bool = True, search_filter: str = "", allow_custom: bool = False)
Slider：数值滑动条 Slider(min_val: float, max_val: float, soft_limits: bool = False) —— 开启 soft_limits=True 时形成“软限制”：滑块滑轨虽限定在该区间，但用户手动在文本框输入超出该范围的极端数值时依然宽容接受；
Button：动作按钮 Button(label: str = "", variant=..., size=..., button_link=... | on_click=..., get_button_state=...)
ColorPicker：物理拾色器面板 ColorPicker(format="hex")
FileSystemPicker：文件系统拾取器 FileSystemPicker(...)（用于直观弹出本地文件/目录浏览器）

有关完整 Traits 列表及其控制的底层 ui_options 键值，请参见前端 UI 控件渲染参考 (Parameter UI Reference)。

Trait 状态持久化机制：Trait 可以通过重写 to_state() 与 apply_state() 参与持久化序列化。只能返回包含文本、数值、布尔值及上述基础类型的简单列表/字典。不支持的值会被告警跳过。

强类型参数辅助快捷类 (`ParameterString`, `ParameterInt`, ...)

Griptape Nodes 在 griptape_nodes.exe_types.param_types.* 命名空间下内置了一整套便捷子类，旨在使常见参数设计更加精简、标准统一且支持运行时动态属性修改：

核心辅助类速查表

辅助构造类	强制的 `type` / `output_type`	默认 `input_types` 宽容行为	关键 UI 专属参数	架构优势与说明
`ParameterString`	`"str"` / `"str"`	`accept_any=True` $\rightarrow$ `["any"]` 并自动通过 `str()` 转换	`markdown`, `multiline`, `placeholder_text`, `is_full_width`	忽略构造函数传入的 `type`/`output_type`，强制纯文本
`ParameterBool`	`"bool"` / `"bool"`	`accept_any=True` $\rightarrow$ `["any"]` 并强转布尔	`on_label`, `off_label`	智能将 `"true"/"false"`、`"yes"/"no"` 字符串转换为布尔
`ParameterInt`	`"int"` / `"int"`	`accept_any=True` $\rightarrow$ `["any"]` 并强转整型	`step`, `slider`, `min_val`, `max_val`, `validate_min_max`	根据参数自动附加 Clamp / MinMax / Slider 特征约束
`ParameterFloat`	`"float"` / `"float"`	`accept_any=True` $\rightarrow$ `["any"]` 并强转浮点	`step`, `slider`, `min_val`, `max_val`, `validate_min_max`	自动配置浮点微调步长与滑动条区间
`ParameterDict`	`"dict"` / `"dict"`	`accept_any=True` $\rightarrow$ `["any"]` 并强转字典	（无）	底层基于 `to_dict()` 深度兼容多种容器转换
`ParameterJson`	`"json"` / `"json"`	`accept_any=True` $\rightarrow$ `["any"]` 并解析 JSON	`button`, `button_label`, `button_icon`	底层集成 `json_repair`，具备超强残缺 JSON 容错纠错能力
`ParameterRange`	`"list"` / `"list"`	`accept_any=True` $\rightarrow$ `["any"]` 并强转列表	`range_slider` + `min_val/max_val/step`	当数值为包含 2 个数字的双元列表时渲染为双向区间滑块
`ParameterImage`	`"ImageUrlArtifact"`	`accept_any=True` $\rightarrow$ `["any"]` (无损直通)	`clickable_file_browser`, `webcam_capture_image`, `edit_mask`, `pulse_on_run`	官方强烈推荐的图像类参数；杜绝大张量 WebSocket 吞吐崩溃
`ParameterAudio`	`"AudioUrlArtifact"`	`accept_any=True` $\rightarrow$ `["any"]` (无损直通)	`clickable_file_browser`, `microphone_capture_audio`, `edit_audio`	专为音频资产定制的前端波形预览与录音捕获
`ParameterVideo`	`"VideoUrlArtifact"`	`accept_any=True` $\rightarrow$ `["any"]` (无损直通)	`clickable_file_browser`, `webcam_capture_video`, `edit_video`	视频流 URL 强类型，杜绝类型名称书写不一致缺陷
`Parameter3D`	`"ThreeDUrlArtifact"`	`accept_any=True` $\rightarrow$ `["any"]` (无损直通)	`clickable_file_browser`, `expander`	三维网格与点云资产视口交互控件
`ParameterButton`	`"button"` / `"str"`	`["str", "any"]`	`label`, `variant`, `size`, `icon`, `state`, `href` / `on_click`	`label` 为展示文本，`default_value` 为存储值

重点核心辅助类详析

1. `ParameterImage`（所有图像算子的绝对强制标准）

在编写图像相关算子时，请始终无条件使用 ParameterImage 代替通用的 Parameter！ 其核心收益包括：

强类型自动锁定为轻量化的 ImageUrlArtifact；
内置开箱即用的本地文件浏览器弹出、网络摄像头拍摄与遮罩涂抹编辑器；
从根源杜绝工作流存盘与 WebSocket 吞吐膨胀：ImageUrlArtifact 仅在网络中传输一个精简的 URL 路径字符串；若错误使用了老旧的 ImageArtifact，图片全量 Base64 字节流会直接塞爆 WebSocket 通道并将工作流 .json 膨胀到几十兆——详见参数有效负载优化 (Parameter Payload Size)。

from griptape_nodes.exe_types.param_types.parameter_image import ParameterImage

# 声明输入图像端口
self.add_parameter(
    ParameterImage(
        name="input_image",
        tooltip="待处理的源图像素材",
        allow_output=False,  # 仅作为输入
    )
)

# 声明输出图像端口
self.add_parameter(
    ParameterImage(
        name="output_image",
        tooltip="生成的高清成片结果",
        allow_input=False,   # 仅作为输出
        allow_property=False,
    )
)

2. `ParameterButton`（交互式动作触发按钮）

按钮用于在属性检查器中提供可点击的触发器，用于即刻触发局部重算、重置计数器或跳转文档：

按钮默认且强制为纯属性模式 (allow_property=True, allow_input=False, allow_output=False)；
必须使用 ParameterButtonGroup 容器组件进行包裹排版；
on_click 回调函数与 href 链接应直接作为参数传给 ParameterButton，无需通过 Button trait 绕路。

from griptape_nodes.exe_types.core_types import ParameterButtonGroup
from griptape_nodes.exe_types.param_types.parameter_button import ParameterButton
from griptape_nodes.traits.button import Button, ButtonDetailsMessagePayload

# 在节点 __init__ 中使用上下文管理器声明按钮组
with ParameterButtonGroup(name="action_buttons") as button_group:
    ParameterButton(
        name="refresh_btn",
        label="刷新资产状态",
        icon="refresh-cw",
        on_click=self._handle_refresh_click,
    )
self.add_node_element(button_group)

def _handle_refresh_click(self, button: Button, payload: ButtonDetailsMessagePayload) -> None:
    # 按钮点击后的回调响应
    self.set_parameter_value("status_text", "已完成刷新")

容器参数架构与关键陷阱 (Containers)

- ParameterList：用于动态容纳多个相同类型的子参数（在代码中通过 get_parameter_list_value() 读取并自动展平）； - ParameterDictionary：用于在面板中维护一组严格保持顺序的键值对集合； - ParameterGroup：纯前端视觉分类组件，在 UI 上形成一个可展开/折叠的高级设置分组框。

⚠️ 严禁混淆 `parent_container_name` 与 `parent_element_name`！

参数对象内部包含两个极易混淆的父级指针属性，其底层工程含义有着云泥之别：

属性名称	指向的目标对象	核心工程职责与用途
`parent_container_name`	`ParameterContainer` (`ParameterList`, `ParameterDictionary`)	数据所有权 (Ownership)：表明该参数属于某个动态列表或字典的数据项。引擎依赖此字段处理数据的展平聚合、子参数销毁以及存盘恢复。
`parent_element_name`	`ParameterGroup`	前端 UI 视觉分组 (UI Grouping)：仅用于将该参数在视觉上收纳进某一个可折叠组内，丝毫不改变参数自身的数据流转逻辑。

致命后果：若将 parent_container_name 错误地指向了 ParameterGroup： 1. 参数会错误脱壳浮动在节点最外层，无法落入组内； 2. 在多次运行之间中间数据无法被干净清理； 3. 工作流保存并重新加载时参数将彻底丢失（引擎反序列化器找不到对应类型的容器，会直接丢弃该参数及其数值！）。

动态自适应参数表面架构范式 (Advanced Dynamic Patterns)

1. 动态自适应显隐 (Dynamic Parameter Visibility)

利用 after_value_set() 生命周期钩子，根据上游选择动态隐藏或唤醒参数：

def after_value_set(self, parameter: Parameter, value: Any) -> None:
    if parameter.name == "generation_mode":
        if value == "text_to_image":
            self.hide_parameter_by_name("input_image")
            self.show_parameter_by_name("prompt")
        elif value == "image_to_image":
            self.show_parameter_by_name("input_image")
            self.show_parameter_by_name("prompt")

    return super().after_value_set(parameter, value)

2. 下拉选项动态热更新 (Dynamic Options Updates)

在运行时从本地磁盘或网络端点读取最新列表并动态更新下拉框：

from griptape_nodes.traits.options import Options

def _update_dropdown(self, param_name: str, new_choices: list[str]) -> None:
    param = self.get_parameter_by_name(param_name)
    if param:
        for trait in param.find_elements_by_type(Options):
            trait.choices = new_choices
            break
        self.set_parameter_value(param_name, new_choices[0] if new_choices else "")

3. 基于 `ParameterTransitionComponent` 优雅切换异构模式

当一个节点拥有一个多选架构下拉框（例如在同一个生成节点中切换 FLUX、SDXL 与 SD3），切换选项会导致参数表完全重塑。如果简单粗暴地将所有参数清空重建，用户此前辛苦拉好的所有外部连线将会全部瞬间断开销毁！

ParameterTransitionComponent 优雅地解决了此难题：它能深度比对当前参数表面与目标参数表面，并在底层计算出四种操作决策：

Preserve (无损保留)：同名同类型同模式参数，连线与数值原样保留，绝对不触碰；
Replace (平滑替换)：同名但数据类型/模式发生微调（例如从接收 str 变更为接收 ImageUrlArtifact）。组件会临时拦截暂存既有物理连线，注销老参数并实例化新参数，随后尝试通过 CreateConnectionRequest 重新发起连线握手。只要类型依然兼容，连线自动恢复！
Remove (智能剔除)：目标架构不需要的专有参数被安全卸载，其独占连线被干净拔除；
Add (动态扩展)：新架构专属的参数被动态长出。

from griptape_nodes.exe_types.param_components.parameter_transition_component import (
    ParameterTransitionComponent,
    TransitionParameter,
)

# 1. 在算子 __init__ 中声明转换组件
self._model_params = ParameterTransitionComponent(
    self,
    manages_parameter=lambda p: p.name in self._DYNAMIC_PARAM_NAMES,
)

# 2. 在模型下拉框变动回调中平滑演进
desired_schema = self._build_desired_schema_for_model(selected_model)
self._model_params.transition_to(desired_schema)