如何配置动态表单

功能概述

动态表单配置功能允许您以声明式方式为 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)

能力选择指南

使用下表选择最小且满足需求的 descriptor 集合。

需求	推荐配置	显式组件 descriptor
仅修改字段标签、描述或工具提示	基础元数据 descriptor	不需要
保持默认输入行为，但添加字段元数据或链接	仅元数据配置	不需要
渲染特定输入控件，例如 text、textarea、select、switch 或 YAML editor	组件类型 descriptor	需要
提供固定默认值或基于表达式的默认值	默认值 descriptor	通常需要
校验用户输入	校验 descriptor	需要
从 API 加载 select 选项	带动态选项的 Select 组件	需要
预览所引用的资源内容	预览 descriptor	不需要；可与一个组件组合
为产品指南或外部 URL 添加字段链接	链接 descriptor	不需要；可与一个组件组合
将一个参数拆分为多个子输入	Combine 组件	需要

基础元数据

表单标签

# 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 会保留参数输入项的默认渲染组件，仅应用支持的 descriptor 增强能力。当您希望改善显示文本或添加帮助链接，但不改变参数输入行为时，这种方式非常有用。

- 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.

仅元数据模式下支持的 descriptor：

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:*

以下 descriptor 需要显式的组件能力，在仅元数据模式下不适用：

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:*

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

若要将仅元数据字段设为只读，请添加 disabled descriptor：

- 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

单选

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

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

在这种模式下，API URL 通常会与 context 变量 结合使用，根据用户当前的 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

可用的 Context 变量

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

通用 Context 变量

变量	描述
`${context.cluster}`	当前 cluster 名称
`${context.namespace}`	当前 namespace
`${context.project}`	当前 project
`${current.search}`	获取下拉框中的当前搜索输入

与 Pipeline/Task 相关的 Context 变量

变量	描述
`${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 请求传递查询参数（例如搜索关键字或过滤条件），可以使用：

# 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

预览组件

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

例如，当用户从下拉框中选择一个 ConfigMap，用于 Task 中的 volume mount 或 environment variable 源时，他们可以直接在表单中预览该 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 中的工作方式：

用户从下拉框中选择一个 ConfigMap（例如 my-config）。
下拉框旁边会出现一个预览按钮。
点击预览按钮会从 Kubernetes API 获取所选 ConfigMap。
原始 YAML 内容会带语法高亮显示在预览面板中。

链接配置

链接配置 会为特定字段添加一个可点击的链接。当用户在填写参数时需要快速访问相关指南、产品文档、外部参考页面或其他系统 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 场景中，以下高级表单组件可以帮助您处理更复杂的配置需求。

Combine 组件

在复杂的 CI/CD 场景中，您可能会遇到这样的情况：单个数组参数需要从多个不同来源（不同 API）收集数据。例如，workloads 参数可能需要同时包含 Deployments 和 StatefulSets，而这两类资源分别需要从完全不同的 Kubernetes API 中获取。

为此，您可以使用 Combine Component (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 syntax。

示例：配置一个多选参数 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 中的工作方式：

用户会同时看到两个独立的多选框：“Deployments” 和 “StatefulSets”。
Deployments 框从 Deployment API 获取数据，StatefulSets 框从 StatefulSet API 获取数据。
当用户在 Deployments 中选择 dummy 和 alm，在 StatefulSets 中选择 db-1 时，提交到 Task 的最终 target_resources 数组会自然合并为：
- name: target_resources value: - deploy:dummy - deploy:alm - sts:db-1

完整示例

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

效果：当用户基于 UI 编排 Pipeline 或 TaskRun 时，该 Task 的 namespace 参数支持通过下拉框选择 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 参数提供一个用于选择 namespaces 的下拉框。

效果：当用户基于 UI 触发 Pipeline，或需要在其他资源（Trigger、TriggerTemplate）中关联此 pipeline 并配置运行时参数时，target-namespace 参数支持通过下拉框选择 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，验证每个 descriptor 是否以 - urn:alm:descriptor: 开头
动态选项未加载：确认 API 路径是否正确，检查当前用户是否有权限访问指定的 API 资源，验证 path、label 和 value 配置是否指向返回数据中实际存在的字段
默认值未生效：确认固定默认值使用 expression:props.default:value 格式，表达式默认值使用 === 而不是 =，检查表达式中的变量（option、index、length、context）拼写是否正确
Context 变量未解析：验证变量名是否正确（例如 context.namespace 而不是 context.namespaces），确认变量是否用于支持表达式的 descriptor，检查 JavaScript 表达式语法是否存在错误
链接未显示：确认 enhance:docLink 使用的是 productDoc 或 external，验证是否存在 docLink:link，并确保外部链接使用完整的 http 或 https URL
字段显示但无法编辑：检查该字段是否配置了 urn:alm:descriptor:com.tectonic.ui:disabled

如何配置动态表单

目录

功能概述

使用场景

快速开始

能力选择指南

基础元数据

表单标签

表单描述

占位提示

表单帮助工具提示

表单禁用状态

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

组件类型

文本输入

多行文本输入

标签输入

单选

开关

YAML 编辑器

选择框

基础内容配置

API 动态选项配置

增强能力

参数默认值

表单校验

必填校验

长度校验

数值范围校验

正则表达式校验

预览组件

链接配置

高级 Widget

Combine 组件

完整示例

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

在 Task 中配置动态表单

在 Pipeline 中配置动态表单

故障排查

#如何配置动态表单

#目录

#功能概述

#使用场景

#快速开始

#能力选择指南

#基础元数据

#表单标签

#表单描述

#占位提示

#表单帮助工具提示

#表单禁用状态

#仅元数据配置，不使用组件

#组件类型

#文本输入

#多行文本输入

#标签输入

#单选

#开关

#YAML 编辑器

#选择框

#基础内容配置

#API 动态选项配置

#增强能力

#参数默认值

#表单校验

#必填校验

#长度校验

#数值范围校验

#正则表达式校验

#预览组件

#链接配置

#高级 Widget

#Combine 组件

#完整示例

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

#在 Task 中配置动态表单

#在 Pipeline 中配置动态表单

#故障排查

如何配置动态表单

目录

功能概述

使用场景

快速开始

能力选择指南

基础元数据

表单标签

表单描述

占位提示

表单帮助工具提示

表单禁用状态

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

组件类型

文本输入

多行文本输入

标签输入

单选

开关

YAML 编辑器

选择框

基础内容配置

API 动态选项配置

增强能力

参数默认值

表单校验

必填校验

长度校验

数值范围校验

正则表达式校验

预览组件

链接配置

高级 Widget

Combine 组件

完整示例

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

在 Task 中配置动态表单

在 Pipeline 中配置动态表单

故障排查