如何配置动态表单

功能概述

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

动态表单生成：自动为资源参数生成交互式表单，为编排和执行 Pipeline 和 Task 提供更好的体验。
丰富的组件支持：提供文本框、选择器、开关、YAML 编辑器等多种表单组件。
字段校验：内置校验规则，确保用户输入满足要求。
动态数据获取：支持通过 API 动态加载选项数据。

使用场景

Pipeline 编排/运行时：在编排或触发 Pipeline 时，允许用户通过友好的表单填写 namespace、secrets 等参数
Task 复用：在 Task 或 Pipeline 模板层提供常用参数的默认值、下拉选项和校验
多环境选择：从 API 中动态查询可用环境或配置，并将其作为选择项

快速开始

基础配置结构

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

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

配置说明

path：指定参数路径，格式为 params.parameter-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)

表单基础配置

表单标签

# 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

支持的字段类型

文本输入

# 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

单选

# value: string
- urn:alm:descriptor:com.tectonic.ui:radio:valueA
- urn:alm:descriptor:com.tectonic.ui:radio:valueB

开关

# 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 动态选项配置

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

在这种模式下，API URL 通常会与上下文变量结合使用，以便根据用户当前的 cluster、namespace、project 或已填写参数动态构造请求路径。例如：

# 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} 来引用运行时上下文信息。

通用上下文变量

Variable	Description
`${context.cluster}`	Current cluster name
`${context.namespace}`	Current namespace
`${context.project}`	Current project
`${current.search}`	Get the current search input from the dropdown box

与 Pipeline/Task 相关的上下文变量

Variable	Description
`${context.params}`	Parameters object, e.g., `${context.params.repo}` can reference the current value of the `repo` parameter in the form

这些变量通常与 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 指定如何从该结构中提取选项数组。

配置选项的 label 和 value 映射字段

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

- 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

高级用法：支持 JavaScript 表达式，例如：

${context.params.map(p => p.name).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 syntax。

表单校验

支持配置多种校验规则，并且可以同时应用多个规则。

必填校验

- 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

使用示例

在 Task 中配置动态表单

示例：为 Task 的 image 参数提供一个用于选择 namespaces 的下拉框。

效果：当用户基于 UI 编排 Pipeline 或 TaskRun 时，该 Task 的 namespace 参数支持通过下拉框选择 namespaces。

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 参数提供一个用于选择 namespaces 的下拉框。

效果：当用户基于 UI 触发 Pipeline，或者需要在其他资源（Trigger、TriggerTemplate）中关联该 pipeline 并配置运行时参数时，target-namespace 参数支持通过下拉框选择 namespaces。

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，验证每个 descriptor 都以 - urn:alm:descriptor: 开头
动态选项未加载：确认 API 路径正确，检查当前用户是否有权限访问指定的 API 资源，验证 path、label 和 value 配置是否指向返回数据中存在的字段
默认值未生效：确认固定默认值使用 expression:props.default:value 格式，表达式默认值使用 === 而不是 =，检查表达式中的变量（option、index、length、context）拼写是否正确
上下文变量未解析：确认变量名是否正确（例如 context.namespace 而不是 context.namespaces），确认变量使用在支持表达式的 descriptor 中，检查 JavaScript 表达式语法是否有错误

#如何配置动态表单

#目录

#功能概述

#使用场景

#快速开始

#表单基础配置

#表单标签

#表单描述

#占位提示

#表单帮助提示

#表单禁用状态

#支持的字段类型

#文本输入

#多行文本输入

#标签输入

#单选

#开关

#YAML 编辑器

#选择框

#基础内容配置

#API 动态选项配置

#参数默认值

#表单校验

#必填校验

#长度校验

#数值范围校验

#正则表达式校验

#使用示例

#在 Task 中配置动态表单

#在 Pipeline 中配置动态表单

#故障排查