跳转至

前端 UI 控件渲染参考 (Parameter UI Reference)

本篇文档系统梳理了在 Python 端声明的 Parameter 参数与 Griptape Nodes 画布编辑器前端 Widget 控件之间的映射体系。决定一个参数在前端呈现形态的核心三要素：

  1. 参数强类型 type：决定了采用哪个基础 Widget 控件（如 str 映射单行文本框、bool 映射滑动开关、ImageUrlArtifact 映射图像视口组件）；
  2. ui_options 高级属性字典：对基础控件实施微观样式微调（完全隐藏、全宽拉伸、启用多行文本、注入摄像头捕获按钮等）；
  3. 控件特征 (Traits)：将 UI 表现与底层运行期行为深度捆绑（如 Slider 不仅渲染滑动条而且在底层进行数值范围硬约束校验，Options 不仅渲染下拉框而且强制约束赋值范围）。Trait 底层会自动向 ui_options 写入受保护的配置项——因此使用 Traits 是操纵这些配置的最佳官方途径。

在绝大多数场景下，请优先选用官方封装好的 参数快捷辅助类（如 ParameterString、ParameterImage 等）及 Traits 体系；只有在进行纯表现层样式微调时，才直接写入原生的 ui_options 字典键值。

未收录在文档中的内部私有属性警示

前端编辑器引擎读取的 ui_options 内部保留键值远多于本页列出的清单。凡未在本页列明（或未由官方 Trait 对外广播）的键值皆属内部未稳定实现，可能在没有向前兼容通知的情况下被重构或移除。

前端 Widget 控件推断决策流

针对画布中的每一个参数，编辑器严格按以下优先级决定渲染的控件：

  1. 若 ui_options 包含了 widget 与 library 标识（通常由 Widget Trait 注入），编辑器会从对应扩展库中动态拉取并装载自定义的前端 JavaScript 小部件；
  2. 否则，根据参数的 type 强类型，在下方内建控件表中匹配映射；若声明为 list[...] 泛型，则无条件选中列表控件；
  3. 若数据类型在表中没有任何映射，则不渲染内嵌的编辑控件——参数表面仅保留文本标签与外部物理连线插槽，不提供就地文本编辑。

数据类型与内建控件映射表 (Type-to-widget)

参数声明类型 type 前端呈现的内建 Widget 控件形态
str 单行文本框（可通过 ui_options 或 Traits 升级为多行文本框、Markdown 编辑器或文件拾取器）
int, float 数字微调输入框（可通过 Slider Trait 升级为滑动条；可通过 step 设定步长）
bool 现代滑动 Toggle 开关
json, JsonArtifact 结构化 JSON 可视化查看器与代码编辑器
python, yaml 带现代语法高亮的专业代码编辑器
html, xml HTML / XML 专有高亮代码编辑器
dict 结构化键值对编辑器；亦可作为双图/双视频对比滑块的宿主（参见 dict 配置）
list, list[...] 列表编辑器，为集合中的每一个元素自动渲染一个对应的微型子控件
button 可点击交互的动作按钮（通过 Button Trait 进行深度定制）
Status 运行状态与提示消息公告块
UrlArtifact URL 网址链接文本展示区
ImageUrlArtifact / ImageArtifact,
VideoUrlArtifact / VideoArtifact,
AudioUrlArtifact / AudioArtifact,
ThreeDUrlArtifact / ThreeDArtifact,
SplatUrlArtifact / SplatArtifact		 富媒体视口监视器与内建编辑器——功能详见 媒体视口与编辑器指南
其他任意非标类型 不呈现内嵌交互控件；仅渲染参数标签文字与物理连线连接插槽

注：GLTFArtifact / GLTFUrlArtifact 依然向下兼容渲染为 3D 视口；在编写新算子时请统一采用官方推荐的 ThreeD 系列类型。

全类型通用的 ui_options 核心样式字典

以下键值适用于任意类型的参数：

配置键名 核心视觉与交互影响
hide 将该参数在前端完全抹除隐藏（隐藏标签、隐藏输入框、隐藏物理连线插槽）。
hide_label 隐藏参数左侧或上方的文本标签名称，但保留编辑控件本身。
hide_property 隐藏内嵌的编辑控件，但保留参数文本标签与外部连线插槽。
display_name 在 UI 面板上渲染的人类可读别名（当希望展示名称不同于 Python 代码中的物理 name 时使用）。
is_full_width 强制将该控件水平横向撑满整个节点卡片的物理宽度。
parameter_render_location 控制该参数相对于同级参数的渲染堆叠次序："top"（置顶）、"in-order"（默认按添加顺序）、"bottom"（置底）。

面向特定类型的专属 ui_options 字典

1. str 文本类型

配置键名 详细功能说明
multiline 渲染为支持自动换行与滚动条的多行文本大文本域 (textarea)。
markdown 启用富文本 Markdown 渲染与编辑模式。
placeholder_text 当文本框内容为空时呈现的灰色占位提示词（在代码编辑器中同样生效）。

2. int / float 数值类型

配置键名 详细功能说明
step 数字输入框增减按钮的步长步进值；引擎在校验时同样会验证输入数值是否为步长的整数倍。
progress_bar 将输入框替换为不可编辑的水平进度条（专用于节点对外汇报耗时或 0~100 百分比）。

提示：若需构建带上下限范围的滑动条，请始终使用 Slider Trait 而非手动书写 ui_options["slider"]——Trait 内部会自动完成数值边界的校验。开启 soft_limits=True 时允许用户键盘手动输入越界数值。

3. 图像多媒体类型 (ParameterImage / ImageUrlArtifact)

配置键名 详细功能说明
clickable_file_browser 开启点击上传功能：点击空白图像占位区即刻弹出系统本地文件拾取窗口；选中的文件会自动上传。
expander 允许用户在节点表面将图像预览视口自由展开或折叠。
crop / crop_image 在图像右上角显示裁剪图标，点击即可调起交互式几何裁剪视窗。
edit_mask 显示蒙版涂鸦按钮，点击即可呼出 Paint Mask 专属绘制层。
edit_excalidraw 显示涂鸦编辑按钮，直接唤醒 Image Bash 进行视觉手绘标注。
webcam_capture_image 将静态缩略图替换为本地摄像头的实时动态取景器与快门抓拍按钮。
aspect_ratio 强制锁定视口画幅比例（例如 "16:9"、"1:1" 等）。
object_fit 画面在框架内的贴合模式（遵循标准 CSS 规则，如 "contain" 等比完整包裹、"cover" 充满裁切）。
hide_details 折叠隐藏缩略图下方展示的物理分辨率、文件大小与资产名元数据栏。
pulse_on_run 当该节点处于 RESOLVING 运行计算状态时，该图像视口会呈现平滑呼吸灯微光动效。

4. 音频多媒体类型 (AudioUrlArtifact)

配置键名 详细功能说明
clickable_file_browser 点击弹出本地音频文件浏览与上传窗口。
microphone_capture_audio 显示麦克风录制按钮，支持在浏览器中直接原声录制音频。
pulse_on_run 运行阶段播放器边框呈现呼吸动效。

5. 字典容器类型 (dict)

配置键名 详细功能说明
compare 将形如 {"input_image_1": ..., "input_image_2": ...} 的双图字典在前端直接渲染为工业级左右卷帘对比滑块（推荐搭配 CompareImagesTrait 校验数据结构）。
video_compare 将字典结构在前端渲染为并排左右分屏的视频同步播放对比视口。

6. JSON 与 列表结构 (json / list)

  • json：modal=True 将内嵌代码编辑框变更为点击后以独立模态大弹窗打开；
  • list：collapsed=True 初始状态默认折叠列表；columns=N 将子项按 N 列栅格网格排版。

控件特征体系全览 (Traits)

Traits 统一存放于 griptape_nodes.traits 命名空间下。每一个 Trait 都会全自动代理底层的 ui_options 键值。在代码中请始终调用 Trait，严禁直接手写底层私有键名：

Trait 类名 典型适用类型 核心业务功能与交互行为 底层写入的 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 结构化数字选择器（Min/Max/Step 联合选择面板）。 numbers_selector
CompareImagesTrait dict 严格校验供图像对比滑块消费的双图字典结构合法性。 —
Widget 任意类型 彻底置换原生内建控件，改用三方扩展库打包的独立 JavaScript 自定义小部件。 widget, library

下拉选项仅作提示而非硬约束的场景 (allow_custom=True)

在出厂默认配置下，Options 会将 choices 列表作为全集硬边界对待：超出选项列表的数值会被直接回退归一至第一项，且手动赋值非法项会触发校验异常阻断。

当候选项列表仅仅是给用户的“参考推荐预设”（例如推荐模型列表），且用户完全有权利手动输入列表中未收录的自定义模型 ID（如私有微调模型或服务商刚刚上线的最新架构）时，请务必开启 allow_custom=True：

from griptape_nodes.exe_types.core_types import Parameter
from griptape_nodes.traits.options import Options

Parameter(
    name="model_id",
    type="str",
    tooltip="可从常用推荐列表中快速挑选，亦可直接手动输入任意模型 ID",
    traits={Options(choices=SUGGESTED_MODELS, allow_custom=True)},
    default_value=SUGGESTED_MODELS[0],
)

开启该标记后，参数在前端会呈现为支持输入联想推荐的灵活文本框，允许用户键入任意自定义内容；同时底层转换器与校验器会宽容放行，确保算子永远具备拥抱未来未知模型标识的极高伸缩性。