amis2/docs/zh-CN/components/form/nestedselect.md

19 KiB
Executable File

title description type group menuName icon order
NestedSelect 级联选择器 0 null NestedSelect 级联选择器 31

基本用法

{
  "type": "form",
  "debug": true,
  "api": "/api/mock2/form/saveForm",
  "body": [
    {
      "type": "nested-select",
      "name": "nestedSelect",
      "label": "级联选择器",
      "options": [
        {
          "label": "A",
          "value": "a"
        },
        {
          "label": "B",
          "value": "b",
          "children": [
            {
              "label": "B-1",
              "value": "b-1"
            },
            {
              "label": "B-2",
              "value": "b-2"
            },
            {
              "label": "B-3",
              "value": "b-3"
            }
          ]
        },
        {
          "label": "C",
          "value": "c"
        }
      ]
    }
  ]
}

动态选项

通过 source 可以从上下文或 api 中获取选项信息,比如

{
  "type": "page",
  "data": {
    "options": [
        {
          "label": "A",
          "value": "a"
        },
        {
          "label": "B",
          "value": "b",
          "children": [
            {
              "label": "B-1",
              "value": "b-1"
            },
            {
              "label": "B-2",
              "value": "b-2"
            },
            {
              "label": "B-3",
              "value": "b-3"
            }
          ]
        },
        {
          "label": "C",
          "value": "c"
        }
      ]
  },
  "body": {
    "type": "form",
    "debug": true,
    "api": "/api/mock2/form/saveForm",
    "body": [
      {
        "type": "nested-select",
        "name": "nestedSelect",
        "label": "级联选择器",
        "source": "${options}"
      }
    ]
  }
}

也可以是 api 地址

{
  "type": "page",
  "body": {
    "type": "form",
    "debug": true,
    "api": "/api/mock2/form/saveForm",
    "body": [
      {
        "type": "nested-select",
        "name": "nestedSelect",
        "label": "级联选择器",
        "source": "/api/mock2/form/getTreeOptions"
      }
    ]
  }
}

只允许选中叶子节点

1.8.0 及以上版本,如果是之前版本可以在对应的节点上不设置 value 实现

在单选时,可以通过 onlyLeaf 来设置只允许选择叶子节点,即便分支节点有 value 也不会被选中。

{
  "type": "form",
  "debug": true,
  "api": "/api/mock2/form/saveForm",
  "body": [
    {
      "type": "nested-select",
      "name": "nestedSelect",
      "label": "级联选择器",
      "onlyLeaf": true,
      "options": [
        {
          "label": "A",
          "value": "a"
        },
        {
          "label": "B",
          "value": "b",
          "children": [
            {
              "label": "B-1",
              "value": "b-1"
            },
            {
              "label": "B-2",
              "value": "b-2"
            },
            {
              "label": "B-3",
              "value": "b-3"
            }
          ]
        },
        {
          "label": "C",
          "value": "c"
        }
      ]
    }
  ]
}

在多选时,也可以通过 onlyLeaf 并且搭配 cascade 来设置只允许选择叶子节点,即便分支节点有 value 也不会有选中动作,

{
  "type": "form",
  "debug": true,
  "api": "/api/mock2/form/saveForm",
  "body": [
    {
      "type": "nested-select",
      "name": "nestedSelect",
      "label": "级联选择器",
      "onlyLeaf": true,
      "cascade": true,
      "multiple": true,
      "options": [
        {
          "label": "A",
          "value": "a"
        },
        {
          "label": "B",
          "value": "b",
          "children": [
            {
              "label": "B-1",
              "value": "b-1"
            },
            {
              "label": "B-2",
              "value": "b-2"
            },
            {
              "label": "B-3",
              "value": "b-3"
            }
          ]
        },
        {
          "label": "C",
          "value": "c"
        }
      ]
    }
  ]
}

选中父节点是否自动选中子节点

默认选中父节点会自动选中子节点,可以设置"cascade": true,不自动选中子节点

{
  "type": "form",
  "debug": true,
  "api": "/api/mock2/form/saveForm",
  "body": [
    {
      "type": "nested-select",
      "name": "nestedSelect1",
      "label": "默认自动选中子节点",
      "multiple": true,
      "options": [
        {
          "label": "A",
          "value": "a"
        },
        {
          "label": "B",
          "value": "b",
          "children": [
            {
              "label": "B-1",
              "value": "b-1"
            },
            {
              "label": "B-2",
              "value": "b-2"
            },
            {
              "label": "B-3",
              "value": "b-3"
            }
          ]
        },
        {
          "label": "C",
          "value": "c"
        }
      ]
    },
    {
        "type": "divider"
    },
    {
      "type": "nested-select",
      "name": "nestedSelect2",
      "label": "不自动选中子节点",
      "multiple": true,
      "cascade": true,
      "options": [
        {
          "label": "A",
          "value": "a"
        },
        {
          "label": "B",
          "value": "b",
          "children": [
            {
              "label": "B-1",
              "value": "b-1"
            },
            {
              "label": "B-2",
              "value": "b-2"
            },
            {
              "label": "B-3",
              "value": "b-3"
            }
          ]
        },
        {
          "label": "C",
          "value": "c"
        }
      ]
    }
  ]
}

选中父节点,值是否包含子节点

默认选中父节点,是不会带上子节点的值,想要自动带上子节点的值,那么配置"withChildren": true

{
  "type": "form",
  "debug": true,
  "api": "/api/mock2/form/saveForm",
  "body": [
    {
      "type": "nested-select",
      "name": "nestedSelect1",
      "label": "默认不自动带上子节点的值",
      "multiple": true,
      "options": [
        {
          "label": "A",
          "value": "a"
        },
        {
          "label": "B",
          "value": "b",
          "children": [
            {
              "label": "B-1",
              "value": "b-1"
            },
            {
              "label": "B-2",
              "value": "b-2"
            },
            {
              "label": "B-3",
              "value": "b-3"
            }
          ]
        },
        {
          "label": "C",
          "value": "c"
        }
      ]
    },
    {
        "type": "divider"
    },
     {
      "type": "nested-select",
      "name": "nestedSelect2",
      "label": "自动带上子节点的值",
      "multiple": true,
      "withChildren": true,
      "options": [
        {
          "label": "A",
          "value": "a"
        },
        {
          "label": "B",
          "value": "b",
          "children": [
            {
              "label": "B-1",
              "value": "b-1"
            },
            {
              "label": "B-2",
              "value": "b-2"
            },
            {
              "label": "B-3",
              "value": "b-3"
            }
          ]
        },
        {
          "label": "C",
          "value": "c"
        }
      ]
    }
  ]
}

也可以设置onlyChildren,实现只包含子节点的值

{
  "type": "form",
  "debug": true,
  "api": "/api/mock2/form/saveForm",
  "body": [
    {
      "type": "nested-select",
      "name": "nestedSelect1",
      "label": "默认不自动带上子节点的值",
      "multiple": true,
      "options": [
        {
          "label": "A",
          "value": "a"
        },
        {
          "label": "B",
          "value": "b",
          "children": [
            {
              "label": "B-1",
              "value": "b-1",
              "children": [
                {
                  "label": "D-1",
                  "value": "d-1"
                },
                {
                  "label": "D-2",
                  "value": "d-2"
                },
                {
                  "label": "D-3",
                  "value": "d-3"
                }
              ]
            },
            {
              "label": "B-2",
              "value": "b-2"
            },
            {
              "label": "B-3",
              "value": "b-3"
            }
          ]
        },
        {
          "label": "C",
          "value": "c"
        }
      ]
    },
    {
        "type": "divider"
    },
     {
      "type": "nested-select",
      "name": "nestedSelect2",
      "label": "只包含子节点的值",
      "multiple": true,
      "onlyChildren": true,
      "clearable": true,
      "options": [
        {
          "label": "A",
          "value": "a"
        },
        {
          "label": "B",
          "value": "b",
          "children": [
            {
              "label": "B-1",
              "value": "b-1",
              "children": [
                {
                  "label": "D-1",
                  "value": "d-1"
                },
                {
                  "label": "D-2",
                  "value": "d-2"
                },
                {
                  "label": "D-3",
                  "value": "d-3"
                }
              ]
            },
            {
              "label": "B-2",
              "value": "b-2"
            },
            {
              "label": "B-3",
              "value": "b-3"
            }
          ]
        },
        {
          "label": "C",
          "value": "c"
        }
      ]
    }
  ]
}

仅展示选中节点文本信息

设置hideNodePathLabel: true,可以隐藏选择框中已选择节点的祖先节点(ancestor)的labelField字段值,仅展示当前选中节点的labelField字段值。

{
  "type": "form",
  "debug": true,
  "api": "/api/mock2/form/saveForm",
  "body": [
    {
      "type": "nested-select",
      "name": "nestedSelect",
      "label": "展示已选择节点的祖先节点的文本信息",
      "value": "a,b-1,b-3",
      "multiple": true,
      "options": [
        {
          "label": "A",
          "value": "a"
        },
        {
          "label": "B",
          "value": "b",
          "children": [
            {
              "label": "B-1",
              "value": "b-1"
            },
            {
              "label": "B-2",
              "value": "b-2"
            },
            {
              "label": "B-3",
              "value": "b-3"
            }
          ]
        },
        {
          "label": "C",
          "value": "c"
        }
      ],
    },
    {
      "type": "divider"
    },
    {
      "type": "nested-select",
      "name": "nestedSelect2",
      "label": "仅展示已选择节点的文本信息",
      "value": "a,b-1,b-3",
      "multiple": true,
      "cascade": true,
      "hideNodePathLabel": true,
      "options": [
        {
          "label": "A",
          "value": "a"
        },
        {
          "label": "B",
          "value": "b",
          "children": [
            {
              "label": "B-1",
              "value": "b-1"
            },
            {
              "label": "B-2",
              "value": "b-2"
            },
            {
              "label": "B-3",
              "value": "b-3"
            }
          ]
        },
        {
          "label": "C",
          "value": "c"
        }
      ]
    }
  ]
}

选项搜索

配置"searchable": true后,输入框内输入内容时,下拉数据源会进行前端过滤,过滤的关键字段默认为valuelabel。如果通过valueFieldlabelField属性,则会选择对应的字段进行过滤。

{
  type: 'form',
  api: '/api/mock2/form/saveForm',
  body: [
    {
      type: 'nested-select',
      name: 'nestedSelect1',
      label: '级联选择器(单选)',
      options: [
        {
          label: 'A',
          value: 'a'
        },
        {
          label: 'B',
          value: 'b',
          children: [
            {
              label: 'B-1',
              value: 'b1'
            },
            {
              label: 'B-2',
              value: 'b2'
            },
            {
              label: 'B-3',
              value: 'b3'
            }
          ]
        },
        {
          label: 'C',
          value: 'c'
        }
      ],
      searchable: true,
      multiple: false,
      joinValues: true,
      clearable: true
    },
    {
      type: 'nested-select',
      name: 'nestedSelect2',
      label: '级联选择器(多选)',
      options: [
        {
          label: 'A',
          value: 'a'
        },
        {
          label: 'B',
          value: 'b',
          children: [
            {
              label: 'B-1',
              value: 'b1'
            },
            {
              label: 'B-2',
              value: 'b2'
            },
            {
              label: 'B-3',
              value: 'b3'
            }
          ]
        },
        {
          label: 'C',
          value: 'c'
        }
      ],
      searchable: true,
      multiple: false,
      joinValues: true,
      clearable: true
    }
  ]
}

属性表

当做选择器表单项使用时,除了支持 普通表单项属性表 中的配置以外,还支持下面一些配置

属性名 类型 默认值 说明
options Array<object>Array<string> 选项组
source stringAPI 动态选项组
delimiter boolean false 拼接符
labelField boolean "label" 选项标签字段
valueField boolean "value" 选项值字段
joinValues boolean true 拼接值
extractValue boolean false 提取值
autoFill object 自动填充
cascade boolean false 设置 true时,当选中父节点时不自动选择子节点。
withChildren boolean false 设置 true时,选中父节点时,值里面将包含子节点的值,否则只会保留父节点的值。
onlyChildren boolean false 多选时,选中父节点时,是否只将其子节点加入到值中。
searchable boolean false 可否搜索
searchPromptText string "输入内容进行检索" 搜索框占位文本
noResultsText string "未找到任何结果" 无结果时的文本
multiple boolean false 可否多选
hideNodePathLabel boolean false 是否隐藏选择框中已选择节点的路径 label 信息
onlyLeaf boolean false 只允许选择叶子节点

事件表

当前组件会对外派发以下事件,可以通过onEvent来监听这些事件,并通过actions来配置执行的动作,在actions中可以通过${事件参数名}来获取事件产生的数据(< 2.3.2 及以下版本 为 ${event.data.[事件参数名]}),详细请查看事件动作

[name]表示当前组件绑定的名称,即name属性,如果没有配置name属性,则通过value取值。

事件名称 事件参数 说明
change [name]: string 组件的值 选中值变化时触发
blur [name]: string 组件的值 输入框失去焦点时触发
focus [name]: string 组件的值 输入框获取焦点时触发

动作表

当前组件对外暴露以下特性动作,其他组件可以通过指定actionType: 动作名称componentId: 该组件id来触发这些动作,动作配置可以通过args: {动作配置项名称: xxx}来配置具体的参数,详细请查看事件动作

动作名称 动作配置 说明
clear - 清空
reset - 将值重置为resetValue,若没有配置resetValue,则清空
reload - 重新加载,调用 source,刷新数据域数据刷新(重新加载)
setValue value: string 更新的值 更新数据,开启multiple时,多个值用,分隔