パラメータ (Parameters)

パラメータは、ノードの入力、出力、およびプロパティを定義します。本ページでは、すべての Parameter 属性、トレイト（Traits）システム、パラメータヘルパークラス、コンテナ、および動的なパラメータサーフェスを構築するための高度な設計パターンについて解説します。

パラメータ型とエディタウィジェットのマッピング、サポートされる ui_options キー、トレイト一覧については、パラメータ UI リファレンス (Parameter UI Reference) を参照してください。

パラメータ属性 (Parameter Attributes)

すべての Parameter 属性：

name: str、一意の識別子（空白不可）
tooltip: str または UI ヘルプテキスト用の list[dict]
default_value: 任意のデフォルト値
type: str（例: "str", "list[str]", ParameterTypeBuiltin.STR.value）
input_types: 着信接続で受け入れ可能な型を指定する list[str]
output_type: 送信接続の型を指定する str
allowed_modes: set[ParameterMode] ({INPUT, OUTPUT, PROPERTY})
ui_options: UI カスタマイズ用の dict
converters: 値変換用の callable リスト (list[Callable[[Any], Any]])
validators: バリデーション用の callable リスト (list[Callable[[Parameter, Any], None]])
hide/hide_label/hide_property: 一般的な UI フラグ（ui_options からも設定可能。競合時は ui_options が優先）
allow_input/allow_property/allow_output: モード設定用の簡易フラグ（allowed_modes が明示設定されている場合は無視）
settable: bool（デフォルト: True） - 計算出力専用パラメータ等の場合は False に設定
serializable: bool（デフォルト: True） - 非シリアライズ値（ドライバ、ファイルハンドル等）の場合は False に設定。出力時、この設定は値を生成したプロセス内に保持し、ワーカープロセス境界を越えてキーのみを送信します（シリアライズできない値の受け渡しを参照）
user_defined: bool（デフォルト: False）
private: bool（デフォルト: False） - 一般ユーザー編集から非表示（ライブラリ内部使用用）
exclude_from_metadata: bool（デフォルト: False） - プレーンテキストメタデータ出力（サイドカー JSON および埋め込み PNG テキストチャンク）からこのパラメータの値を除外します。除外された事実は parameters_omitted に記録されるため監査可能です。パスワードや認証情報などの機密データを扱うパラメータに使用します。
parent_container_name: str|None — ParameterContainer（ParameterList または ParameterDictionary）の子として割り当てます。
parent_element_name: str|None — ParameterGroup（UI グルーピング要素）の下にネストします。UI 上で視覚的に整理するために使用します。

トレイト (Traits)

add_trait() 経由で特殊な機能や UI 表現を追加します：

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(...)（ファイル/ディレクトリ選択ダイアログ UI）

トレイトの完全な一覧、レンダリングされるウィジェット、管理される ui_options キーについては、パラメータ UI リファレンス (Parameter UI Reference) を参照してください。

パラメータヘルパー構造 (`ParameterString`, `ParameterInt`, ...)

Griptape Nodes は、griptape_nodes.exe_types.param_types.* 配下に便利な Parameter サブクラス群を提供しています。これらは、一般的なパラメータパターンを シンプル、一貫性があり、実行時に変更可能 にするために用意されています。

クイックリファレンステーブル

ヘルパー	強制される `type` / `output_type`	デフォルトの `input_types` 挙動	主な UI 簡易引数	備考
`ParameterString`	`"str"` / `"str"`	`accept_any=True` → `["any"]`（`str` への自動変換）	`markdown`, `multiline`, `placeholder_text`, `is_full_width`	`type`, `output_type`, `input_types` コンストラクタ引数は無視
`ParameterBool`	`"bool"` / `"bool"`	`accept_any=True` → `["any"]`（`bool` への自動変換）	`on_label`, `off_label`	`"true"/"false"`, `"yes"/"no"` などの文字列を自動変換
`ParameterInt`	`"int"` / `"int"`	`accept_any=True` → `["any"]`（`int` への自動変換）	`step`, `slider`, `min_val`, `max_val`, `validate_min_max`	引数に基づいて制約トレイト（Clamp/MinMax/Slider）を自動付与
`ParameterFloat`	`"float"` / `"float"`	`accept_any=True` → `["any"]`（`float` への自動変換）	`step`, `slider`, `min_val`, `max_val`, `validate_min_max`	引数に基づいて制約トレイト（Clamp/MinMax/Slider）を自動付与
`ParameterDict`	`"dict"` / `"dict"`	`accept_any=True` → `["any"]`（`dict` への自動変換）	なし	変換に `griptape_nodes.utils.dict_utils.to_dict()` を使用
`ParameterJson`	`"json"` / `"json"`	`accept_any=True` → `["any"]`（JSON への自動変換）	`button`, `button_label`, `button_icon`	文字列解析に `json_repair.repair_json()` を使用
`ParameterRange`	`"list"` / `"list"`	`accept_any=True` → `["any"]`（`list` への自動変換）	`range_slider` + `min_val/max_val/step`, ラベル	値が要素数 2 の数値リストの場合にスライダーとして動作
`ParameterImage`	`"ImageUrlArtifact"` / `"ImageUrlArtifact"`	`accept_any=True` → `["any"]`（無変換）	`clickable_file_browser`, `webcam_capture_image`, `edit_mask`, `pulse_on_run`	画像用の標準ヘルパー。型変換が必要な場合はコンバータを追加
`ParameterAudio`	`"AudioUrlArtifact"` / `"AudioUrlArtifact"`	`accept_any=True` → `["any"]`（無変換）	`clickable_file_browser`, `microphone_capture_audio`, `edit_audio`, `pulse_on_run`	音声用の標準ヘルパー
`ParameterVideo`	`"VideoUrlArtifact"` / `"VideoUrlArtifact"`	`accept_any=True` → `["any"]`（無変換）	`clickable_file_browser`, `webcam_capture_video`, `edit_video`, `pulse_on_run`	動画用の標準ヘルパー
`Parameter3D`	`"ThreeDUrlArtifact"` / `"ThreeDUrlArtifact"`	`accept_any=True` → `["any"]`（無変換）	`clickable_file_browser`, `expander`, `pulse_on_run`	3D モデル用の標準ヘルパー
`ParameterButton`	`"button"` / `"str"`	`["str", "any"]`	`label`, `variant`, `size`, `icon`, `state`, `href` / `on_click`	Label は表示テキスト、`default_value` は格納値

`ParameterImage`（画像パラメータの推奨ベストプラクティス）

画像の入力/出力には、汎用 Parameter ではなく常に ParameterImage を使用してください。

自動的に type="ImageUrlArtifact" および output_type="ImageUrlArtifact" が設定されます。
ファイルブラウザ、Web カメラキャプチャ、マスク編集などの UI 機能があらかじめ統合されています。
ペイロードサイズの削減: 汎用の ImageArtifact は WebSocket 通信やワークフロー保存ファイル内に画像バイト列をインライン展開してしまいますが、ImageUrlArtifact は短い URL 文字列のみを保持するため軽量で高速です（詳細はパラメータペイロードサイズを参照）。

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,
    )
)

コンテナ (Containers)

ParameterList: 複数の子 Parameter を所有するコンテナ（値の取得には get_parameter_list_value() を使用）
ParameterDictionary: 順序付けられたキー/値ペアを所有するコンテナ（単一 dict 値を扱う ParameterDict とは異なります）
ParameterGroup: UI 上での視覚的グルーピング要素

parent_container_name と parent_element_name の極めて重要な違い:

属性	対象先	役割
`parent_container_name`	`ParameterContainer` (`ParameterList`, `ParameterDictionary`)	所有権 (Ownership)。パラメータがリストや辞書コンテナの子要素であることを示します。子要素のクリーンアップや値の集約に使用されます。
`parent_element_name`	`ParameterGroup`	UI グルーピング。UI 上で折りたたみ可能なグループボックス内に視覚的にネストします。

両者を混同しないでください。 誤って使用すると、ノードのルートにパラメータが表示されたり、実行間のクリーンアップが行われなくなったり、保存/再読み込み時にパラメータが消失する原因となります。

ParameterList または ParameterDictionary に入れる場合 → parent_container_name を使用
視覚的な整理のために ParameterGroup に入れる場合 → parent_element_name を使用

一般的なパラメータパターン (Common Parameter Patterns)

ファイルブラウザ付きファイルパス選択

ディスクからファイルやディレクトリを選択させるには、str パラメータに FileSystemPicker トレイトを追加します：

from griptape_nodes.traits.file_system_picker import FileSystemPicker

Parameter(
    name="config_path",
    type="str",
    tooltip="設定ファイルへのパス",
    allowed_modes={ParameterMode.INPUT, ParameterMode.PROPERTY},
    traits={
        FileSystemPicker(
            allow_files=True,
            allow_directories=False,
            file_extensions=[".json", ".yaml"],
        )
    },
)

高度なパラメータパターン (Advanced Parameter Patterns)

動的パラメータ表示制御 (Dynamic Parameter Visibility)

after_value_set() コールバックを使用してコンテキストに応じた UI を実現します：

def after_value_set(self, parameter: Parameter, value: Any) -> None:
    """モデル選択に応じてパラメータの表示/非表示を切り替え"""
    if parameter.name == "model":
        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)

ParameterTransitionComponent による動的スキーマ遷移

モデルセレクターやモード切り替えなど、ユーザーの選択肢によって入出力パラメータのセットが大きく変化するノードでは、安易に全パラメータを再構築すると既存の接続配線がすべて破壊されてしまいます。 ParameterTransitionComponent は、現在のパラメータと新しい選択肢が必要とするパラメータの差分（Diff）を計算し、以下の 4 つのアクションを自動実行します：

Preserve (保持): 両方に存在しシグネチャが一致するパラメータ。一切手を加えず接続を完全維持。
Replace (置換): 同名だが型やモード等のシグネチャが異なるパラメータ。接続情報を退避し、新しいパラメータを生成した後、再接続を試行。互換性のある配線のみ復元。
Remove (削除): 新しいスキーマに存在しないパラメータを削除（接続も解除）。
Add (追加): 新しく必要になったパラメータを追加。

これによって、ユーザーがモデルを切り替えても共通のパラメータ接続（プロンプト、解像度、シード値など）が破棄されずに維持されます。