参数设计

1. 简介

1.1 功能简介

参数设计是指对插件使用时需要填写的内容进行字段设置。包括在开启插件前的插件配置，在前端事件、智能助手、流程节点中执行时需要设置的执行动作。

1.2 应用场景

1.3 预期效果

以设置前端事件中的执行动作为例，执行动作中的参数即本章节需要配置的参数。效果如下所示：

2. 参数设计

插件有 4 种类型的参数可以配置，四者都非必须，按场景所需添加即可：

2.1 身份验证

1）身份验证是指用户在配置插件时需要填写应用的相关信息。插件设计过程中，您可选择「无」不验证身份，也可根据不同的集成模式进行身份验证，简道云中支持通过以下 6 种方式验证身份：

2）当选择身份验证方式为钉钉自建应用、企业微信应用、飞书自建应用和微信公众平台时，插件配置时需输入对应的应用 ID、应用 Key 和应用 Secret 进行身份验证。以选择钉钉自建应用为例，插件配置时效果如下所示：

3）当选择身份验证方式为 Basic Auth 时，插件配置时需输入对应的 Username 和 Password 进行身份验证。用户也可点击「添加参数」来设置更多身份验证选项，同时可在右侧属性栏中设置参数相关属性。

以授权参数仅为 Username 和 Password 为例，插件配置效果如下所示：

4）当选择身份验证方式为 OAuth2.0 - Authorization Code 时，验证方式支持设置以下内容：

以配置重定向地址、授权参数、进行OAuth 2.0 端点配置为例，插件配置效果如下所示：

5）当选择身份验证方式为 OAuth2.0 - Client Credentials 时，验证方式支持设置以下内容：

以授权参数仅为 ClientID 和 ClientSecret 为例，插件配置效果如下所示：

2.2 通用参数

通用参数是使用插件时要配置的参数针对整个插件的参数。通常是在启用插件前，对插件进行的配置。

如，对接第三方平台需要配置的 API Key 等参数均可以在通用参数中设置。

2.3 请求参数

请求参数是在不同位置（比如前端事件/智能助手）中使用插件时，插件使用者需要提供的内容。比如：调用简道云部门接口时，需要使用者提供部门信息。

在设计请求参数时，可以选择不同类型的字段。不同的字段类型影响插件用户在配置插件时的输入方式，以及您在代码中获取到的值的类型。

1）您在入参声明中添加了一个「部门选择」类型的参数，那么您的用户在配置插件时，将只能在界面上选择部门类型的值，或引用表单数据中支持转换为该类型的字段，比如「部门单选」/「部门多选」。

2）您在入参声明中添加了一个「子表单」类型的参数，那么您的用户在配置插件时，将只能在界面上选择子表单类型的值，并且可以选择「子表单赋值」或者「逐行赋值」。

2.4 返回参数

返回参数是指插件执行完成后，返回给插件使用者的内容。插件使用者可以选择需要的内容回填至表单中，或传递给其他插件的其他函数。比如：调用部门接口后，将会返回部门下成员信息，可以将成员信息定义成返回参数。

2）参数类型可选择 any、object[]。

默认为 any，适用于请求参数与返回参数一对一的情况。

object[]，适用于请求参数与返回参数一对多的情况，返回信息为数组，比如通过部门查询部门下成员时，可能有多个成员。

若设置了参数类型为 object[]，则可通过点击列表头前的「+ 号」按钮，向下新增一行，作为子节点，如下所示。子节点的含义为数组内的具体元素，比如：返回多个成员，每个成员信息包含 成员昵称、成员编号等。

3）返回参数在前端事件插件中，配置效果如下所示：

2.5 表单校验提示信息

表单视图下配置通用参数、请求参数和返回参数时，支持对输入内容进行格式提示和实时校验，以降低输入错误的可能性，便于开发者校验修改表单配置，提高开发效率。效果如下图所示：