amis/docs/components/form/options.md
2020-09-22 17:07:41 +08:00

34 KiB
Executable File
Raw Blame History

title description type group menuName icon order
Options 选择器表单项 0 null Options 选择器表单项 2

选择器表单项 是指那些(例如下拉选择框)具有选择器特性的表单项

它派生自 表单项,拥有表单项所有的特性。

选项组格式

选择器表单项可以通过配置一组选项(options),可以供给用户选择,如下:

{
    "type": "form",
    "controls": [
        {
            "label": "选项",
            "type": "select",
            "name": "select",
            "options": [
                {
                    "label":"A",
                    "value":"a"
                },
                {
                    "label":"B",
                    "value":"b"
                },
                {
                    "label":"C",
                    "value":"c"
                }
            ]
        }
    ]
}

options属性配置的对象数组就是select选择器组件的选项组。

标准格式

{
    "options": [
        {
            "label": "xxx1",
            "value": "value1",
            "children": []
            ... // 其他变量值
        },
        {
            "label": "xxx2",
            "value": "value2",
            "children": []
            ... // 其他变量值
        }
    ]
}

标准的选项格式为对象数组,数组中的每个对象需要两个必备字段:

  • label:标识当前选项的显示文本,帮助用户选择
  • value:标识当前选项的值,用作数据保存和映射
  • children:嵌套子选项,只有在 Tree 或 Nested-Select 等支持嵌套功能的组件中才有用

查看下面例子,修改选项你会发现数据域会发发生变化,改数据域中该表单项的值为选中选项的value值。

{
    "type": "form",
    "debug": true,
    "controls": [
        {
            "label": "选项",
            "type": "select",
            "name": "select",
            "options": [
                {
                    "label":"A",
                    "value":"a"
                },
                {
                    "label":"B",
                    "value":"b"
                },
                {
                    "label":"C",
                    "value":"c"
                }
            ]
        }
    ]
}

简单格式

也可以配置简单的字符串或数字数组,此时默认labelvalue保持一致

{
    "type": "form",
    "debug": true,
    "controls": [
        {
            "label": "选项",
            "type": "select",
            "name": "select",
            "options": ["A", "B", "C"]
        }
    ]
}

静态选项组 options

可以使用静态方式,配置一组选项组:

{
    "type": "form",
    "controls": [
        {
            "label": "选项",
            "type": "select",
            "name": "select",
            "options": [
                {
                    "label":"A",
                    "value":"a"
                },
                {
                    "label":"B",
                    "value":"b"
                },
                {
                    "label":"C",
                    "value":"c"
                }
            ]
        }
    ]
}

动态选项组 source

通过数据域中变量配置

你也可以配置source属性,利用 数据映射,获取当前数据链中的变量

{
    "type": "form",
    "data": {
        "items": [
            {
                "label":"A",
                "value":"a"
            },
            {
                "label":"B",
                "value":"b"
            },
            {
                "label":"C",
                "value":"c"
            }
        ]
    },
    "controls": [
        {
            "label": "选项",
            "type": "select",
            "name": "select",
            "source": "${items}"
        }
    ]
}

上例中,我们给 select 组件,配置"source": "${items}",获取了当前数据域中的items变量作为选项组。

远程拉取

除了可以通过数据映射获取当前数据域中的变量以外,source还支持配置接口,格式为 API,用于动态返回选项组。

{
    "type": "form",
    "controls": [
        {
            "label": "选项",
            "type": "select",
            "name": "select",
            "source": "https://houtai.baidu.com/api/mock2/form/getOptions?waitSeconds=1"
        }
    ]
}

远程拉取接口时,返回的数据结构除了需要满足 amis 接口要求的基本数据结构 以外,必须用"options"作为选项组的key值,如下

{
  "status": 0,
  "msg": "",
  "data": {
    // 必须用 options 作为选项组的 key 值
    "options": [
      {
        "label": "A",
        "value": "a"
      },
      {
        "label": "B",
        "value": "b"
      },
      {
        "label": "C",
        "value": "c"
      }
    ]
  }
}

默认值/自动选中 value

我们知道表单项可以通过配置value属性来设置默认值

而选择器表单项如果设置value属性,为某一个选项中的value值,那么该选择器将自动选中该选项。

静态配置

静态配置同表单项默认值配置方式,直接在组件上配置value属性。

{
    "type": "form",
    "controls": [
        {
            "label": "选项",
            "type": "select",
            "name": "select",
            "value": "b",
            "options": [
                {
                    "label":"A",
                    "value":"a"
                },
                {
                    "label":"B",
                    "value":"b"
                },
                {
                    "label":"C",
                    "value":"c"
                }
            ]
        }
    ]
}

上例我们设置默认值为b,则会自动匹配到选项B并选中。

动态配置

有时候我们想默认选中一个选项,但是options又是远程拉取的,无法确定默认值是啥,这时候,需要在source接口中返回value,来动态设置默认值接口返回数据结构如下:

{
  "status": 0,
  "msg": "",
  "data": {
    "value": "b", // 这样就会自动选中b选项
    "options": [
      {
        "label": "A",
        "value": "a"
      },
      {
        "label": "B",
        "value": "b"
      },
      {
        "label": "C",
        "value": "c"
      }
    ]
  }
}

数据格式一致性问题

当使用 sourcevalue 配置默认值的时候,需要保持数据格式的一致性。

如果使用 sourcevalue 配置的默认值与当前表单项配置的数据格式不符合,而且用户没有再次操作该表单项,而直接提交表单,那么会将当前默认值原封不动的提交给后端,可能会导致不一致性的问题,我们看一个例子:

{
    "type": "form",
    "controls": [
        {
            "label": "选项",
            "type": "select",
            "name": "select",
            "multiple": true,
            "value": ["a", "c"],
            "options": [
                {
                    "label":"A",
                    "value":"a"
                },
                {
                    "label":"B",
                    "value":"b"
                },
                {
                    "label":"C",
                    "value":"c"
                }
            ]
        }
    ]
}

上例中, select 我们配置了"multiple": true,预期中,我们希望选中 AC 项时,表单项的数据格式为:"a,c",但是我们设置了"value": ["a", "c"],并不符合我们当前表单项的数据格式配置,这样会导致两个问题:

  1. 有可能不会默认选中 AC 选项;
  2. 当不操作该表单项,直接提交时,预期是:"a,c",但提交给后端的数据为:["a", "c"],导致了不一致性的问题。

通过 source 配置默认值同理,不再赘述

因此一定确保默认值与选择器表单项数据格式配置相匹配。

多选 multiple

大部分选择器组件默认是单选的,可以配置"multiple": true支持多选。

{
    "type": "form",
    "debug": true,
    "data": {
        "options": [
            {
                "label": "A",
                "value": "a"
            },
            {
                "label": "B",
                "value": "b"
            },
            {
                "label": "C",
                "value": "c"
            }
        ]
    },
    "controls": [
        {
            "label": "单选",
            "type": "select",
            "name": "select1",
            "source": "${options}"
        },
        {
            "type": "divider"
        },
        {
            "label": "多选",
            "type": "select",
            "name": "select2",
            "multiple": true,
            "source": "${options}"
        }
    ]
}

默认多选的值格式为逗号拼接 value 值,例如:1,2,3,如果需要改变值格式,请阅读下面 拼接符 delimiter拼接值 joinValues提取多选值 extractValue配置项。

拼接符 delimiter

多选模式下,默认表单项值为选中的选项的value值,用默认拼接符,拼接,如下

{
    "type": "form",
    "debug": true,
    "controls": [
        {
            "label": "选项",
            "type": "select",
            "name": "select",
            "multiple": true,
            "options": [
                {
                    "label":"A",
                    "value":"a"
                },
                {
                    "label":"B",
                    "value":"b"
                },
                {
                    "label":"C",
                    "value":"c"
                }
            ]
        }
    ]
}

默认的拼接符是逗号,,但是当你的某个选项中的value值内包含,这个字符,这样会造成一些预期中的问题

你可以设置delimiter属性,自定义拼接符,保证不与你选项中的value值冲突

{
    "type": "form",
    "debug": true,
    "controls": [
        {
            "label": "选项",
            "type": "select",
            "name": "select",
            "multiple": true,
            "delimiter": "|",
            "options": [
                {
                    "label":"A",
                    "value":"a,1"
                },
                {
                    "label":"B",
                    "value":"b,2"
                },
                {
                    "label":"C",
                    "value":"c,3"
                }
            ]
        }
    ]
}

上例我们value中有逗号,与默认拼接符冲突,这时设置"delimiter": "|",可以看到选择多个选项时,每个选项的value属性会用|拼接起来,作为表单项的值

拼接值 joinValues

当选择器表单项选中某一选项后,当前表单项的值格式默认:

  • 单选:选中选项的value
  • 多选:选中所有选项的value,用拼接符进行拼接,默认拼接符为,

选中下面两个选择器,观察数据域值变化。

{
    "type": "form",
    "debug": true,
    "controls": [
        {
            "label": "单选",
            "type": "select",
            "name": "select1",
            "options": [
                {
                    "label": "A",
                    "value": "a"
                },
                {
                    "label": "B",
                    "value": "b"
                },
                {
                    "label": "C",
                    "value": "c"
                }
            ]
        },
        {
            "type": "divider"
        },
        {
            "label": "多选",
            "type": "select",
            "name": "select2",
            "multiple": true,
            "options": [
                {
                    "label": "A",
                    "value": "a"
                },
                {
                    "label": "B",
                    "value": "b"
                },
                {
                    "label": "C",
                    "value": "c"
                }
            ]
        }
    ]
}

但是你可以通过配置"joinValues": false,来获取完整的选项对象

单选模式

单选模式下,配置"joinValues": false,该表单项值为选中选项的完整对象值,选中下例中的任意选项,观察数据域变化。

{
    "type": "form",
    "debug": true,
    "controls": [
        {
            "label": "选项",
            "type": "select",
            "name": "select",
            "joinValues": false,
            "options": [
                {
                    "label":"A",
                    "value":"a"
                },
                {
                    "label":"B",
                    "value":"b"
                },
                {
                    "label":"C",
                    "value":"c"
                }
            ]
        }
    ]
}

多选模式

多选模式下,配置"joinValues": false,该表单项值为所有选中项的对象数组

{
    "type": "form",
    "debug": true,
    "controls": [
        {
            "label": "选项",
            "type": "select",
            "name": "select",
            "multiple": true,
            "joinValues": false,
            "options": [
                {
                    "label":"A",
                    "value":"a"
                },
                {
                    "label":"B",
                    "value":"b"
                },
                {
                    "label":"C",
                    "value":"c"
                }
            ]
        }
    ]
}

自动选中问题

当你通过joinValues调整选择器表单项的数据结构后,设置默认值时,格式也要和设置的数据结构保持一致

例如下面这个例子,当你给select设置了"joinValues": false时,选中 B 选项,则该表单项值为{"label":"B","value":"b"},如果你想要默认选中某一项,则也需要设置value为完整的对象:{"label":"B","value":"b"}

{
    "type": "form",
    "debug": true,
    "controls": [
        {
            "label": "选项",
            "type": "select",
            "name": "select",
            "joinValues": false,
            "value": {
                "label":"B",
                "value":"b"
            },
            "options": [
                {
                    "label":"A",
                    "value":"a"
                },
                {
                    "label":"B",
                    "value":"b"
                },
                {
                    "label":"C",
                    "value":"c"
                }
            ]
        }
    ]
}

提取多选值 extractValue

"joinValues": false时,默认会将选中的所有选项组成的对象数组,作为表单项的值,如果你想只抽取选项中的 value 值,拼成新的数组,那么可以配置"extractValue": true

{
    "type": "form",
    "debug": true,
    "controls": [
        {
            "label": "选项",
            "type": "select",
            "name": "select",
            "multiple": true,
            "joinValues": false,
            "extractValue": true,
            "options": [
                {
                    "label":"A",
                    "value":"a"
                },
                {
                    "label":"B",
                    "value":"b"
                },
                {
                    "label":"C",
                    "value":"c"
                }
            ]
        }
    ]
}

选中所有选型,你会看到表单项的值为:["a", "b", "c"]

自动选中问题

当你通过joinValuesextractValue调整选择器表单项的数据结构后,设置默认值时,格式也要和设置的数据结构保持一致

例如下面这个例子,当你给select设置了"joinValues": false"extractValue": true时,选中 A、B 选项,则该表单项值为["a", "b"],如果你想要默认选中某一项,则也需要设置value为同样格式:["a", "b"]

{
    "type": "form",
    "debug": true,
    "controls": [
        {
            "label": "选项",
            "type": "select",
            "name": "select",
            "multiple": true,
            "joinValues": false,
            "extractValue": true,
            "value": ["a", "b"],
            "options": [
                {
                    "label":"A",
                    "value":"a"
                },
                {
                    "label":"B",
                    "value":"b"
                },
                {
                    "label":"C",
                    "value":"c"
                }
            ]
        }
    ]
}

检索 searchable

可以配置 "searchable": true 显示前端过滤,适合用于有大量内容的列表。

{
    "type": "form",
    "controls": [
        {
            "label": "选项",
            "type": "select",
            "name": "select",
            "searchable": true,
            "options": [
                {
                    "label":"A",
                    "value":"a"
                },
                {
                    "label":"B",
                    "value":"b"
                },
                {
                    "label":"C",
                    "value":"c"
                }
            ]
        }
    ]
}

自动补全 autoComplete

{
    "type": "form",
    "controls": [
        {
            "name": "select",
            "type": "select",
            "label": "选项自动补全",
            "autoComplete": "https://houtai.baidu.com/api/mock2/options/autoComplete?term=$term",
            "placeholder": "请输入"
        }
    ]
}

可以在autoComplete配置中,用数据映射,获取变量term,为当前输入的关键字。

支持该配置项的组件有Text、Select、Chained-Select、TreeSelect。

选项标签字段 labelField

默认渲染选项组,会获取每一项中的label变量作为展示文本,如果你的选中项中没有label字段,可能会有显示问题

例如下例中options 中只有textvalue字段而没有 value 字段,这时点开下拉框,你会发现选项无法正常显示。

{
    "type": "form",
    "debug": true,
    "controls": [
        {
            "label": "选项",
            "type": "select",
            "name": "select",
            "options": [
                {
                    "text":"A",
                    "value":"a"
                },
                {
                    "text":"B",
                    "value":"b"
                },
                {
                    "text":"C",
                    "value":"c"
                }
            ]
        }
    ]
}

这种情况下如果你想自定义该字段,则可以设置labelField

{
    "type": "form",
    "debug": true,
    "controls": [
        {
            "label": "选项",
            "type": "select",
            "name": "select",
            "labelField": "text",
            "options": [
                {
                    "text":"A",
                    "value":"a"
                },
                {
                    "text":"B",
                    "value":"b"
                },
                {
                    "text":"C",
                    "value":"c"
                }
            ]
        }
    ]
}

不推荐使用该方式,建议格式化好选项组数据结构

选项值字段 valueField

默认渲染选项组,会获取每一项中的value变量作为表单项值,如果你的选中项中没有value字段,将会无法选中

例如下例中options 中只有labelval字段而没有value字段,这时点开下拉框,你会发现选项无法正常选中。

{
    "type": "form",
    "debug": true,
    "controls": [
        {
            "label": "选项",
            "type": "select",
            "name": "select",
            "options": [
                {
                    "label":"A",
                    "val":"a"
                },
                {
                    "label":"B",
                    "val":"b"
                },
                {
                    "label":"C",
                    "val":"c"
                }
            ]
        }
    ]
}

这种情况下如果你想自定义该字段,则可以设置valueField

{
    "type": "form",
    "debug": true,
    "controls": [
        {
            "label": "选项",
            "type": "select",
            "name": "select",
            "valueField": "val",
            "options": [
                {
                    "label":"A",
                    "val":"a"
                },
                {
                    "label":"B",
                    "val":"b"
                },
                {
                    "label":"C",
                    "val":"c"
                }
            ]
        }
    ]
}

不推荐使用该方式,建议格式化好选项组数据结构

新增选项

部分选择器组件支持在前端进行新增选项的操作。

支持该功能的组件有CheckBoxes、Select、Tree

前端新增 creatable

,可以配置"creatable": true,支持在前端临时新增选项。

{
    "type": "form",
    "controls": [
        {
            "label": "选项",
            "type": "select",
            "name": "select",
            "creatable": true,
            "options": [
                {
                    "label":"A",
                    "value":"a"
                },
                {
                    "label":"B",
                    "value":"b"
                },
                {
                    "label":"C",
                    "value":"c"
                }
            ]
        }
    ]
}

点开下拉框,会看到选项列表底部有新增选项按钮,点击后会显示一个包含简单表单的弹框,点击提交可以新增选项,不同组件交互会有不同。

新增选项表单弹框的默认配置如下:

{
  "type": "dialog",
  "title": "新增选项",
  "body": {
    "type": "form",
    "controls": [
      {
        "type": "text",
        "name": "label",
        "label": false,
        "placeholder": "请输入名称"
      }
    ]
  }
}
  • 你可以配置createBtnLabel来自定义这个弹框的标题;
  • 你也可以配置optionLabel,来替换"选项"这个字符,如我们配置"optionLabel": "员工",标题会显示:新增员工
  • 默认表单项的name属性为labelField所配置的值,默认为label

自定义新增表单项 addControls

默认只有一个文本框,也就是意味着,默认添加选项后,该选项labelvalue是一样的,如果你想自定义该表单中的表单项,你可以通过配置addControls属性

{
    "type": "form",
    "debug": true,
    "controls": [
        {
            "label": "选项",
            "type": "select",
            "name": "select",
            "creatable": true,
            "addControls": [
                {
                    "type": "text",
                    "name": "label",
                    "label": "选项标题"
                },
                {
                    "type": "text",
                    "name": "value",
                    "label": "选项值"
                }
            ],
            "options": [
                {
                    "label":"A",
                    "value":"a"
                },
                {
                    "label":"B",
                    "value":"b"
                },
                {
                    "label":"C",
                    "value":"c"
                }
            ]
        }
    ]
}

上例中你可以选项标题输入D,选项值输入d。实现自定义添加选项格式

不过在没配置保存接口时,addControls中务必需要有labelFieldvalueField所配置的name表单项才可以正确保存

addControls属性格式为表单项数组,更多细节参考 FormItem 表单项

配置新增接口 addApi

默认新增只会暂时把新增的值保存在前端,如果你想前端新增选项后,同时把该选项保存到后端,则可以配置保存接口addApi

{
    "type": "form",
    "controls": [
        {
            "label": "选项",
            "type": "select",
            "name": "select",
            "addApi": "https://houtai.baidu.com/api/mock2/form/saveForm",
            "options": [
                {
                    "label":"A",
                    "value":"a"
                },
                {
                    "label":"B",
                    "value":"b"
                },
                {
                    "label":"C",
                    "value":"c"
                }
            ]
        }
    ]
}

配置addApi实际上将该配置值设置给该表单的api属性。

如果同时配置了sourceaddApi,添加选项成功后会重新获取请求source接口

编辑选项

部分选择器组件支持在前端编辑选项

支持该功能的组件有CheckBoxes、Select、Tree、Table-formitem

前端编辑 editable

配置"editable": true,支持在前端编辑选项。

{
    "type": "form",
    "debug": true,
    "controls": [
        {
            "label": "选项",
            "type": "select",
            "name": "select",
            "editable": true,
            "options": [
                {
                    "label":"A",
                    "value":"a"
                },
                {
                    "label":"B",
                    "value":"b"
                },
                {
                    "label":"C",
                    "value":"c"
                }
            ]
        }
    ]
}

点开下拉框,会看到每个选项右侧有一个编辑图标,点击后会显示一个编辑选项的弹框,修改后点击提交可以编辑选项标签。不同组件交互会有不同

编辑选项弹框的默认配置如下:

{
  "type": "dialog",
  "title": "新增选项",
  "body": {
    "type": "form",
    "controls": [
      {
        "type": "text",
        "name": "label",
        "label": false,
        "placeholder": "请输入名称"
      }
    ]
  }
}
  • 你也可以配置optionLabel,来替换"选项"这个字符,如我们配置"optionLabel": "员工",标题会显示:新增员工
  • 默认表单项的name属性为labelField所配置的值,默认为label

自定义编辑表单项 editControls

默认只能修改当前选项的label属性,如果你想要修改其他属性,可以配置editControls,自定义编辑表单项

{
    "type": "form",
    "debug": true,
    "controls": [
        {
            "label": "选项",
            "type": "select",
            "name": "select",
            "editable": true,
            "editControls": [
                {
                    "type": "text",
                    "name": "label",
                    "label": "选项标题"
                },
                {
                    "type": "text",
                    "name": "value",
                    "label": "选项值"
                }
            ],
            "options": [
                {
                    "label":"A",
                    "value":"a"
                },
                {
                    "label":"B",
                    "value":"b"
                },
                {
                    "label":"C",
                    "value":"c"
                }
            ]
        }
    ]
}

修改后重新选中该表单项,观察数据域中数据变化。

配置编辑接口 editApi

默认编辑只会作用在前端,如果你想前端编辑选项后,同时把该选项保存到后端,则可以配置保存接口editApi

{
    "type": "form",
    "controls": [
        {
            "label": "选项",
            "type": "select",
            "name": "select",
            "editApi": "https://houtai.baidu.com/api/mock2/form/saveForm",
            "options": [
                {
                    "label":"A",
                    "value":"a"
                },
                {
                    "label":"B",
                    "value":"b"
                },
                {
                    "label":"C",## 二级标题
                    "value":"c"
                }
            ]
        }
    ]
}

配置editApi实际上将该配置值设置给编辑表单的api属性。

如果同时配置了sourceeditApi,添加选项成功后会重新获取请求source接口

删除选项

部分选择器组件,支持在前端进行编辑选项操作

支持该功能的组件有CheckBoxes、Select、Tree、Table-formitem

配置删除接口 deleteApi

删除选项不支持在前端级别删除,我们认为是没有意义的,必须要配置deleteApi使用接口进行删除

配置"removable": truedeleteApi,支持在前端删除选项。

{
    "type": "form",
    "debug": true,
    "controls": [
        {
            "label": "选项",
            "type": "select",
            "name": "select",
            "deleteApi": "https://houtai.baidu.com/api/mock2/form/saveForm",
            "options": [
                {
                    "label":"A",
                    "value":"a"
                },
                {
                    "label":"B",
                    "value":"b"
                },
                {
                    "label":"C",
                    "value":"c"
                }
            ]
        }
    ]
}

点开下拉框,鼠标悬浮在选项上,可以看到右侧会有删除图标,点击可请求删除接口进行删除

自动填充 autoFill

一些选择器组件,支持配置autoFill,将当前已选中的选项的某个字段的值,自动填充到表单中某个表单项中,只在单选时有效,支持数据映射

{
    "type": "form",
    "api": "https://houtai.baidu.com/api/mock2/form/saveForm",
    "controls": [
        {
            "type": "select",
            "label": "选项",
            "name": "select",
            "autoFill": {
                "option": "${label}"
            },
            "options": [
                {
                    "label": "Option A",
                    "value": "a"
                },
                {
                    "label": "Option B",
                    "value": "b"
                }
            ]
        },
        {
            "type": "text",
            "name": "option",
            "label": "选中项"
        }
    ]
}

上例中我们配置了"autoFill": {"option": "${label}"},表示将选中项中的label的值,自动填充到当前表单项中nameoption的文本框中。

支持该配置项的有ButtonGroup、List、NestedSelect、Picker、Radios、Select。

属性表

除了支持 普通表单项属性表 中的配置以外,还支持下面一些配置

属性名 类型 默认值 说明
options Array<object>Array<string> 选项组,供用户选择
source API数据映射 选项组源,可通过数据映射获取当前数据域变量、或者配置 API 对象
multiple boolean false 是否支持多选
labelField boolean "label" 标识选项中哪个字段是label
valueField boolean "value" 标识选项中哪个字段是value
joinValues boolean true 是否拼接value
extractValue boolean false 是否将value值抽取出来组成新的数组,只有在joinValuesfalse是生效