6.7 参数设置

  在创建SQL数据集时可以对SQL语句的某些位置进行参数替换，用参数来代替SQL语句中的某些值。达到灵活创建SQL数据集的目的。

  该参数是项目下的资源，不同于“4.10 公共参数”可以跨项目使用。参数可以在一个项目的数据集、图表、图册内使用。但如果切换到了其他的项目后参数需要重新添加与编辑。

6.7.1 参数添加

  进入项目后可以在右上角位置找到参数设置按钮：

  点击后出现参数设置界面：

  点击参数添加后出现参数添加界面：

  点击下拉列表按钮可以进行参数类别选择，目前可以选择字符串、字段、整形、浮点型、日期类型5种不同类别。其中字符串与字段类别区别将在后面进行说明。

• 参数标签用于界面显示，可以用于提示用户该参数的名称，可包含汉字。

• 参数标识为参数的唯一标识，用于编辑SQL语句时进行占位替换。由于SQL语句含有特殊的语法解析规则，参数标识不能包含汉字与特殊字符。同时也不应取与已有系统变量名称相同的名称，否则该参数会被当作系统变量而无法生效。

• 是否可见选框控制该参数能否在播放页面上方显示该参数的播放控件。

  在创建参数时可以输入默认值，该默认值在添加了该参数后默认生效。

  当参数类型为字符串、字段时并且控件类别为单选时。可以进行下拉框设置和默认值绑定，都可以绑定一个独立的数据集可以动态根据数据集时实的结果来对下拉框和默认值进行赋值。 V5.6.08以上的版本中当参数类型为日期类型时，控件类型支持年、年月、日期、时间、周、日期时间六种类型，支持默认值设置相对时间，让日期类型参数的默认值更灵活多变。并且支持控件平铺样式，当启用平铺样式后，如果需要设置样式，需要点击“控件设置”进入设置界面。

6.7.2 参数在SQL数据集内使用

  在进入SQL数据集设置界面后可以在左侧看到该项目下已经添加的参数列表：

  在SQL输入界面输入相应的SQL语句后拖动该参数到SQL语句的位置上，该参数即可添加成功。也可以通过“${参数标识}”的方式来添加。 使用技巧：为了能更精确的解析sql语句，建议在引入sql参数时，在参数最外层嵌套参数标识“{# #}”，比如：select * from a1 where {# a=${参数标识} #}。

  在添加该参数后，如果该参数设置了默认值，参数会被该参数添加的默认值替换。如果没有默认值，则SQL语句完整情况下对参数位置进行恒等替换，该参数不生效。 sql语句较为复杂时，写完后点击上方的“运行SQL”按钮运行，如果有语法错误请结合错误信息调整sql语句直到可以成功执行。

6.7.3 参数在图表内使用

  在选择了数据集后，如果该数据集包含了参数并且参数含有默认值，则参数最后添加的默认值生效，进行SQL语句替换生成SQL数据集。

  在下方有参数选框，可以拖动需要的参数到图表上方的区域，进行参数选定。在设定好相应的参数内容后点击确定，参数即可生效。

  为保证参数的独立性，避免修改参数时造成其他图表的改变，图表的参数在首次添加时与该项目下的参数含有继承关系，但添加后该参数与此图表绑定，与该项目的参数没有关联关系，修改图表内的参数时，其他使用了该参数的图表、图册的参数设置并不会随之改变。再次点选上方参数可以打开参数的修改界面。

6.7.4 参数在图表播放时使用

  参数可以添加到图表上方的过滤区，充当过滤条件使用，在播放页面参数改变时，随着参数的改变图表数据会随之改变。

6.7.5 参数在图册内使用

  与参数在图表页的使用相同，参数需要在左下方进行拖动选择，但与图表不同的是该参数会作用于所有数据集中引入参数的图表，并且值会覆盖这类图表的对应参数。

  参数在拖到上方控件上后，也可以拖到图册的自由块中，以一个参数控件形式存在。当拖拽到自由块中时，通常要开启高级设置下的“自动刷新数据”功能。

6.7.6 参数在图册播放时使用

  ​与图表播放时参数的使用方法相同，图册页会显示图册页添加并且可见的参数。修改参数值会作用于所有数据集中引入参数的图表。在项目下添加了参数后，可以在图册或图表内进行参数拖动使用。拖动后的参数设置界面包含许多功能。

  自动刷新数据选框控制该参数在更改时是否直接进行图表数据刷新，如果关闭该选框则需要点击上方的确认后才进行图表刷新。   设置控件宽度选框当开始时可以进行控件宽度设置。   地址传参可以将当前参数的JSON格式信息做显示，方便进行复制与URL传参。   控件样式设置可以对控件的样式进行修改，以一个JS对象形式进行保存，播放时生效。

6.7.6.1 在图册或图表内进行字符串与字段型参数使用

  参数类型为字符串或字段类型时，可以修改与设置参数在播放时的控件样式。有三种不同的控件类型分别为输入框，单选框与多选框。

  其中单选框与多选框需要在详细设置下进行选框内容绑定。目前共有数据集、自定义数据、系统变量三种内容绑定方式。其中自定义数据可以输入不同的选框内容，以逗号作为两个不同取值的间隔。

6.7.6.2 在图册或图表内进行整形与浮点型参数使用

  整形与浮点型的参数控件类型默认带一个滑动条，可以在详细设置里修改滑动条的属性，或取消隐藏滑动条。

6.7.6.3 在图册或图表内进行日期参数使用

  日期类型可以在设置界面修改不同的控件类型，包括年、年月、日期、时间、日期时间五种不同的控件类型。

6.7.6.3.1 日期参数设置相对时间

日期类型的参数除了可以设置固定默认时间外还可以设置相对时间来根据当前时间动态生成默认值，点击“相对时间”按钮即可进行编辑： 根据控件类型的不同生成的界面也会有所不同。 以日期+时间的日期类型参数为例，在界面上的年月日等日期部分上可以设置前、后、当前、与固定四种相对关系。前后较为好理解，设置为当前时后方的相对时间输入框内容不再生效，比如年份的相对时间设置为当前，则取当前年份2021为该参数的年。当先取固定时可以在后面的输入框输入固定的时间设置，比如在年的输入框输入2020，该参数的年会固定到2020年。
日的设置有周与日两种粒度的设置规则，可以选取上几周的星期几为相对时间的日的取值。

6.7.7 Url中参数的使用方法

  除了手动拖动参数进行参数添加外，还可以将参数引入到Url的方式来进行参数的使用。添加的方式为在Url（如果Url包含“#”则在“#”之前）添加"&paramList=[]"。

单个参数的JSON模板为:

{
"paramName": "Name",
"paramType": "STRING",
"defaultValueList": ["1"],
"viewable": false,
"required": false
}

分别对应参数标识名，参数类型:

  "STRING" //字符串, 
   "FIELD" //字段,  
   "INT" //整形,   
   "FLOAT" //浮点型,
   "DATE" //日期类型

参数默认值（“可为多个，格式与JSON数组格式相同”），是否可见，是否必填。

参数的JSON模板格式获取方式为： 在图册中点击“地址传参”按钮，即可获取到完整的JSON模板，根据获取到的值，进行以上单个参数模板每个参数的赋值替换。

多个参数见用“，”相隔填入&paramList=[]的“[]”内部。除此之外由于要放在Url上需要对传参内容进行UrlEncode编码。

完成未编码前参数示例为：

&paramList=[{
  "paramName": "param1",
  "paramType": "STRING",
  "defaultValueList": ["1"],
  "viewable": true,
  "required": false},
  {
  "paramName": "param2",
  "paramType": "FIELD",
  "defaultValueList": ["2"],
  "viewable": true,
  "required": false}]

以上是参数param1和param2分别赋值1和2后生成的JSON格式的模板，接着要进行URL转码操作，可以使用“https://www.sojson.com/encodeurl.html”网址 或百度其他网址。将"[]" 内的内容包括[]进行转码处理即可获取到完整的URL。

6.7.7.1 Url传参的简化

为了简化Url传参的输入内容增加了简化的Url参数功能，当前图册已经使用了某个参数时可以在Url末尾添加“&参数标识=参数取值”来对这个图册参数赋值。比如图册引用了一个参数标识为position的参数，在Url后输入“&position=吉林”即可为图册参数position赋值为吉林，达到Url传参目的，URL转码只需要将中文转码即可。

6.7.8 不同参数类别的优先级

  Url参数优先级>图册参数优先级>图表优先级，高优先级会覆盖低优先级的参数。

6.7.9 SQL语句的替换规则及不同类型参数的区别

  其他参数类别较好理解，字符型与字段型的区别为，字符型在替换时会在前后添加引号作为字符型标识，字段型则不会。

  举例说明，同样的参数值为value，字符型会替换成“value”,字段型只会替换成value,不添加其他的内容。可以理解为字段型适用于in 字符型适用于=的场景。

6.7.10 参数在Rest数据源中使用

  如果在项目中使用的Rest数据源，那么在Rest数据源中通过http请求获取数据时，会把参数的值通过参数映射传递给接口，详见：《4.1 数据源》中的《4.1.4.2.2 请求参数》

6.7.11 参数绑定下拉框下拉选项

  字符串与字段类型可以设置控件类型为单选与多选，为了满足用户动态生成单选与多选的需求，目前参数可以绑定动态的下拉框，功能入口如下图： 点击后可以进入绑定功能界面 目前支持绑定三种下拉框内容，分别为数据集、自定义数据、系统变量。 在点选了数据集后可以在下方点选不同的数据集，在选择了确定的数据集后可以在下方点选该数据集的不同字段来完成ID字段与名称字段的绑定。 ID字段为该下拉选项字段的具体取值，名称字段为该下拉字段在下拉栏内的文字提示。比如数据集内有两个字段，分别为身份证号与姓名，可以选取姓名为名称字段，身份证为ID字段，在下拉栏内您只会看到姓名，但是点选后该姓名对应身份证号会生效赋值到参数上。 自定义字段可以在此处输入你需要的下拉框内容，比如星期、年份等，不同的下拉选项以逗号进行间隔，点击确定后会根据输入的内容生成相应的下拉框内容。 在系统变量下可以选择与当前系统或用户有关的内容作为下拉框的下拉选项。

6.7.12 参数绑定动态默认值

  用户在某些使用场景时可能会使用动态的参数默认值来达到动态控制参数的目的。功能入口如下： 在此处可以绑定动态默认值的来源，当前支持数据集与系统变量。 当选择数据集时可以点选不同的数据集，在设置了绑定值字段后，该参数的默认值就会自动生成。默认值为该数据集与该字段下的第一条数据。为了保证参数默认值的有效性建议该数据集仅有一条数据。 系统变量与上一章的系统变量相同，绑定后会选取第一条数据生效。 是否开启的选项处于打开状态后该动态默认值会生效。