如何配置动态表单

功能概述

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

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

使用场景

Pipeline 编排/运行时：允许用户在编排或触发 Pipeline 时通过友好表单填写命名空间、Secret 等参数
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)

表单基础配置

表单标签

# 表单标签
- urn:alm:descriptor:label:en:English Name
- urn:alm:descriptor:label:zh:中文名称

表单描述

# 表单描述
- urn:alm:descriptor:description:en:English Description
- urn:alm:descriptor:description:zh:中文描述

占位提示

# 占位提示
- urn:alm:descriptor:placeholder:en:This is a Placeholder
- urn:alm:descriptor:placeholder:zh:这是占位提示

表单帮助提示

# 帮助提示
- urn:alm:descriptor:tooltip:en:This is a Help Tip
- urn:alm:descriptor:tooltip:zh:这是帮助提示

表单禁用状态

# 是否禁用表单
- 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

# 将值映射为指定字符串
# 开关开启时，值为 True
- urn:alm:descriptor:props:booleanSwitch:true:True
# 开关关闭时，值为 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
# 选项
- urn:alm:descriptor:com.tectonic.ui:select:valueA
- urn:alm:descriptor:com.tectonic.ui:select:valueB
# 设置选择框为多选模式
# value: array
- urn:alm:descriptor:props:select:multiple
# 允许手动输入内容作为选项
- urn:alm:descriptor:props:select:allowCreate
# 允许清空内容
- urn:alm:descriptor:props:select:clearable

API 动态选项配置

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

此模式下，API URL 通常结合 上下文变量 使用，根据用户当前集群、命名空间、项目或填写的参数动态构造请求路径。例如：

# 在 URL 中使用 ${context.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}`	当前命名空间
`${context.project}`	当前项目
`${current.search}`	获取下拉框当前的搜索输入

Pipeline/Task 相关上下文变量

变量	说明
`${context.params}`	参数对象，例如 `${context.params.repo}` 可引用表单中 `repo` 参数的当前值

这些变量通常与 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 请求传递查询参数（如搜索关键字或过滤条件），可使用：

# 添加名为 search 的查询参数，值为用户输入
- 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：上下文参数

# 选择标签为特定值的选项
- urn:alm:descriptor:expression:props.default.exp:option.metadata.labels['default']==='true'
# 默认选择第一个
- urn:alm:descriptor:expression:props.default.exp:index === 0
# 默认选择最后一个
- urn:alm:descriptor:expression:props.default.exp:index === length - 1
# 只有一个选项时默认选择
- urn:alm:descriptor:expression:props.default.exp:length === 1
# 默认选择当前命名空间
- urn:alm:descriptor:expression:props.default:${context.namespace}
# 复杂条件
- 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

长度校验

# 最小长度
- urn:alm:descriptor:com.tectonic.ui:validation:minLength:6
# 最大长度
- urn:alm:descriptor:com.tectonic.ui:validation:maxLength:64

数值范围校验

# 最小值（适用于数值类型）
- urn:alm:descriptor:com.tectonic.ui:validation:minimum:1
# 最大值
- urn:alm:descriptor:com.tectonic.ui:validation:maximum:100

正则表达式校验

# 正整数
- urn:alm:descriptor:com.tectonic.ui:validation:pattern:[1-9]\d*
# Kubernetes 资源名称（小写字母、数字、短横线）
- 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:密码
    - urn:alm:descriptor:com.tectonic.ui:text
    - urn:alm:descriptor:description:zh:至少 8 个字符，包含字母和数字。
    - 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 参数提供命名空间选择下拉框。

效果：用户基于 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: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: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 中配置动态表单

#故障排查