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。

支持的语言

1. 英语
2. 葡萄牙语（巴西）进行中
3. 如果您想包含您的语言，请向我们发送带有 messages.properties 文件的拉取请求或与我们联系！

已知限制

1. 参数应该仅由人类处理，目前不适用于插件、API 或脚本触发的作业。更多信息请参见此问题。
2. 在提交问题之前，请查看故障排除页面

发布说明

请参阅 CHANGES.md 文件。

赞助商

如需商业支持，请通过 @tupilabs 与我们联系。

要了解插件的来源，请查看 BioUno 项目。

如果您希望赞助插件的开发或 JIRA 中的公开问题，请与我们联系。

其他资源

• "使用 HTML、Groovy 和 Bash 在 Jenkins 流水线中实现动态和响应式参数化"，作者：Esteban Echavarria Collazos - 链接

在 BioUno 网站上查看文章、教程和出版物列表