UI控件 (UI Schema)

本章节系统介绍 GdiSDK 中用于描述模块参数 UI 交互的 UI Schema / AttributeSchema 体系， 以及它与 GDIM 平台之间的关系。对应代码主要位于 gdisdk.pipeline.pipeData 和 gdisdk.pipeline.pipeline 中的若干 Pydantic 模型， 例如 gdisdk.pipeline.pipeData.UIAttributeSchema 及其子类。

总体来看：

  • ui schema 的直接作用：让 Pipeline / 模块的「Python 参数」映射成一组结构化的 UI 控件；

  • ui schema 与 GDIM 的关系：GDIM 在加载 .pipe 文件时，会读取这些 ui schema，自动生成参数表单， 让最终用户可以在 Web 端安全地配置模块参数，而无需理解底层代码；

  • 额外能力：在上传 Pipeline 后，GDIM 还支持通过可视化拖拽控件的方式设计参数区和结果区的布局， ui schema 提供「字段和控件的语义」，GDIM 则负责「编排和排版」。

什么是 UI Schema？

在 gdisdk.pipeline.pipeline.PipeModule 中，可以选择性地重写 update_ui_schema， 返回一个以「参数名」为键、以 UIAttributeSchema 派生类为值的字典，用来描述 「这个参数应该如何在 UI 中展示和编辑」：

from gdisdk.pipeline.pipeData import UIAttributeSchema, FloatAttributeSchema


def update_ui_schema(self, reset: bool = False) -> dict[str, UIAttributeSchema]:
    return {
        "threshold": FloatAttributeSchema(
            title="阈值",
            default=self.threshold,
            minimum=None,
            maximum=None,
        ),
    }

当 Pipeline 被保存为 .pipe 并上传到 GDIM 后：

  • GDIM 会读取通过 PipeLine.add_attribute 注册到 Pipeline 属性中的 ui schema，基于这些属性生成参数控件（输入框、下拉、多选、文件选择等）； 模块内部的 update_ui_schema 只是提供了一份「默认定义」，真正生效的是 Pipeline 属性上的 ui schema，且可以在 add_attribute(..., ui_schema_overrides=...) 中被重写；

  • 应用配置者还可以在 GDIM 管理端使用可视化拖拽方式，调整这些控件和结果展示组件的布局， 例如把某些参数放在同一分组、将主结果图表放在首屏等。

因此可以理解为： ui schema 是为了让 Pipeline 能够在 GDIM / 其他前端上「可视化运行」而生的， 它把模块的内部参数暴露为结构化表单字段，方便非开发者安全地修改参数。

常用 UIAttributeSchema 类型概览

除 CustomAttributeSchema 外，其他具体控件类型均继承自 gdisdk.pipeline.pipeData.BaseAttributeSchema。 该基类中包含了一组通用字段，例如：

  • title：在 UI 中显示的标题；

  • default：默认值；

  • required：是否必填；

  • visible / readonly：是否在 UI 中可见、是否只读；

  • units：物理量单位（通常来自 gdisdk.dataclass.terminologies 中的 Units）；

  • selections / selections_name：枚举 / 下拉值列表及其显示名；

  • depends_on：依赖的模块参数或端口名（如 "InputToken"），用于动态更新选项；

  • widget：建议使用的前端控件类型（如 "select"、 "textarea" 等）；

  • widget_attributes：补充的控件配置（例如「下拉启用搜索」「多选」等）。

在此基础上，常见的子类包括（均定义在 gdisdk.pipeline.pipeData 中）：

  • StringAttributeSchema 文本输入；可通过 selections / selections_name 配置为下拉框 / 单选框等。

  • IntegerAttributeSchema / FloatAttributeSchema 整数 / 浮点数输入；支持 minimum / maximum / exclude_minimum / exclude_maximum 等数值约束。

  • BooleanAttributeSchema 布尔开关，一般在 UI 中表现为滑动开关。

  • ArrayAttributeSchema 列表 / 多选类控件，常见场景包括「多选表名」「多选列名」等； 通过 items 指定单个元素的 Schema（通常是 StringAttributeSchema）， 并可使用 min_items / max_items 控制长度。

  • ObjectAttributeSchema 复杂嵌套对象；通过 properties 定义子字段，用于「结构化配置」场景，例如多字段组合参数。

  • FileAttributeSchema 文件或 GDIM 文件对象配置；通常对应「文件选择 / 上传 / 下载」类控件， 常见于需要用户选择报告模板、上传 Excel、下载生成文件等场景。

  • CustomAttributeSchema``（``vtype="general"） 自定义 UI，不由 GDIM 自动生成控件。用于地图选点、专用编辑器等需要前后端单独约定的场景。 仅可作为顶层 Pipeline 属性使用，不能嵌套在 object / array / table 中。 通过 title、description、``default``（示例值）等字段与前端开发者对齐数据结构； 实际取值校验由模块代码负责。

与 PipeLine 属性及 GDIM UI 的协同

在模块内部定义好 update_ui_schema 之后，通常会通过 PipeLine.add_attribute 把关键参数提升为 Pipeline 属性，供 GDIM 或其他前端统一配置，例如：

pipeline.add_attribute(
    attr_name="tpl_number",
    module_name="QueryTable",
    param_name="tpl_number",
    attr_title="沉降点编号",
)

这里：

  • 模块 QueryTable 的 update_ui_schema 定义了 tpl_number 字段的 ui schema （值类型、下拉选项、是否多选等）；

  • add_attribute 则把它映射为 Pipeline 层的一个属性 tpl_number， 让 GDIM 可以在「应用配置界面」中展示为一个可编辑控件；

  • 运行时，GDIM 会把用户在表单里填写的值写回 Pipeline，再由 Pipeline 写回对应模块参数。

add_attribute 还支持 ui_schema_overrides 参数，可以在 不改动模块源码 的前提下， 对字段的 ui schema 做二次定制，例如：

from gdisdk.llm.promptTemplates import SystemDomainPrompt

pipeline.add_attribute(
    attr_name="system_prompt",
    module_name="TableAnalyzer",
    param_name="system_prompt",
    attr_title="智能助手角色",
    ui_schema_overrides={
        "default": SystemDomainPrompt.GEOLOGICAL.value,
        "selections": [
            SystemDomainPrompt.GEOLOGICAL.value,
            SystemDomainPrompt.GEOTECHNICAL_ENGINEERING.value,
            SystemDomainPrompt.HYDROGEOLOGY.value,
            SystemDomainPrompt.GROUNDWATER_CONTAMINATION.value,
        ],
        "selections_name": [
            "地质专家",
            "岩土工程专家",
            "水文地质专家",
            "地下水污染专家",
        ],
    },
)

这套机制的配合效果是：

  • 模块作者 只需在 update_ui_schema 中声明字段类型和基本 UI 行为；

  • Pipeline 作者 / 应用配置者 可以在不改源码的情况下，针对具体应用场景调整默认值、选项、可见性等；

  • GDIM 平台 则基于这些结构化信息，把参数和结果以表单 + 组件的形式「编排」成应用界面， 包括通过拖拽来调整布局、分组、标签页等。

更多示例与推荐阅读

  • 用户指南 (User Guide) 中的「如何定义Pipeline的UI交互」「如何定义模块的UI交互」两节， 展示了 ui schema 与 Pipeline 属性、GDIM 前端之间的完整闭环流程；

  • gdisdk.modules.readers 中的 GdimTableReader、gdisdk.modules.widgets 中的 PythonCoder 等模块，包含了更多动态控件、复杂对象配置的实际写法；

  • gdisdk.pipeline.pipeline 中 PipeLine.add_attribute 方法。