如何配置动态表单

功能概览

动态表单配置功能允许您以声明方式为 Pipeline 和 Task 等资源配置友好的交互体验。无需编写前端代码,只需在资源的 annotations 中添加 style.tekton.dev/descriptors 配置,即可实现:

  • 动态生成表单:自动为资源参数生成交互式表单,在编排和执行 Pipeline 与 Task 时提供更好的体验。
  • 丰富的组件支持:提供文本框、选择器、开关、YAML 编辑器等多种表单组件。
  • 字段验证:内置验证规则,确保用户输入符合要求。
  • 动态获取数据:支持通过 API 动态加载选项数据。
  • 字段链接:为特定字段添加产品或外部链接。
  • 仅元数据配置:在不覆盖字段默认组件的情况下,添加标签、描述、工具提示、禁用状态、预览或链接。
  • 结构化数组编辑:将字符串数组中的每一项拆分为一个或多个可编辑字段。
  • 组合输入:为一个 Pipeline 参数呈现多个相关控件,并在执行前合并这些控件的值。
  • 嵌套表单:加载所选资源的配置,并在当前表单中呈现其参数。
  • 本地化元数据:以多种语言维护显示名称、描述和工具提示,同时保留原始的 Tekton 名称和值。

动态表单行为可在主要 Pipeline 工作流中复用:

产品领域动态表单的使用方式
Pipeline 和 Task 编写配置参数控件,并维护 Params、Workspaces、Results 和 Tasks 的显示元数据。
Pipeline 和 Task 详情显示便于业务理解的标签、描述和工具提示,同时保留原始 Tekton 名称可见。
PipelineRun、TaskRun 和 Run Template 执行复用所选 Pipeline 或 Task 描述符,以支持选择器、结构化编辑器、嵌套表单、预览和运行时设置。
集成配置使用所选 ResourceInterface 或 Connector 提供的描述符来配置特定于 Integration 的控件和选项。
Trigger 和 ScheduledTrigger 配置复用目标 Run Template 的运行配置。事件变量通过 TriggerBinding 和所选启动方法进行配置。

如果字段没有受支持的描述符,产品将保留其常规 输入控件和原生 Tekton 行为。

使用场景

  • Pipeline 编排/运行时:在编排或触发 Pipeline 时,允许用户通过友好的表单填写 namespace 和 secrets 等参数
  • Task 复用:在 Task 或 Pipeline 模板级别,为常用参数提供默认值、下拉选项和验证
  • 多环境选择:通过 API 动态查询可用环境或配置,并将其用作选择选项
  • 结构化配置:编辑 KEY=VALUE、JSON 字符串或其他结构化数组项等值,无需手动格式化每个字符串
  • 基于资源的配置:选择资源并在行内配置其参数,例如为所选模板配置值
  • 一致的 Pipeline 编写和执行:在 Pipeline 编辑、Task 配置、PipelineRun 和 TaskRun 表单中复用相同的参数元数据和动态控件

快速入门

基本配置结构

所有配置都通过 style.tekton.dev/descriptors 中的 annotations 字段定义:

metadata:
  annotations:
    style.tekton.dev/descriptors: |
      - path: params.parameter-name
        x-descriptors:
          - configuration-item1
          - configuration-item2

配置说明

  • path:根据所描述的资源字段,使用 params.<parameter-name>、workspaces.<workspace-name> 或 results.<result-name>。
  • x-descriptors:配置项数组,每个配置项以 urn:alm:descriptor: 开始

简单示例

为 Task 参数配置一个必填文本输入框:

apiVersion: tekton.dev/v1
kind: Task
metadata:
  name: simple-task
  annotations:
    style.tekton.dev/descriptors: |
      - path: params.gitURL
        x-descriptors:
          - urn:alm:descriptor:label:zh:GitRepo
          - urn:alm:descriptor:com.tectonic.ui:text
          - urn:alm:descriptor:placeholder:zh:Git URL
          - urn:alm:descriptor:com.tectonic.ui:validation:required
spec:
  params:
    - name: gitURL
      type: string
  steps:
    - name: clone
      image: alpine/git
      script: |
        git clone $(params.gitURL)

能力选择指南

使用下表选择符合需求的最小描述符集合。

需求推荐配置显式组件描述符
仅更改字段标签、描述或工具提示基本元数据描述符不需要
保留默认输入行为,但添加字段元数据或链接仅元数据配置不需要
呈现特定输入控件,例如文本框、多行文本框、选择框、开关或 YAML 编辑器组件类型描述符必需
提供固定值或基于表达式的默认值默认值描述符通常必需
验证用户输入验证描述符必需
从 API 加载选择选项带动态选项的选择组件必需
预览所引用的资源内容预览描述符不需要;可与一个描述符组合使用
添加指向产品指南或外部 URL 的字段链接链接描述符不需要;可与一个描述符组合使用
将一个参数拆分为多个子输入组合组件必需
将字符串数组中的每一项编辑为结构化字段数组表格组件必需
在当前字段中显示所选资源的参数行内表单组件必需
以多种语言维护显示元数据Params、Workspaces 和 Results 的描述符元数据不需要

基本元数据

表单标签

# Label for the form
- urn:alm:descriptor:label:en:English Name
- urn:alm:descriptor:label:zh:Chinese name

表单描述

# Description for the form
- urn:alm:descriptor:description:en:English Description
- urn:alm:descriptor:description:zh:Chinese Description

占位符提示

# Placeholder for the form
- urn:alm:descriptor:placeholder:en:This is a Placeholder
- urn:alm:descriptor:placeholder:zh:This is a Placeholder

表单帮助工具提示

# Help tooltip for the form
- urn:alm:descriptor:tooltip:en:This is a Help Tip
- urn:alm:descriptor:tooltip:zh:This is a Help Tip

表单禁用状态

# Whether the form is disabled
- urn:alm:descriptor:com.tectonic.ui:disabled

不使用组件的仅元数据配置

您可以配置字段元数据和增强功能,而无需声明表单组件,例如 text、select 或 widgets:select。

在此模式下,UI 会保留参数输入项的默认呈现组件,仅应用受支持的描述符增强功能。当您希望改善显示文本或添加帮助链接,但不改变参数的输入行为时,此模式非常有用。

- path: params.mailSubject
  x-descriptors:
    - urn:alm:descriptor:label:en:Mail Subject
    - urn:alm:descriptor:label:zh:Mail Subject
    - urn:alm:descriptor:description:en:Used to render the notification title.
    - urn:alm:descriptor:description:zh:Used to render the notification title.
    - urn:alm:descriptor:tooltip:en:Rendered at runtime.
    - urn:alm:descriptor:tooltip:zh:Rendered at runtime.

仅元数据模式支持以下描述符:

  • urn:alm:descriptor:label:*
  • urn:alm:descriptor:description:*
  • urn:alm:descriptor:tooltip:*
  • urn:alm:descriptor:com.tectonic.ui:disabled
  • urn:alm:descriptor:enhance:preview:* 和 urn:alm:descriptor:preview:*
  • urn:alm:descriptor:enhance:docLink:* 和 urn:alm:descriptor:docLink:*

以下描述符需要显式组件能力,在仅元数据模式下不适用:

  • urn:alm:descriptor:placeholder:*
  • urn:alm:descriptor:com.tectonic.ui:validation:*
  • urn:alm:descriptor:expression:props.default*
  • urn:alm:descriptor:expression:props.options:*
  • urn:alm:descriptor:widgets:*

如果需要占位符、验证、动态选项、默认值或特定控件行为,请显式声明相应组件。

要将仅元数据字段设为只读,请添加禁用描述符:

- urn:alm:descriptor:com.tectonic.ui:disabled

高级和基本表单模式

对于使用受支持动态表单描述符的参数,产品可以显示使用已配置控件或小组件的 Advanced 表单。当不需要高级控件,或高级控件无法在当前上下文中使用时,Basic 表单仍可作为回退选项。

切换模式不会改变实际的 Pipeline 参数值。模式只会改变值的编辑方式。这样,用户可以在可用时使用便捷的选择器或结构化编辑器,同时保留直接输入方法,以便进行故障排除或输入特殊值。

当参数已经由 Pipeline Integration 提供时,表单可以先显示 Integration 配置。移除 Integration 绑定后,参数可以恢复为其描述符定义的动态控件。

参数、Workspace 和 Result 的描述符元数据

动态表单元数据不仅限于参数输入控件。Pipeline 作者还可以为 Pipeline 参数、Workspace 和 Result 配置显示名称、描述和 工具提示。

打开 Pipeline 配置表单,选择 Param、Workspace 或 Result,然后 打开 Advanced Form Configuration。你可以在 Form 模式下维护元数据,或在 YAML 模式下编辑完整的描述符。

元数据会复用于:

  • Pipeline 和 Task 详情。
  • Pipeline 和 Task 执行表单。
  • Pipeline 任务配置。
  • Result 变量建议。

原始 Tekton 名称仍会与配置的显示名称一起显示,插入 Pipeline 定义的引用 仍会使用原始 Tekton 名称。例如,显示为 Artifact URL 的 Result 仍会插入 $(tasks.build.results.artifact-url)。

多语言

Form 编辑器默认使用英语。当描述符包含多种语言的元数据时,会显示语言选择器。 你可以选择一种语言并更新其显示名称、描述和工具提示,而不会覆盖其他语言。

当需要维护完整描述符(包括组件、验证、动态选项或小组件设置)时,请使用 YAML 模式。Form 模式用于常见的显示元数据,并会保留描述符其余配置不变。

Workspace 和 Result 边界

Workspace 和 Result 描述符仅用于增强显示信息。它们不会将 Workspace 或 Result 转换为输入控件,其组件、验证、默认值、动态选项和小组件设置也不会应用。 Workspace 和 Result 的必需或可选行为仍由 Pipeline 声明提供。

Run Template 行为

Run Template 使用 Pipeline 描述符作为其参数的基础配置。当特定模板需要不同的 标签、控件、默认值或可见性时,Run Template 可以提供自己的描述符配置。

编辑 Run Template 时,所有 Pipeline 参数都可供配置。使用 Set at Runtime 标识应在运行模板时提供的值。在执行期间,用户会看到 Run Template 为运行时输入 公开的参数;固定值仍是已保存模板的一部分。

更改 Pipeline 描述符不会自动替换 Run Template 的特定配置。更改 Pipeline 后, 请检查 Run Template,尤其是在添加参数或更改其运行时行为时。

描述符源取决于表单上下文。Pipeline 和 Task 表单从选定的 Pipeline 或 Task 读取描述符。Integration 表单从选定的 ResourceInterface 或 Connector 读取 Integration 描述符。Trigger 和 ScheduledTrigger 表单复用 Run Template 配置; 其事件变量值通过 TriggerBinding 和相应的启动方法维护。

Workspace 和 Result 的元数据示例

- path: workspaces.source
  x-descriptors:
    - urn:alm:descriptor:label:en:Source Workspace
    - urn:alm:descriptor:description:en:Workspace used for source files
    - urn:alm:descriptor:tooltip:en:Provide storage that contains the source code
- path: results.image-url
  x-descriptors:
    - urn:alm:descriptor:label:en:Published Image
    - urn:alm:descriptor:description:en:Image produced by the Pipeline
    - urn:alm:descriptor:tooltip:en:Use this Result in downstream tasks

这些描述符仅用于改善显示效果。Pipeline 在其定义和变量引用中仍使用原始的 source Workspace 和 image-url Result 名称。

组件类型

文本输入

# value: string
- urn:alm:descriptor:com.tectonic.ui:text

多行文本输入

# value: string
- urn:alm:descriptor:com.tectonic.ui:textarea

标签输入

# value: array
- urn:alm:descriptor:com.tectonic.ui:tagsInput

单选框

# Declare a radio option with value "option-a"
- urn:alm:descriptor:com.tectonic.ui:radio:option-a
# Set the English display label of option-a to "Option A"
- urn:alm:descriptor:com.tectonic.ui:radio:option-a:en:Option A
# Set the Chinese display label of option-a to "Option A(zh)"
- urn:alm:descriptor:com.tectonic.ui:radio:option-a:zh:Option A(zh)
# Declare a radio option with value "option-b"
- urn:alm:descriptor:com.tectonic.ui:radio:option-b
# Set the English display label of option-b to "Option B"
- urn:alm:descriptor:com.tectonic.ui:radio:option-b:en:Option B
# Set the Chinese display label of option-b to "Option B(zh)"
- urn:alm:descriptor:com.tectonic.ui:radio:option-b:zh:Option B(zh)
# Set the default selected option to "option-a"
- urn:alm:descriptor:com.tectonic.default:option-a

开关

# value: boolean
- urn:alm:descriptor:com.tectonic.ui:booleanSwitch

# Map value to specified string
# When switch is on, value is True
- urn:alm:descriptor:props:booleanSwitch:true:True
# When switch is off, value is False
- urn:alm:descriptor:props:booleanSwitch:false:False

YAML 编辑器

# value: string
- urn:alm:descriptor:com.tectonic.ui:yaml

选择框

基本内容配置

# value: string
- urn:alm:descriptor:com.tectonic.ui:select
# Options
- urn:alm:descriptor:props:select:options:valueA
- urn:alm:descriptor:props:select:options:valueB
# Set the select box to multiple selection mode
# value: array
- urn:alm:descriptor:props:select:multiple
# Manually entered content can be used as selection items
- urn:alm:descriptor:props:select:allowCreate
# Content can be cleared
- urn:alm:descriptor:props:select:clearable

API 动态选项配置

当表单控件需要根据当前环境动态加载可用选项(例如可用的 namespace、secret 等)时,可以使用 API 动态配置,从后端接口实时获取下拉选项。

在此模式下,API URL 通常与上下文变量结合使用,根据用户当前的集群、namespace、项目或已填写的参数动态构造请求路径。例如:

# Use ${context.cluster} variable in URL to dynamically retrieve namespace list for current cluster
- urn:alm:descriptor:expression:props.options:api:apiPath
- urn:alm:descriptor:expression:props.options:api:/kubernetes/${context.cluster}/api/v1/namespaces

可用的上下文变量

在动态 API 路径中,可以使用 ${variable} 引用运行时上下文信息。

  • 通用上下文变量
变量描述
${context.cluster}当前集群名称
${context.namespace}当前 namespace
${context.project}当前项目
${current.search}从下拉框中获取当前搜索输入
  • Pipeline/Task 相关上下文变量
变量描述
${context.params}参数对象,例如,${context.params.repo} 可以引用表单中 repo 参数的当前值

对于 Integration 表单,${context.connectorClass} 是选中的 ConnectorClass 对象。Schema 表达式可以通过 context.connectorClass 访问同一对象,例如在从 ConnectorClass 定义解析 OpenAPI schema 时使用。

这些变量通常与 API URL 结合使用,以便在不同环境中动态构造请求地址,从而实现与环境相关的选项加载逻辑。例如:

- urn:alm:descriptor:expression:props.options:api:apiPath
- urn:alm:descriptor:expression:props.options:api:/api/v1/${context.namespace}/deployments?repo=${context.params.repo}

配置返回数据的数据路径

- urn:alm:descriptor:expression:props.options:path:spec.items

当 API 返回复杂结构时,例如:

{
  "spec": {
    "items": [ ... ]
  }
}

可以使用 path 指定如何从该结构中提取选项数组。

配置选项的标签和值映射字段

如果返回的数据对象较为复杂,需要将内部字段指定为“显示名称”和“选项值”,可以使用:

- urn:alm:descriptor:expression:props.options:label:path:metadata.name
- urn:alm:descriptor:expression:props.options:value:path:metadata.name

当 API 返回简单的 string[] 数组时,无需进行此配置。

配置 API 查询参数

如果需要向 API 请求传递查询参数(例如搜索关键字或过滤条件),可以使用:

# Add query parameter named "search" with user input as value
- urn:alm:descriptor:widgets:select
- urn:alm:descriptor:expression:props.options:api:/kubernetes/${context.cluster}/apis/tekton.dev/v1/namespaces/${context.namespace}/pipelineruns
- urn:alm:descriptor:expression:props.options:path:items
- urn:alm:descriptor:expression:props.options:label:path:metadata.name
- urn:alm:descriptor:expression:props.options:value:path:metadata.name
- urn:alm:descriptor:expression:props.options:api:params:search:${current.search}

当用户在下拉框中输入“test”时,实际请求将为:

/kubernetes/.../pipelineruns?search=test

基于 Schema 的选项

在 Integration 场景中,选择框可以使用选中 Connector 暴露的 OpenAPI schema,而无需手动描述每个 API 请求和选项映射:

- urn:alm:descriptor:widgets:select
- urn:alm:descriptor:expression:props.options:schema:openapi:context.connectorClass.spec.api.openapi:listProjects

平台使用该 schema 构建可用选项及其表单行为。当 Connector 为项目、分支、标签或合并请求提供标准 API 时,这种方式非常有用。

计算选项字段

对于更复杂的响应,可以使用表达式计算选项列表,或计算每个选项的标签、值和描述:

- urn:alm:descriptor:expression:props.options:path.exp:$.items.flatMap(item => item.spec.targets || [])
- urn:alm:descriptor:expression:props.options:label:path.exp:`${$.name} (${$.status})`
- urn:alm:descriptor:expression:props.options:value:path.exp:$.id
- 'urn:alm:descriptor:expression:props.options:description:path.exp:`Target: ${$.name}`'

表达式会将当前选项作为 $ 接收。表达式还可以使用当前表单上下文(例如 context.params)来计算值。

高级用法:支持 JavaScript 表达式,例如:

${Object.keys(context.params || {}).join(',')}

增强功能

参数默认值

固定默认值

- urn:alm:descriptor:expression:props.default:default-value

基于表达式的动态默认值

可用变量:

  • option:选项原始数据

  • index:选项索引

  • length:选项总数

  • context:上下文参数

    # Select options with specific labels
    - urn:alm:descriptor:expression:props.default.exp:option.metadata.labels['default']==='true'
    # Default to select the first item
    - urn:alm:descriptor:expression:props.default.exp:index === 0
    # Default to select the last item
    - urn:alm:descriptor:expression:props.default.exp:index === length - 1
    # Default to select when there is only one option
    - urn:alm:descriptor:expression:props.default.exp:length === 1
    # Default to select the current namespace
    - urn:alm:descriptor:expression:props.default:${context.namespace}
    # Complex conditions
    - urn:alm:descriptor:expression:props.default.exp:option.metadata.name.includes('test') && option.status.conditions.some(c => c.status==='True')
INFO

有关复杂场景中的条件语法规则,请参阅 JavaScript 语法。

表单验证

支持配置各种验证规则,并且可以同时应用多个规则。

必填验证

- urn:alm:descriptor:com.tectonic.ui:validation:required

长度验证

# Minimum length
- urn:alm:descriptor:com.tectonic.ui:validation:minLength:6
# Maximum length
- urn:alm:descriptor:com.tectonic.ui:validation:maxLength:64

数值范围验证

# Minimum value (applicable to numeric types)
- urn:alm:descriptor:com.tectonic.ui:validation:minimum:1
# Maximum value
- urn:alm:descriptor:com.tectonic.ui:validation:maximum:100

正则表达式验证

# Positive integer
- urn:alm:descriptor:com.tectonic.ui:validation:pattern:[1-9]\d*
# Kubernetes resource name (lowercase letters, numbers, hyphens)
- urn:alm:descriptor:com.tectonic.ui:validation:pattern:[a-z0-9]([-a-z0-9]*[a-z0-9])?

组合示例:为密码字段配置完整的验证规则

- path: params.password
  x-descriptors:
    - urn:alm:descriptor:label:zh:password
    - urn:alm:descriptor:com.tectonic.ui:text
    - urn:alm:descriptor:description:zh:At least 8 characters, including letters and numbers.
    - urn:alm:descriptor:com.tectonic.ui:validation:required
    - urn:alm:descriptor:com.tectonic.ui:validation:minLength:8
    - urn:alm:descriptor:com.tectonic.ui:validation:maxLength:32

预览组件

预览组件允许用户直接在表单中预览所选资源的 YAML 内容。这在用户需要先验证资源配置,再将其用于 Pipeline 的场景中特别有用,例如检查 ConfigMap 内容、验证 Secret 数据,或查看 Task/Pipeline YAML 定义。

例如,当用户从下拉框中选择 ConfigMap,并将其用作 Task 中的卷挂载或环境变量来源时,可以直接在表单中预览 ConfigMap 的数据,以确保选择了正确的资源。

配置

# Enable preview - show button when parameter has value
- urn:alm:descriptor:enhance:preview:context.params.<param-name>

# API endpoint to fetch resource content
- urn:alm:descriptor:preview:resource:api:<api-url>

# JSONPath or JS expression to extract content from response
- urn:alm:descriptor:preview:resource:path:<jsonpath>
- urn:alm:descriptor:preview:resource:path.exp:<js-expression>

示例:配置一个用于选择 ConfigMap 的下拉框,并添加用于查看其 YAML 内容的预览按钮。

- path: params.configmap
  x-descriptors:
    # Form label
    - urn:alm:descriptor:label:en:ConfigMap
    - urn:alm:descriptor:label:zh:ConfigMap

    # Dropdown to select ConfigMap from current namespace
    - urn:alm:descriptor:com.tectonic.ui:select
    - urn:alm:descriptor:expression:props.options:api:/kubernetes/${context.cluster}/api/v1/namespaces/${context.namespace}/configmaps
    - urn:alm:descriptor:expression:props.options:path:items
    - urn:alm:descriptor:expression:props.options:label:path:metadata.name
    - urn:alm:descriptor:expression:props.options:value:path:metadata.name
    - urn:alm:descriptor:com.tectonic.ui:validation:required

    # Preview feature
    - urn:alm:descriptor:enhance:preview:context.params.configmap
    - urn:alm:descriptor:preview:resource:api:/kubernetes/${context.cluster}/api/v1/namespaces/${context.namespace}/configmaps?fieldSelector=metadata.name%3D${context.params.configmap}
    - urn:alm:descriptor:preview:resource:path:items[0]

UI 中的工作方式:

  1. 用户从下拉框中选择 ConfigMap(例如 my-config)。
  2. 下拉框旁边会显示预览按钮。
  3. 单击预览按钮,从 Kubernetes API 获取所选 ConfigMap。
  4. 原始 YAML 内容会显示在带有语法高亮的预览面板中。

预览请求可以使用 GET 或 POST。POST 预览可以根据当前表单值构建 PipelineRun 或 TaskRun 请求,并显示服务器返回的 结果。

预览内容可以显示为:

  • YAML 或其他资源表示形式。
  • 包含主题和 HTML 正文的文章,例如渲染后的通知 消息。

预览用于在执行前检查结果。预览上下文中不可用的仅运行时变量可能仍处于未解析状态,因此预览应被视为参考,而不是最终执行输出的保证。

链接配置会向特定字段添加可点击链接。当用户填写参数时需要快速访问相关指南、产品文档、外部参考页面或其他系统 URL 时,可以使用此配置。

链接可以与表单组件结合使用,也可以在仅元数据模式下使用;在仅元数据模式下,你只需添加帮助文本和链接,而无需更改字段的默认输入组件。

配置

# Enable an internal product link
- urn:alm:descriptor:enhance:docLink:productDoc

# Product link path. Product documentation pages are a common use case.
- urn:alm:descriptor:docLink:link:alauda-devops-pipelines/pipelines/how_to/configure_dynamic_forms.html

# Optional link tooltip label. The UI uses a built-in default when omitted.
- urn:alm:descriptor:docLink:label:en:Open guide
- urn:alm:descriptor:docLink:label:zh:Open guide

对于完整 URL 链接,请使用 external 链接类型,并提供完整的 http 或 https URL:

- urn:alm:descriptor:enhance:docLink:external
- urn:alm:descriptor:docLink:link:https://example.com/docs
- urn:alm:descriptor:docLink:label:en:External reference
- urn:alm:descriptor:docLink:label:zh:External reference

示例:为 Git 仓库 URL 字段添加指向参数指南的链接。

- path: params.gitURL
  x-descriptors:
    - urn:alm:descriptor:label:en:Git Repository URL
    - urn:alm:descriptor:label:zh:Git Repository URL
    - urn:alm:descriptor:description:en:Enter the source repository URL.
    - urn:alm:descriptor:description:zh:Enter the source repository URL.
    - urn:alm:descriptor:com.tectonic.ui:text
    - urn:alm:descriptor:enhance:docLink:productDoc
    - urn:alm:descriptor:docLink:link:alauda-devops-pipelines/pipelines/how_to/configure_dynamic_forms.html
    - urn:alm:descriptor:docLink:label:en:Open parameter guide
    - urn:alm:descriptor:docLink:label:zh:Open parameter guide

配置规则

  • 一个字段只能使用一种链接类型:productDoc 或 external。
  • productDoc 使用产品链接路径,例如 alauda-devops-pipelines/pipelines/how_to/configure_dynamic_forms.html。
  • external 仅接受完整的 http 或 https URL。
  • 如果链接无效,或类型与链接值不匹配,UI 不会渲染该链接。

高级组件

在复杂的 CI/CD 场景中,以下高级表单组件可以帮助您处理更复杂的配置需求。

组合组件

在复杂的 CI/CD 场景中,您可能会遇到这样的情况:单个数组参数需要从多个不同来源(不同 API)收集数据。例如,workloads 参数可能需要同时包含“Deployments”和“StatefulSets”,而这两者需要从完全不同的 Kubernetes API 获取数据。

为实现这一目标,您可以使用组合组件(widgets:combine)。它允许您在 UI 中将单个参数拆分为多个相互独立的子表单控件(例如,用于选择资源类型的单选按钮,以及用于选择实际资源的选择框),然后在提交到 Pipeline 之前,通过 JavaScript 表达式将它们的值组合成最终的数组或 JSON 对象。

配置

# Declare the use of the combine widget
- urn:alm:descriptor:widgets:combine

# Parent combine logic: defines how to merge all sub-component values into the final parameter
# Available variable: items (contains all sub-component values)
# Example: (items.deployments || []).concat(items.statefulsets || []) - merge multiple arrays into one
- urn:alm:descriptor:combine:value.exp:<js-expression>

# Parent: define sub-components
- urn:alm:descriptor:combine:items:
    - path: <sub-component-name-1>
      x-descriptors:
        # Child split logic: defines how to extract this sub-component's value from the parent for echo display
        # Available variable: parent (the current parameter value)
        # Example: (parent || []).filter(p => p.startsWith('deploy:')) - extract items with 'deploy:' prefix
        - urn:alm:descriptor:combine:value.exp:<js-expression>
        # ... other descriptors for this sub-component

    - path: <sub-component-name-2>
      x-descriptors:
        # Child split logic: defines how to extract this sub-component's value from the parent for echo display
        - urn:alm:descriptor:combine:value.exp:<js-expression>
        # ... other descriptors for this sub-component

有关更多 js-expression 语法,请参阅 JavaScript 语法。

示例:配置多选参数 target_resources,允许用户从 Deployments 和 StatefulSets 中选择资源。最终参数值将是一个组合了两个 API 中所选资源的数组,并应用特定前缀以区分其类型(例如,["deploy:app-v1", "sts:db-v1"])。

- path: params.target_resources
  x-descriptors:
    # Declare the use of the combine widget
    - urn:alm:descriptor:widgets:combine
    
    # [Parent] Combine logic: concat the arrays from both 'deployments' and 'statefulsets' sub-components
    - urn:alm:descriptor:combine:value.exp:(items.deployments || []).concat(items.statefulsets || [])
    
    # Define sub-components
    - urn:alm:descriptor:combine:items:
        
        # Sub-component 1: Select Deployments
        - path: deployments
          x-descriptors:
            # [Child 1] Split logic: extract items starting with 'deploy:' from the parent array
            - urn:alm:descriptor:combine:value.exp:(parent || []).filter(p => p.startsWith('deploy:'))
            - urn:alm:descriptor:label:en:Deployments
            - urn:alm:descriptor:label:zh:Deployments
            - urn:alm:descriptor:widgets:select
            - urn:alm:descriptor:props:select:multiple
            - urn:alm:descriptor:expression:props.options:api:/kubernetes/${context.cluster}/apis/apps/v1/namespaces/${context.namespace}/deployments
            - urn:alm:descriptor:expression:props.options:path:items
            - urn:alm:descriptor:expression:props.options:label:path:metadata.name
            # Prepend 'deploy:' prefix
            - urn:alm:descriptor:expression:props.options:value:path.exp:'deploy:'+$.metadata.name
            
        # Sub-component 2: Select StatefulSets
        - path: statefulsets
          x-descriptors:
            # [Child 2] Split logic: extract items starting with 'sts:' from the parent array
            - urn:alm:descriptor:combine:value.exp:(parent || []).filter(p => p.startsWith('sts:'))
            - urn:alm:descriptor:label:en:StatefulSets
            - urn:alm:descriptor:label:zh:StatefulSets
            - urn:alm:descriptor:widgets:select
            - urn:alm:descriptor:props:select:multiple
            - urn:alm:descriptor:expression:props.options:api:/kubernetes/${context.cluster}/apis/apps/v1/namespaces/${context.namespace}/statefulsets
            - urn:alm:descriptor:expression:props.options:path:items
            - urn:alm:descriptor:expression:props.options:label:path:metadata.name
            # Prepend 'sts:' prefix
            - urn:alm:descriptor:expression:props.options:value:path.exp:'sts:'+$.metadata.name

UI 中的工作方式:

  1. 用户会同时看到两个独立的多选框:“Deployments”和“StatefulSets”。

  2. Deployments 框从 Deployment API 获取数据,StatefulSets 框从 StatefulSet API 获取数据。

  3. 当用户在 Deployments 中选择 dummy 和 alm,并在 StatefulSets 中选择 db-1 时,提交到 Task 的最终 target_resources 数组会自然组合为:

    - name: target_resources
      value:
        - deploy:dummy
        - deploy:alm
        - sts:db-1

数组表格组件

数组表格组件(widgets:arrayTable)将字符串数组编辑为结构化行。当每个数组项包含多个业务值时,请使用此组件,例如 KEY=VALUE、name|protocol|description 或 JSON 字符串。

Pipeline 参数仍然是 string[]。表单只会改变每个项的编辑方式,并在 Pipeline 启动前将每一行转换回一个字符串。

- path: params.buildArgs
  x-descriptors:
    - urn:alm:descriptor:widgets:arrayTable
    - urn:alm:descriptor:arrayTable:separator:=
    - urn:alm:descriptor:arrayTable:items:
        - path: key
          x-descriptors:
            - urn:alm:descriptor:label:en:Key
            - urn:alm:descriptor:com.tectonic.ui:text
        - path: value
          x-descriptors:
            - urn:alm:descriptor:label:en:Value
            - urn:alm:descriptor:com.tectonic.ui:text

对于 MESSAGE=left=middle=right,第一个分隔符用于分隔键,剩余文本会保留在值中。这样可以避免最后一个字段中的其他分隔符丢失。

布局会根据行字段数量进行调整:

  • 一个字段:显示为全宽行,不单独显示表头。
  • 两个字段:字段以列的形式显示,并共享一个表头。
  • 多于两个字段:字段垂直显示,每行带有标签。

对于无法通过分隔符表示的 JSON 或其他格式,请定义 urn:alm:descriptor:arrayTable:parse.exp: 和 urn:alm:descriptor:arrayTable:stringify.exp:。解析表达式会接收 parent(存储的字符串)和 context,并且必须返回一个包含所有已配置项路径的对象。字符串化表达式会接收 items(当前行值)和 context,并且必须返回一个字符串。

例如,可以将 JSON 数组项编辑为两个字段,然后再转换回存储的字符串:

- path: params.jsonItems
  x-descriptors:
    - urn:alm:descriptor:widgets:arrayTable
    - urn:alm:descriptor:arrayTable:items:
        - path: key
          x-descriptors:
            - urn:alm:descriptor:label:en:Key
            - urn:alm:descriptor:com.tectonic.ui:text
        - path: value
          x-descriptors:
            - urn:alm:descriptor:label:en:Value
            - urn:alm:descriptor:com.tectonic.ui:text
    - 'urn:alm:descriptor:arrayTable:parse.exp:parse(parent)'
    - 'urn:alm:descriptor:arrayTable:stringify.exp:stringify(items)'

无效的转换结果会显示为表单错误,不会静默覆盖原始值。

对于简单的独立字符串列表,请勿使用数组表格。此时应使用标准数组输入或 tagsInput。

内联表单组件

内联表单组件(widgets:inlineForm)会在当前参数字段中显示所选资源的参数。当一次选择决定下一组输入时,此组件非常有用,例如先选择消息模板,然后输入该模板的变量。

内联表单可以从 API 加载资源,也可以从当前表单上下文中已有的值加载资源。描述符会标识:

  • 要加载的资源。
  • 包含所选对象的资源路径。
  • 资源的参数路径和描述符路径。
  • 如何将嵌套表单值转换为父参数值,以及如何执行反向转换。

示例:

- path: params.templateValues
  x-descriptors:
    - urn:alm:descriptor:widgets:inlineForm
    - urn:alm:descriptor:inlineForm:resource:api:/kubernetes/${context.cluster}/api/v1/namespaces/kube-public/configmaps?fieldSelector=metadata.name%3D${context.params.templateName}
    - urn:alm:descriptor:inlineForm:resource:path:items[0]
    - 'urn:alm:descriptor:inlineForm:params:path.exp:parse($.metadata.annotations["style.tekton.dev/descriptors"] || "")?.map(d => ({type: "string", name: d.path.split("params.")[1]}))'
    - 'urn:alm:descriptor:inlineForm:stringify:$?.length ? stringify($.reduce((acc, cur) => { acc[cur.name] = cur.value; return acc; }, {})) : ""'
    - 'urn:alm:descriptor:inlineForm:parse:Object.entries(parse($ || "") || {}).map(([name, value]) => ({name, value}))'

当资源或其参数发生变化时,内联表单会针对当前上下文进行刷新。嵌套验证结果会传递到父字段,因此 Pipeline 无法在内联配置无效的情况下提交。

内联表单可以与预览组件结合使用。例如,用户可以配置所选模板的变量,然后预览渲染结果,而无需离开 Pipeline 表单。

完整示例

在 Task 中配置仅元数据动态表单

示例:添加标签、描述、工具提示和字段链接,而无需声明表单组件。

效果:UI 会保留每个参数的默认输入行为,仅应用已配置的元数据和链接。

apiVersion: tekton.dev/v1
kind: Task
metadata:
  name: metadata-only-demo-task
  namespace: <your namespace>
  annotations:
    style.tekton.dev/descriptors: |
      - path: params.mailSubject
        x-descriptors:
          - urn:alm:descriptor:label:en:Mail Subject
          - urn:alm:descriptor:label:zh:Mail Subject
          - urn:alm:descriptor:description:en:Used to render the notification title.
          - urn:alm:descriptor:description:zh:Used to render the notification title.
          - urn:alm:descriptor:tooltip:en:Rendered at runtime.
          - urn:alm:descriptor:tooltip:zh:Rendered at runtime.
      - path: params.runtimeNote
        x-descriptors:
          - urn:alm:descriptor:label:en:Runtime Note
          - urn:alm:descriptor:label:zh:Runtime Note
          - urn:alm:descriptor:description:en:No component descriptor is configured for this parameter.
          - urn:alm:descriptor:description:zh:No component descriptor is configured for this parameter.
          - urn:alm:descriptor:tooltip:en:The UI should keep the parameter entry's default rendering component.
          - urn:alm:descriptor:tooltip:zh:The UI should keep the parameter entry's default rendering component.
          - urn:alm:descriptor:enhance:docLink:productDoc
          - urn:alm:descriptor:docLink:link:alauda-devops-pipelines/pipelines/how_to/configure_dynamic_forms.html
          - urn:alm:descriptor:docLink:label:en:Open form guide
          - urn:alm:descriptor:docLink:label:zh:Open form guide
spec:
  params:
    - name: mailSubject
      type: string
      default: Metadata-only subject
    - name: runtimeNote
      type: string
      default: This parameter has no explicit form component descriptor.
  steps:
    - name: print-values
      image: ubuntu
      env:
        - name: MAIL_SUBJECT
          value: $(params.mailSubject)
        - name: RUNTIME_NOTE
          value: $(params.runtimeNote)
      script: |
        #!/usr/bin/env sh
        set -eu
        echo "mailSubject=${MAIL_SUBJECT}"
        echo "runtimeNote=${RUNTIME_NOTE}"

在 Task 中配置动态表单

示例:为 Task 的 image 参数提供用于选择命名空间的下拉框。

效果:当用户通过 UI 编排 Pipeline 或 TaskRun 时,此 Task 的 namespace 参数支持通过下拉框选择命名空间。

apiVersion: tekton.dev/v1
kind: Task
metadata:
  name: demo-task
  namespace: <your namespace>
  annotations:
    style.tekton.dev/descriptors: |
      - path: params.namespace
        x-descriptors:
          - urn:alm:descriptor:label:en:namespace
          - urn:alm:descriptor:label:zh:namespace(zh)
          - urn:alm:descriptor:com.tectonic.ui:select
          - urn:alm:descriptor:expression:props.options:api:/kubernetes/${context.cluster}/api/v1/namespaces
          - urn:alm:descriptor:expression:props.options:path:items
          - urn:alm:descriptor:expression:props.options:label:path:metadata.name
          - urn:alm:descriptor:expression:props.options:value:path:metadata.name
          - urn:alm:descriptor:com.tectonic.ui:validation:required
spec:
  params:
    - name: namespace
      type: string
  steps:
    - name: demo
      image: ubuntu
      script: |
        #!/bin/sh
        pwd

在 Pipeline 中配置动态表单

示例:为 Pipeline 的 target-namespace 参数提供用于选择命名空间的下拉框。

效果:当用户通过 UI 触发 Pipeline,或需要在其他资源(Trigger、TriggerTemplate)中关联此 Pipeline 并配置运行时参数时,target-namespace 参数支持通过下拉框选择命名空间。

apiVersion: tekton.dev/v1
kind: Pipeline
metadata:
  annotations:
    style.tekton.dev/descriptors: |
      - path: params.target-namespace
        x-descriptors:
          - urn:alm:descriptor:label:en:target-namespace
          - urn:alm:descriptor:label:zh:target-namespace(zh)
          - urn:alm:descriptor:com.tectonic.ui:select
          - urn:alm:descriptor:expression:props.options:api:/kubernetes/${context.cluster}/api/v1/namespaces
          - urn:alm:descriptor:expression:props.options:label:path:metadata.name
          - urn:alm:descriptor:expression:props.options:value:path:metadata.name
          - urn:alm:descriptor:expression:props.options:path:items
          - urn:alm:descriptor:com.tectonic.ui:validation:required
  name: demo-pipelines
  namespace: <your namespace>
spec:
  params:
    - name: target-namespace
      type: string
  tasks:
    - name: kubectl
      taskRef:
        resolver: hub
        params:
          - name: kind
            value: task
          - name: catalog
            value: catalog
          - name: name
            value: kubectl
          - name: version
            value: "0.1"

故障排除

  • 表单未显示或配置未生效:检查 style.tekton.dev/descriptors 的 YAML 格式是否正确,确认 path 是否根据需要配置为 params.parameter-name、workspaces.workspace-name 或 results.result-name,并验证每个描述符是否以 - urn:alm:descriptor: 开头
  • 动态选项未加载:确认 API 路径是否正确,检查当前用户是否有权访问指定的 API 资源,验证 path、label 和 value 配置是否指向返回数据中存在的字段
  • 默认值未生效:确认固定默认值使用 expression:props.default:value 格式,表达式默认值使用 === 而不是 =,并检查表达式中的变量(option、index、length、context)拼写是否正确
  • 上下文变量未解析:验证变量名称是否正确(例如使用 context.namespace 而不是 context.namespaces),确认变量是否用于支持表达式的描述符中,并检查 JavaScript 表达式语法是否存在错误
  • 链接未显示:确认 enhance:docLink 使用的是 productDoc 或 external,验证是否存在 docLink:link,并确保外部链接使用完整的 http 或 https URL
  • 字段已显示但无法编辑:检查是否为该字段配置了 urn:alm:descriptor:com.tectonic.ui:disabled
  • 高级控件未显示:检查描述符路径是否与现有参数匹配,是否具备所需的控件能力,以及当前条目是否支持配置的控件。使用 Basic 表单单独验证底层值。
  • 数组表格无法渲染:检查 arrayTable:items 是否至少包含一个具有唯一且非空 path 的项。无效的项定义会回退到常规数组表单。
  • 数组值更改未保存:检查分隔符或 parse.exp 和 stringify.exp 表达式。转换失败或嵌套字段无效时,不会覆盖原始数组值。
  • 内联表单为空:检查所选资源、资源路径、参数路径和描述符路径是否能在当前上下文中解析。同时验证当前用户是否可以读取资源 API。
  • 预览结果与最终运行结果不同:检查预览是否依赖仅在运行时可用的变量。当执行上下文不可用时,预览结果仅供参考。
  • Workspace 或 Result 控件未改变:Workspace 和 Result 描述符仅提供显示元数据。必填、可选和绑定行为仍由 Pipeline 声明提供。