パラメータ UI リファレンス (Parameter UI Reference)

このページでは、Python の Parameter で宣言した定義がエディタ上でどのようにレンダリングされるかを対応付けて解説します。パラメータの UI は以下の 3 つの要素によって決定されます：

1. パラメータの type: ウィジェットを選択します（str はテキストフィールド、bool はトグルスイッチ、ImageUrlArtifact は画像ビューアなど）。
2. ui_options: 選択されたウィジェットの挙動や外観を微調整します（非表示、全幅表示、複数行テキストエリア、Web カメラキャプチャボタンの追加など）。
3. トレイト (Traits): UI と振る舞いをパッケージ化して提供します（Slider はスライダー UI のレンダリングと範囲のバリデーションを同時に行い、Options はドロップダウンの表示と選択肢への値制限を同時に行います）。内部的には、トレイトは独自のキーを ui_options に書き込みます。

目的に合ったものがある場合は、生（raw）の ui_options キーを直接指定するよりも、パラメータヘルパークラス（ParameterString, ParameterImage など）やトレイトの利用を推奨します。

非公開キーは内部専用です (Undocumented keys are internal)

エディタは本ページに記載されている以上の ui_options キーを内部的に読み取っています。本ページに記載されていない（またはトレイトが出力しない）キーはエディタ内部専用であり、予告なく変更または削除される可能性があります。

ウィジェット選択の優先順位 (How the widget is chosen)

各パラメータについて、エディタは以下の順序でウィジェットを決定します：

1. ui_options に widget と library が存在する場合（Widget トレイト による設定）、エディタはそのライブラリからカスタムウィジェットをロードします。
2. それ以外の場合、パラメータの type に基づいて下表から組み込みウィジェットを選択します。list[...] 型（任意の要素型）はリストウィジェットを選択します。
3. マッピングが存在しない型の場合、インラインウィジェットは一切レンダリングされません（ラベルと接続ハンドルのみが表示されます）。

型とウィジェットのマッピング (Type-to-widget mapping)

type	ウィジェット
str	単一行テキストフィールド（ui_options やトレイトにより複数行、Markdown、ピッカー等に拡張可能）
int, float	数値入力（Slider トレイトでスライダー化、step でステップ幅指定）
bool	トグルスイッチ
json, JsonArtifact	JSON ビューア/エディタ
python, yaml	シンタックスハイライト付きコードエディタ
html, xml	HTML/XML モードのコードエディタ
dict	キー/値エディタ（画像/動画の比較スライダー機能も提供）
list, list[...]	要素ごとにウィジェットをレンダリングするリストエディタ
button	クリック可能なボタン（Button トレイトで設定）
Status	ステータス/メッセージ表示ブロック
UrlArtifact	URL 表示
ImageUrlArtifact / ImageArtifact, VideoUrlArtifact / VideoArtifact, AudioUrlArtifact / AudioArtifact, ThreeDUrlArtifact / ThreeDArtifact, SplatUrlArtifact / SplatArtifact	メディアビューアおよびエディタ — 詳細は メディアビューアとエディタ を参照
その他すべて	インラインウィジェットなし（ラベルと接続ハンドルのみ）

共通の ui_options (全型共通)

キー	効果
hide	パラメータ全体を完全に非表示（ラベル、ウィジェット、接続ハンドルすべて）。
hide_label	名前ラベルを非表示にし、ウィジェットのみ残す。
hide_property	インラインウィジェットを非表示にし、ラベルと接続ハンドルのみ残す。
display_name	パラメータ名と異なる表示用ラベルテキスト。
is_full_width	ウィジェットをノードの全幅いっぱいに引き伸ばす。
parameter_render_location	兄弟パラメータに対する描画順序: "top"、"in-order"（デフォルト）、"bottom"。

型別の ui_options (Per-type ui_options)

str

キー	効果
multiline	単一行フィールドの代わりに複数行テキストエリアを表示。
markdown	テキストを Markdown としてレンダリング/編集。
placeholder_text	フィールドが空のときに表示されるプレースホルダー。

int / float

キー	効果
step	ステッパーで使用される増分値。エンジンはこの値の倍数であるかを検証。
progress_bar	編集可能な入力の代わりにプログレスバーとして表示（0〜100 の進捗状況など）。

画像型 (Image types)

キー	効果
clickable_file_browser	空のパラメータをクリックするとファイル選択ダイアログが開き、ファイルを自動アップロード。
expander	ビューアの展開/折りたたみを許可。
crop / crop_image	クロップエディタを開くボタンを表示。
edit_mask	ペイントマスクエディタを開くボタンを表示。
edit_excalidraw	Image Bash エディタを開くボタンを表示。
webcam_capture_image	サムネイルを Web カメラのライブプレビューとキャプチャボタンに置き換え。
aspect_ratio	表示領域のアスペクト比を固定（例: "16:9"）。
object_fit	画像の収まり方を制御（CSS の object-fit と同様: "contain" / "cover"）。
pulse_on_run	ノードの実行中にビューアをパルス点滅アニメーション表示。

音声型 (Audio types)

キー	効果
clickable_file_browser	クリックしてファイル選択・アップロード。
microphone_capture_audio	マイクから直接録音するボタンを表示。
pulse_on_run	ノード実行中にプレイヤーをパルス点滅表示。

dict

キー	効果
compare	辞書（{"input_image_1": ..., "input_image_2": ...}）を画像比較スライダーとしてレンダリング。
video_compare	辞書を左右並列の動画比較プレイヤーとしてレンダリング。

トレイト一覧 (Traits)

トレイトは griptape_nodes.traits 配下に定義されており、パラメータの add_trait() または traits={...} 引数でアタッチします：

トレイト	主な対象型	機能	管理する ui_options
Options	str, 汎用	固定の選択肢に制限されたドロップダウン（検索付き）。allow_custom=True でサジェスト入力化。	simple_dropdown, show_search, search_filter, allow_custom
MultiOptions	list	複数選択ドロップダウン。	multi_options
Slider	int, float	min_val と max_val 間のスライダー。soft_limits=True で範囲外の手入力を許容。	slider
Clamp	int, float, シーケンス	代入時に値を範囲内に収める。独自の UI は持たない。	—
Button	button	ボタンのラベル、バリアント、サイズ、クリック動作を設定。	button_label, variant, size, state, full_width
ColorPicker	str	カラーピッカーを開く色見本パッチ。フォーマット（"hex" 等）を検証。	color_picker
FileSystemPicker	str	フィルタリング付きのファイル/ディレクトリ選択ダイアログを開く参照ボタン。	fileSystemPicker
NumbersSelector	dict	最小/最大/ステップの数値範囲セレクター。	numbers_selector
CompareImagesTrait	dict	画像比較スライダーで使用される 2 画像辞書の形状を検証。	—
Widget	汎用	組み込みウィジェットをライブラリ提供のカスタムウィジェットに置き換え。	widget, library