Active Choices 插件

概述

Active Choices 插件用于参数化的自由风格 Jenkins 作业中，用于创建脚本化、动态和交互式的作业参数。Active Choices 参数可以动态更新，并可以呈现为下拉框、复选框、单选按钮或丰富的 HTML UI 小部件。

Active Choices 参数使用 Groovy 或（可选的）Scriptler Groovy 脚本进行编写。这些自定义脚本支持使用 Jenkins Java API、系统环境变量、全局节点属性，以及可能的外部 Java 和 Javascript 库。

插件安装后，将提供三种新的参数类型：

Active Choices 参数
Active Choices 响应式参数
Active Choices 响应式引用参数

注意： 响应式引用参数允许将参数显示为格式化的 HTML。在配置使用此功能的作业时，请考虑参数的呈现方式以及是否可能存在安全问题。

注意： 该插件的开发方式严重依赖 Jenkins UI 的 HTML/DOM。我们使用 JavaScript 导航 DOM 以创建参数之间的关系和响应性。请关注 JENKINS-63284 以获取不依赖 UI 的版本更新。当该问题关闭时，该插件应该可以与流水线、DSL、定时器、cron、REST API 触发的作业等正常工作。

Active Choices 参数允许用户为作业参数选择值。参数值可以：

动态生成（使用 Groovy 或 Scriptler 脚本）
基于其他 UI 参数动态更新
多值（可以有多个值）
使用各种 UI 控件呈现，包括动态 HTML（请注意上述关于安全风险的说明）

我们将通过简要描述 Active Choices 基于 UI 控件的行为和呈现特征来介绍它们。然后，我们将提供配置指南。

Active Choices 参数

行为

Active Choices 参数使用 Groovy 脚本或 Scriptler 目录中的脚本动态生成构建参数的值选项列表。

呈现

Active Choices 参数可以呈现为标准选择列表、复选框和单选按钮。
可以选择显示文本框过滤器以帮助过滤值选项。

Active Choices 响应式和响应式引用参数

这两种参数都具有额外的有用行为，而响应式引用还有一些独特的呈现选项。

行为

与上述 Active Choices 参数类似：

Active Choices 响应式和响应式引用参数使用 Groovy 脚本或 Scriptler 脚本动态生成构建参数的值选项

此外：

当其他作业 UI 控件的值发生变化时，Active Choices 响应式和响应式引用参数可以动态更新（级联更新）

呈现选项

Active Choices 响应式

Active Choices 响应式参数可以呈现为标准选择列表、复选框和单选按钮。
可以选择显示文本框过滤器以帮助过滤值选项。

Active Choices 响应式引用

Active Choices 响应式引用参数用于增强 Jenkins 作业表单 UI 的引用信息。

考虑到这种用例，响应式引用 UI 控件可以呈现为：

HTML 列表（有序或无序）
HTML 输入文本框
动态生成的 HTML（图像、iframe 等）；

动态生成的 HTML 选项可以处理 Groovy 脚本返回的任何格式良好的 HTML。它可以呈现各种 HTML 元素，包括图片、内联框架、超链接、富文本等。

此外，响应式引用参数可以从 UI 中隐藏，从而提供动态生成隐藏构建参数的选项。这些选项将在响应式引用配置部分进一步讨论。

呈现示例

在上面的示例中，当"Gender"参数发生变化时，"Professions"参数的值选项会更新。

此外，呈现为图片的响应式引用参数"Gender_Balance"也会在"Gender"参数更新时动态更新。

行为和呈现总结

下表总结了三种 Active Choices 参数类型的行为和呈现特征。

Active Choices 参数类型配置

该插件包含以下参数类型：

Active Choices 参数
Active Choices 响应式参数
Active Choices 响应式引用参数

现在我们将描述它们的配置详情。

Active Choices 参数：配置选项（示例 01）

Active Choices 参数通过在参数配置中设置以下选项进行配置

"名称"和"描述"

这些是所有 Jenkins 参数通用的典型参数名称和描述

"脚本"

"脚本"是将动态生成参数值选项的 Groovy 代码或 Scriptlet 脚本

通过选择两个单选按钮选项之一，您可以直接输入 Groovy 脚本或使用 Scriptler 脚本
脚本必须返回 java.util.List、数组或 java.util.Map，如下例所示：

return ['选项 1', '选项 2', '选项 3']

"回退脚本"

"回退脚本"配置选项提供了备用参数值选项，以防主脚本失败（抛出异常或未返回 java.util.List、数组或 java.util.Map）。

"选择类型"

**"选择类型"**选项提供了四种不同的选项值呈现方式：

允许单选的列表框
允许多选的列表框
复选框列表（允许多选）
单选按钮列表（允许单选）

"启用过滤器"

**"启用过滤器"**选项将在 UI 控件中提供一个文本框过滤器，可以在其中输入文本过滤器。只有包含该文本的值选项才会列出。

此过滤器不区分大小写。

Active Choices 参数呈现（示例 01）

"示例 01" Active Choices 参数配置生成以下构建表单 UI 控件。用户可以从可过滤的下拉列表中选择单个"州"选项。

设置"默认"选择

可以在初始化 Active Choices UI 控件时默认选择一些选项。

您可以通过在脚本返回的元素中添加后缀 :selected 来定义默认值选择。在下面的示例中，我们将使"Parana"州成为参数 UI 控件呈现时的默认选择。

设置"禁用"选择

您还可以通过添加后缀 :disabled 来定义禁用选择。在下面的示例中，我们将使各种元素被禁用且不可变。

如您所见，:selected 和 :disabled 可以同时指定。

我们感谢 Dynamic Parameter 插件的开发者提供了一些初始概念和代码，Active Choices 就是在此基础上实现的。然而，Active Choices 插件与原始 Dynamic Parameter 插件之间存在几个重要的差异和改进：

Active Choices 参数可以呈现为多选控件（组合框或复选框），允许用户为参数选择多个值
参数选项值列表可以过滤。如果选中"启用过滤器"选项，将显示一个额外的输入框，允许用户过滤选项。
如果值生成器脚本引发异常，您可以定义"回退"行为。
您可以在动态生成的值列表中定义默认值选择

Active Choices 响应式参数：配置选项（示例 02）

Active Choices 响应式参数的配置选项与上面 Active Choices 参数所示的选项类似。然而，响应式参数提供了额外的"引用参数"配置选项。

此选项包含一个作业参数列表，当这些参数中的任何一个发生变化时，会触发响应式参数的自动刷新

"引用参数"

"引用参数"文本字段包含当前作业中以逗号分隔的参数名称列表，当这些参数的值发生变化时，将触发响应式参数的刷新。在重新执行脚本以生成 Active Choices 控件的新选项值集之前，这些参数的值会传递到脚本绑定上下文中。

Active Choices 响应式参数呈现（示例 02）

让我们来看一个使用Active Choices参数渲染的Jenkins构建表单，它满足以下要求。该表单：

允许用户选择几个巴西州中的一个
提供一个额外的控件，动态显示所选州所属的一组城市
允许用户选择显示的城市中的一个或多个

这个job的UI有两个参数：

1) 州：一个Active Choices参数

第一个参数是来自"示例01"的"州"Active Choices参数。它允许用户选择几个巴西州中的一个。我们完全可以使用Jenkins的Choice参数，但我们使用Active Choice参数（如示例01所示）。这个参数的Groovy脚本如下：

return [
    '圣保罗',
    '里约热内卢',
    '巴拉那',
    '阿克里'
]

2) 城市：一个Active Choices Reactive参数

第二个参数是"城市"Active Choices Reactive参数，它动态显示所选州所属的一组城市，并允许用户选择多个值。"城市"参数的配置如上面的"示例02"所示。

注意：

"城市"Reactive参数引用了之前定义的州参数（'引用参数'=州）；
"选择类型"设置为"复选框"。这将允许用户通过选择多个复选框来选择一个或多个"城市"。
将使用自定义的"Groovy脚本"来生成"城市"值选项，如下所示（脚本返回的最后一个列表值）

if (States == "圣保罗") {
  return ["巴雷托斯", "圣保罗", "伊图"]
} else if (States == "里约热内卢") {
  return ["里约热内卢", "曼加拉蒂巴"]
} else if (States == "巴拉那") {
  return ["库里蒂巴", "蓬塔格罗萨"]
} else if (States == "阿克里") {
  return ["里奥布朗库", "阿克雷兰迪亚"]
} else {
  return ["未知州"]
}

每当用户更改州参数的选项时，"城市"参数都会动态更新。注意，引用的"州"参数在脚本绑定中，可以直接使用。

你可以使用Reactive参数类型来做一些事情，比如根据给定的组ID显示Maven构件列表。

Active Choices Reactive Reference参数：配置选项

Reactive Reference参数的配置选项与上面显示的Active Choices Reactive参数的选项类似。

然而，Reactive Reference参数提供了一组独特的渲染选项（参见"选择类型"）。

输入文本框
编号列表
项目符号列表
格式化HTML
格式化隐藏HTML

鉴于渲染选项的多样性，Active Choices Groovy脚本必须为每个选项返回以下类型的变量：

选择类型	Groovy返回	说明
输入文本框	字符串	返回的字符串显示在一个简单的文本框中
编号列表	列表	返回的列表显示为编号列表
项目符号列表	列表	返回的列表显示为项目符号列表
格式化HTML	字符串	返回的字符串必须是格式良好的HTML才能正确显示。你可以在这里包含任何HTML标签，例如：一些<table>，或者指向另一个网站的<form>
格式化隐藏HTML	字符串	参数不会在UI中显示

Reactive Reference参数的一个典型应用是动态显示参考信息，这些信息可以指导用户为另一个作业参数选择适当的值。

根据设计，Reactive Reference参数的值不会传递到构建环境，但有一个重要的例外。当选择类型设置为格式化HTML或格式化隐藏HTML，且HTML是一个'input'元素时，值可以传递到构建。有关其他说明，请参阅"高级用法"部分。

示例配置：Active Choices Reactive Reference参数

下面我们展示了3个具有不同选择类型的Reactive References示例，以及它们在Jenkins作业UI中的相应渲染。

考虑一个例子，用户需要选择一种与可用葡萄酒搭配的餐点。如果在用户考虑特定葡萄酒时能提供一些有用的参考信息，食物的选择会更容易。我们称这个参考信息为"葡萄酒规则"，我们可以使用Reactive Reference参数轻松实现它。

当用户从"葡萄酒菜单"中做出新的选择时，"葡萄酒规则"会自动更新（注意引用参数=葡萄酒菜单）。因此，当我们选择"葡萄酒菜单"时，我们还会得到一个"葡萄酒规则"，可以指导"食物菜单"的选择。

Reactive Reference配置（示例03）

"葡萄酒规则"参数的完整配置如下所示。

Reactive Reference Groovy脚本（示例03）

为每个选项生成"葡萄酒规则"格式化HTML的Groovy脚本如下所示。

switch(WINE_MENU) {
  case ~/.*香槟.*/:
    winerec='香槟适合搭配任何咸味食物'
    return "<b>${winerec}</b>"
  case ~/.*长相思.*/:
    winerec='长相思适合搭配酸味调料和酱汁'
    return "<b>${winerec}</b>"
  case ~/.*绿维特利纳.*/:
    winerec='当菜肴中有大量新鲜香草时，选择绿维特利纳'
    return "<b>${winerec}</b>"
  case ~/.*灰皮诺.*/:
    winerec='灰皮诺适合搭配清淡的鱼类菜肴'
    return "<b>${winerec}</b>"
  case ~/.*霞多丽.*/:
    winerec='选择霞多丽搭配油腻的鱼或富含酱汁的鱼'
    return "<b>${winerec}</b>"
  case ~/.*半干型雷司令.*/:
    winerec='半干型雷司令搭配甜辣菜肴'
    return "<b>${winerec}</b>"
  case ~/.*阿斯蒂莫斯卡托.*/:
    winerec='阿斯蒂莫斯卡托适合水果甜点'
    return "<b>${winerec}</b>"
  case ~/.*干型桃红.*/:
    winerec='将干型桃红葡萄酒与丰富的奶酪菜肴搭配'
    return "<b>${winerec}</b>"
  case ~/.*黑皮诺.*/:
    winerec='黑皮诺适合搭配带有泥土风味的菜肴'
    return "<b>${winerec}</b>"
}

高级用法说明

编写Groovy脚本时的注意事项

你的Groovy脚本绑定可以访问两个额外的变量：

jenkinsProject -> Jenkins项目对象
jenkinsBuild -> Jenkins构建对象

将Reactive Reference值传递给构建

如前所述，通常Reactive Reference参数的值不会传递给构建。但是，在某些情况下，能够传递这些值会很有用。关于这个功能的更详细讨论，你可以在这里阅读。

场景1：传递可由用户编辑的动态创建值

在这种情况下，我们想为用户提供一个可编辑的动态默认值。这可以通过以下Reactive Reference配置实现：

选择类型：格式化HTML
Groovy脚本返回带有动态默认值的HTML input元素
高级选项设置为

场景2：传递隐藏的动态创建值（用户不能编辑）

在这种情况下，我们希望构建能够访问从UI中的用户输入/选项选择动态生成的参数。该参数是以编程方式创建的，用户不能编辑。这可以通过以下Reactive Reference配置实现：

选择类型：格式化隐藏HTML
Groovy脚本返回带有动态默认值的HTML input元素
高级选项设置为

"格式化隐藏HTML"选择类型在你想计算要在构建中使用的值，但这些值不应该被用户修改时很有用（例如，计算部署URL）。

在这两种情况下，Groovy脚本必须返回格式如下的HTML元素：

return "<input name='value' value='${ReactiveRefParam}' class='setting-input' type='text'>"

ReactiveRefParam是将传递给构建的Reactive Reference值

场景3：使用动态HTML创建输入控件并将其值传递给构建

这是Reactive Reference参数的一个有趣应用。它允许你创建具有改进交互性的自定义UI参数控件。参见示例

高级选项：省略值字段

默认情况下，"Reactive References"会向构建传递一个隐藏的<input name="value" value="">。这意味着你的"Reactive Reference"参数将始终为空，但你可以使用"格式化HTML"参数，并指示插件不包含这个隐藏的值参数。

你可以点击"高级"按钮，在那里你会找到一个省略值字段的选项。这将让你为隐藏参数定义一个值。

将Active Choices与Scriptler脚本一起使用

我们假设需要使用Scriptler生成参数的用户已经熟悉Scriptler插件。如果你需要有关如何使用Scriptler插件的更多信息，请首先参阅其Wiki页面。与 Groovy 脚本类似，Scriptler 脚本也是用 Groovy 编写的，用于渲染参数。您的 Scriptler 脚本必须返回 java.util.List、Array 或 java.util.Map 用于 Active Choices 和 Reactive 参数，或者为 Reactive Reference 参数返回自定义 HTML 元素。请注意，当将 Scriptler 与 Active Choices 结合使用时，其他构建参数的值将在 Scriptler 脚本上下文中可用。您无需在 Scriptler 界面或在作业定义期间定义这些参数。

然而，Scriptler 插件提供的主要优势是创建了一个可在多个作业中使用甚至用于自动化的可重用 Groovy 脚本目录。

为了使您的 Scriptler 脚本可以在多个项目中重用，您应该对它们进行参数化，并使用构建参数分配脚本参数。

示例

Scriptler 中的 Environments.groovy

return ["Select:selected", "DEV", "TEST", "STAGE", "PROD"]

Scriptler 中的 HostsInEnv.groovy

// 静态内容示例。这些列表也可以动态生成作为替代方案。
List devList  = ["Select:selected", "dev1", "dev2"]
List testList  = ["Select:selected", "test1", "test2", "test3"]
List stageList = ["Select:selected", "stage1"]
List prodList  = ["Select:selected", "prod1", "prod2", "prod3", "prod4"]

List default_item = ["None"]

if (Environment == 'DEV') {
  return devList
} else if (Environment == 'TEST') {
  return testList
} else if (Environment == 'STAGE') {
  return stageList
} else if (Environment == 'PROD') {
  return prodList
} else {
  return default_item
}

Jenkinsfile 中的流水线

properties([
  parameters([
    [
      $class: 'ChoiceParameter',
      choiceType: 'PT_SINGLE_SELECT',
      name: 'Environment',
      script: [
        $class: 'ScriptlerScript',
        scriptlerScriptId:'Environments.groovy'
      ]
    ],
    [
      $class: 'CascadeChoiceParameter',
      choiceType: 'PT_SINGLE_SELECT',
      name: 'Host',
      referencedParameters: 'Environment',
      script: [
        $class: 'ScriptlerScript',
        scriptlerScriptId:'HostsInEnv.groovy',
        parameters: [
          [name:'Environment', value: '$Environment']
        ]
      ]
   ]
 ])
])

pipeline {
  agent any
  stages {
    stage('Build') {
      steps {
        echo "${params.Environment}"
        echo "${params.Host}"
      }
    }
  }
}

过滤支持正则表达式

请注意，尽管 Active Choices 参数可用的"过滤器"文本框通过简单输入一些文本提供了简单的不区分大小写的过滤功能，但它也支持使用正则表达式进行更复杂的过滤。

以下示例展示了使用正则表达式过滤复杂选项列表的情况。

安全性

v2.0 之前的 Active Choices 版本可能不安全。在使用较旧版本之前，请查看以下警告：

从 Active Choices v2.0 开始，Active Choices Reactive Reference 参数的沙箱 Groovy 脚本将不再发出被认为不安全的 HTML，例如 <script> 标签。这可能导致"使用参数构建"表单上的行为发生变化，如缺少元素。要解决此问题，需要将发出 HTML 的 Groovy 脚本配置为在脚本安全沙箱之外运行，可能需要在"进程内脚本批准"中单独获得管理员批准。

Active Choices 将加载两个额外的 Javascript 文件，JQuery 和 unochoice.js。