amis2/docs/zh-CN/components/form/input-tree.md
hsm-lv 4acfbb99ce
feat:优化动作数据域 (#5544)
* feat:优化事件数据域

* feat:优化事件数据域

* feat:优化事件数据域(option->item,options->items)

* feat:优化事件数据域(version)

* feat:优化事件数据域(修复弹窗事件多次触发&并行数据获取问题)

* feat:优化事件数据域(删除多余代码)

* feat:优化事件数据域(更新文档)

* feat:优化事件数据域(更新文档)

* feat:优化动作数据域

* feat:优化动作数据域
2022-10-12 15:09:03 +08:00

32 KiB
Executable File
Raw Blame History

title description type group menuName icon order
InputTree 树形选择框 0 null InpputTree 树形选择框 59

基本使用

配置的options中,可以通过children字段进行嵌套展示,实现树形选择器

{
  "type": "form",
  "api": "/api/mock2/form/saveForm",
  "body": [
    {
      "type": "input-tree",
      "name": "tree",
      "label": "Tree",
      "options": [
        {
          "label": "Folder A",
          "value": 1,
          "children": [
            {
              "label": "file A",
              "value": 2
            },
            {
              "label": "Folder B",
              "value": 3,
              "children": [
                {
                  "label": "file b1",
                  "value": 3.1
                },
                {
                  "label": "file b2",
                  "value": 3.2
                }
              ]
            }
          ]
        },
        {
          "label": "file C",
          "value": 4
        },
        {
          "label": "file D",
          "value": 5
        }
      ]
    }
  ]
}

选择器样式

配置"type": "tree-select"可以实现选择器样式

{
  "type": "form",
  "api": "/api/mock2/form/saveForm",
  "body": [
    {
      "type": "tree-select",
      "name": "tree",
      "label": "Tree",
      "options": [
        {
          "label": "Folder A",
          "value": 1,
          "children": [
            {
              "label": "file A",
              "value": 2
            },
            {
              "label": "file B",
              "value": 3
            }
          ]
        },
        {
          "label": "file C",
          "value": 4
        },
        {
          "label": "file D",
          "value": 5
        }
      ]
    }
  ]
}

是否显示展开线

1.1.6 版本

通过 showOutline 来控制是否显示展开线。

{
  "type": "form",
  "api": "/api/mock2/form/saveForm",
  "body": [
    {
      "type": "input-tree",
      "name": "tree",
      "label": "Tree",
      "showOutline": true,
      "options": [
        {
          "label": "Folder A",
          "value": 1,
          "children": [
            {
              "label": "file A",
              "value": 2
            },
            {
              "label": "Folder B",
              "value": 3,
              "children": [
                {
                  "label": "file b1",
                  "value": 3.1
                },
                {
                  "label": "file b2",
                  "value": 3.2
                }
              ]
            }
          ]
        },
        {
          "label": "file C",
          "value": 4
        },
        {
          "label": "file D",
          "value": 5
        }
      ]
    }
  ]
}

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

since 1.9.0

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

{
  "type": "form",
  "debug": true,
  "api": "/api/mock2/form/saveForm",
  "body": [
    {
      "type": "input-tree",
      "name": "tree1",
      "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": "input-tree",
      "name": "tree2",
      "label": "不自动选中子节点",
      "multiple": true,
      "autoCheckChildren": false,
      "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默认为 false子节点禁止反选值不包含子节点值配置"cascade": true子节点可以反选值包含父子节点值1.9.0 之前的版本 cascade 配置为 true 的效果为:选中父节点不默认选中子节点)

{
  "type": "form",
  "debug": true,
  "api": "/api/mock2/form/saveForm",
  "body": [
    {
      "type": "input-tree",
      "name": "tree1",
      "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": "input-tree",
      "name": "tree2",
      "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默认为 false子节点禁止反选值包含父子节点值配置withChildren": true,子节点禁止反选,值包含父子节点值

{
  "type": "form",
  "debug": true,
  "api": "/api/mock2/form/saveForm",
  "body": [
    {
      "type": "input-tree",
      "name": "tree1",
      "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": "input-tree",
      "name": "tree2",
      "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": "input-tree",
      "name": "tree1",
      "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": "input-tree",
      "name": "tree2",
      "label": "只包含子节点的值",
      "multiple": true,
      "onlyChildren": 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"
        }
      ]
    }
  ]
}

只允许选择叶子节点

1.10.0 及以上版本

在单选时,可通过 onlyLeaf 可以配置只允许选择叶子节点

{
  "type": "form",
  "api": "/api/mock2/form/saveForm",
  "body": [
    {
      "type": "input-tree",
      "name": "tree",
      "label": "Tree",
      "onlyLeaf": true,
      "searchable": true,
      "options": [
        {
          "label": "Folder A",
          "value": 1,
          "children": [
            {
              "label": "file A",
              "value": 2
            },
            {
              "label": "file B",
              "value": 3
            }
          ]
        },
        {
          "label": "file C",
          "value": 4
        },
        {
          "label": "file D",
          "value": 5
        },
        {
          "label": "Folder E",
          "value": "61",
          "children": [
            {
              "label": "Folder G",
              "value": "62",
              "children": [
                {
                  "label": "file H",
                  "value": 6
                },
                {
                  "label": "file I",
                  "value": 7
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}

默认展开

默认是展开所有子节点的,如果不想默认展开,则配置"initiallyOpen": false

{
  "type": "form",
  "debug": true,
  "api": "/api/mock2/form/saveForm",
  "body": [
    {
      "type": "input-tree",
      "name": "tree1",
      "label": "默认不自动带上子节点的值",
      "initiallyOpen": false,
      "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"
        }
      ]
    }
  ]
}

如果层级较多,也可以配置unfoldedLevel指定展开的层级数,默认展开第 1 层

下例中设置"unfoldedLevel": 2,表示展开第 2 层

{
  "type": "form",
  "debug": true,
  "api": "/api/mock2/form/saveForm",
  "body": [
    {
      "type": "input-tree",
      "name": "tree1",
      "label": "默认不自动带上子节点的值",
      "initiallyOpen": false,
      "unfoldedLevel": 2,
      "options": [
        {
          "label": "A",
          "value": "a"
        },
        {
          "label": "B",
          "value": "b",
          "children": [
            {
              "label": "B-1",
              "value": "b-1"
            },
            {
              "label": "B-2",
              "value": "b-2",
              "children": [
                {
                    "label": "B-2-1",
                    "value": "b-2-1"
                },
                {
                    "label": "B-2-2",
                    "value": "b-2-2"
                },
                {
                    "label": "B-2-3",
                    "value": "b-2-3"
                }
            ]
            },
            {
              "label": "B-3",
              "value": "b-3"
            }
          ]
        },
        {
          "label": "C",
          "value": "c"
        }
      ]
    }
  ]
}

可编辑

配置 creatableremovableeditable 可以实现树可编辑。

{
  "type": "form",
  "api": "/api/mock2/form/saveForm",
  "body": [
    {
      "type": "input-tree",
      "name": "tree",
      "label": "Tree",
      "creatable": true,
      "removable": true,
      "editable": true,
      "options": [
        {
          "label": "Folder A",
          "value": 1,
          "children": [
            {
              "label": "file A",
              "value": 2
            },
            {
              "label": "file B",
              "value": 3
            }
          ]
        },
        {
          "label": "file C",
          "value": 4
        },
        {
          "label": "file D",
          "value": 5
        }
      ]
    }
  ]
}

控制哪些项可编辑

配置 creatableremovableeditable 可以实现树可编辑,同时如果需要关闭部分节点的编辑权限,可以在节点上配置creatableremovableeditable

rootCreatable 可以用来关闭顶层是否可以创建。如果想要控制顶层可编辑,请配置 hideRoot,用节点来控制。

{
  "type": "form",
  "api": "/api/mock2/form/saveForm",
  "body": [
    {
      "type": "input-tree",
      "name": "tree",
      "label": "Tree",
      "creatable": true,
      "removable": true,
      "editable": true,
      "rootCreatable": false,
      "options": [
        {
          "label": "Folder A",
          "value": 1,
          "creatable": false,
          "removable": false,
          "editable": false,
          "children": [
            {
              "label": "file A",
              "value": 2
            },
            {
              "label": "file B",
              "value": 3
            }
          ]
        },
        {
          "label": "file C",
          "value": 4,
          "removable": false
        },
        {
          "label": "file D",
          "value": 5,
          "editable": false
        }
      ]
    }
  ]
}

控制添加/编辑的表单

配置 addControls 可以控制添加时需要填写哪些信息,同样还有 editControls 来配置编辑节点的表单

{
  "type": "form",
  "api": "/api/mock2/form/saveForm",
  "body": [
    {
      "type": "input-tree",
      "name": "tree",
      "label": "Tree",
      "creatable": true,
      "addControls": [
        {
          "label": "节点名称",
          "type": "input-text",
          "required": true,
          "name": "label"
        },
        {
          "label": "节点值",
          "type": "input-text",
          "required": true,
          "name": "value"
        }
      ],
      "options": [
        {
          "label": "Folder A",
          "value": 1,
          "children": [
            {
              "label": "file A",
              "value": 2
            },
            {
              "label": "file B",
              "value": 3
            }
          ]
        },
        {
          "label": "file C",
          "value": 4
        },
        {
          "label": "file D",
          "value": 5
        }
      ]
    }
  ]
}

懒加载

since 1.1.6

需要懒加载的选项请配置 defer 为 true然后配置 deferApi 即可完成懒加载。如果不配置 deferApi 会使用 source 接口。 deferApi 中可以用到当前选项中的任何字段,比如以下这个例子是把 label 传给了 defer 接口

{
  "type": "form",
  "api": "/api/mock2/form/saveForm",
  "body": [
    {
      "type": "input-tree",
      "name": "tree",
      "label": "Tree",
      "deferApi": "/api/mock2/form/deferOptions?label=${label}&waitSeconds=2",
      "options": [
        {
          "label": "Folder A",
          "value": 1,
          "collapsed": true,
          "children": [
            {
              "label": "file A",
              "value": 2
            },
            {
              "label": "file B",
              "value": 3
            }
          ]
        },
        {
          "label": "这下面是懒加载的",
          "value": 4,
          "defer": true
        },
        {
          "label": "file D",
          "value": 5
        }
      ]
    }
  ]
}

节点路径模式

since 1.2.4

配置enableNodePath: true后, 可以将value格式转换成节点路径模式,pathSeparator设置路径分隔符,建议将该属性的值和拼接符delimiter区分开。节点路径模式下,value中所有节点的父节点都会自动加载数据并回显。不同配置属性的节点路径模式value如下:

    a
   / \
  b   d
 /
c
----------------------------------------------
multiple  joinValues  extractValue  value
----------------------------------------------
false       true           -        'a/b/c'
false       false        false      {label: 'A/B/C', value: 'a/b/c'}
true        true           -        'a/b/c,a/d'
true        false        true       ['a/b/c', 'a/d']
true        false        true       [{label: 'A/B/C', value: 'a/b/c'},{label: 'A/D', value: 'a/d'}]
{
  "type": "form",
  "api": "/api/mock2/form/saveForm",
  "body": [
    {
      "type": "input-tree",
      "name": "tree",
      "label": "Tree",
      "deferApi": "/api/mock2/form/deferOptions?label=${label}&waitSeconds=2",
      "value": "1/2,4/lazy-1/lazy-1-3,4/lazy-1/lazy-1-5",
      "enableNodePath": true,
      "pathSeparator": '/',
      "multiple": true,
      "options": [
        {
          "label": "Folder A",
          "value": 1,
          "collapsed": true,
          "children": [
            {
              "label": "file A",
              "value": 2
            },
            {
              "label": "file B",
              "value": 3
            }
          ]
        },
        {
          "label": "这下面是懒加载的",
          "value": 4,
          "defer": true
        },
        {
          "label": "file D",
          "value": 5
        }
      ]
    }
  ]
}

属性表

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

属性名 类型 默认值 说明
options Array<object>Array<string> 选项组
source stringAPI 动态选项组
autoComplete API 自动提示补全
multiple boolean false 是否多选
delimiter string false 拼接符
labelField string "label" 选项标签字段
valueField string "value" 选项值字段
iconField string "icon" 图标值字段
joinValues boolean true 拼接值
extractValue boolean false 提取值
creatable boolean false 新增选项
addControls Array<表单项> 自定义新增表单项
addApi API 配置新增选项接口
editable boolean false 编辑选项
editControls Array<表单项> 自定义编辑表单项
editApi API 配置编辑选项接口
removable boolean false 删除选项
deleteApi API 配置删除选项接口
searchable boolean false 是否可检索,仅在 type 为 tree-select 的时候生效
hideRoot boolean true 如果想要显示个顶级节点,请设置为 false
rootLabel boolean "顶级" hideRoot 不为 false 时有用,用来设置顶级节点的文字。
showIcon boolean true 是否显示图标
showRadio boolean false 是否显示单选按钮,multiplefalse 是有效。
showOutline boolean false 是否显示树层级展开线
initiallyOpen boolean true 设置是否默认展开所有层级。
unfoldedLevel number 1 设置默认展开的级数,只有initiallyOpen不是true时生效。
autoCheckChildren boolean true 当选中父节点时级联选择子节点。
cascade boolean false autoCheckChildren 为 true 时生效;默认行为:子节点禁用,值只包含父节点值;设置为 true 时,子节点可反选,值包含父子节点值。
withChildren boolean false cascade 为 false 时生效,选中父节点时,值里面将包含父子节点的值,否则只会保留父节点的值。
onlyChildren boolean false autoCheckChildren 为 true 时生效,不受 cascade 影响onlyChildren 为 trueui 行为级联选中子节点,子节点可反选,值只包含子节点的值。
onlyLeaf boolean false 只允许选择叶子节点
rootCreatable boolean false 是否可以创建顶级节点
rootCreateTip string "添加一级节点" 创建顶级节点的悬浮提示
minLength number 最少选中的节点数
maxLength number 最多选中的节点数
treeContainerClassName string tree 最外层容器类名
enableNodePath boolean false 是否开启节点路径模式
pathSeparator string / 节点路径的分隔符,enableNodePathtrue时生效
highlightTxt string 标签中需要高亮的字符,支持变量

事件表

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

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

事件名称 事件参数 说明
change [name]: string 组件的值 选中值变化时触发
add items: object[]选项集合(< 2.3.2 及以下版本 为options
[name]: object 新增的节点信息
新增节点提交时触发
edit items: object[]选项集合(< 2.3.2 及以下版本 为options
[name]: object 编辑的节点信息
编辑节点提交时触发
delete items: object[]选项集合(< 2.3.2 及以下版本 为options
[name]: object 删除的节点信息
删除节点提交时触发
loadFinished [name]: object deferApi 懒加载远程请求成功后返回的数据 懒加载接口远程请求成功时触发

动作表

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

动作名称 动作配置 说明
expand openLevel: number 展开指定层级
collapse - 收起
clear - 清空
reset - 将值重置为resetValue,若没有配置resetValue,则清空
setValue value: string | string[] 更新的值 更新数据,开启multiple支持设置多项,开启joinValues时,多值用,分隔,否则多值用数组