参数类插件:Active Choices 与 Multiselect

默认的 choice 参数只能给一个静态列表。要做「下拉项由脚本动态生成」「一个参数的值决定另一个参数的可选项」这类联动,就得靠 Active Choices 插件;要在一个下拉里同时绑定多个环境变量,则用 Multiselect。

Active Choices Parameter:脚本生成选项

Active Choices 的选项由一段 Groovy 脚本返回的列表决定。在 Pipeline 里用 properties([parameters([...])]) 声明,核心是 $class: 'ChoiceParameter' 这一段,choiceType 决定控件形态:

choiceType	控件
PT_SINGLE_SELECT	单选列表
PT_MULTI_SELECT	多选列表
PT_RADIO	单选按钮
PT_CHECKBOX	复选框

properties([
    parameters([
        choice(choices: ['dev', 'alpha'], description: 'P4 branch', name: 'P4Branch'),
        [
            $class: 'ChoiceParameter',
            choiceType: 'PT_SINGLE_SELECT',   // 改这里就能切换控件形态
            filterLength: 1,
            filterable: false,                // true 时列表旁出现过滤框
            name: 'target_stream',
            script: [
                $class: 'GroovyScript',
                fallbackScript: [classpath: [], sandbox: false, script: ''],
                script: [
                    classpath: [],
                    sandbox: false,
                    script: 'return ["Option 1", "Option 2", "Option 3"]'
                ]
            ]
        ]
    ])
])
pipeline {
    agent { node { label 'build-node-1'; customWorkspace "D:\\test" } }
    stages {
        stage("integrate") {
            steps {
                script {
                    echo params.P4Branch
                    echo params.target_stream
                }
            }
        }
    }
}

四种控件的写法只差 choiceType 一个字段,其余完全一样。filterable: true 时会在列表旁多出一个过滤框,选项多时方便检索。

两个常踩的点:

• 新加的参数值不出现,等几秒刷新页面再看。
• 脚本要写多行时用三引号 '''...'''。

Active Choices Reactive Parameter:参数联动

要让「P4Branch 选 dev 时,p4_client 只显示 dev 相关的几项」,用 CascadeChoiceParameter,通过 referencedParameters 声明它依赖哪个参数,脚本里直接用被依赖参数的名字取值:

properties([
    parameters([
        choice(choices: ['dev', 'main'], description: 'P4 branch', name: 'P4Branch'),
        [
            $class: 'ChoiceParameter',         // Active Choices Parameter
            choiceType: 'PT_CHECKBOX',
            filterable: true,
            name: 'target_stream',
            script: [
                $class: 'GroovyScript',
                fallbackScript: [classpath: [], sandbox: false, script: ''],
                script: [classpath: [], sandbox: false,
                    script: 'return ["Option 1", "Option 2", "Option 3"]']
            ]
        ],
        [
            $class: 'CascadeChoiceParameter',   // Active Choices Reactive Parameter
            choiceType: 'PT_SINGLE_SELECT',
            name: 'p4_client',
            referencedParameters: 'P4Branch',   // 依赖的参数名
            script: [
                $class: 'GroovyScript',
                fallbackScript: [classpath: [], sandbox: false,
                    script: 'return ["Could not get p4_client params"]'],
                script: [classpath: [], sandbox: false,
                    script: '''
                        if (P4Branch == "dev")  { return ["dev 1", "dev 2", "dev 3"] }
                        else if (P4Branch == "main") { return ["main 1", "main 2", "main 3"] }
                    ''']   // 上游参数的值决定本参数的选项
            ]
        ]
    ])
])

fallbackScript 是主脚本报错时的兜底返回,联动脚本里一定要写,否则上游参数取不到值时整个下拉会空掉。

Multiselect parameter:一个下拉绑多个变量

Multiselect 用一段 CSV 描述下拉,选中一项时一次性给多个环境变量赋值。注意它不支持 Parameterized Scheduler。

CSV 的行类型:

• H:每个下拉框的表头标签,一个变量一个。
• V:变量名,会作为环境变量在构建过程中使用。
• T:下一行各内容项的显示标题(可选,不写就用内容本身当标签)。
• C:实际内容项,选中后写入对应环境变量。

适合「选一个目标,自动带出它的若干配置项」这种场景,比 Active Choices 写脚本更轻。