树表组件 2.8+

树表组件 treeTable 是基于 table 组件延伸的树形表格组件,支持常见的树组件功能。
注意:该组件不支持 IE8,若要支持,可自行添加 polyfill实现兼容。

示例

以下所有示例中演示的数据均为「静态模拟数据」,实际使用时换成您的真实接口即可。

综合演示

  

API

table 组件的所有 API 均适用于 treeTable 组件。在此基础上,treeTable 还专门提供了以下方法:

API 描述
var treeTable = layui.treeTable; 获得 treeTable 模块。
treeTable.render(options) treeTable 组件渲染,核心方法。
treeTable.reload(id, options) 树表完整重载。
treeTable.reloadData(id, options) 树表数据重载。
treeTable.reloadAsyncNode(id, index) 重载异步子节点
treeTable.getData(id, isSimpleData) 获取树表数据。
treeTable.getNodeById(id, dataId) 获取节点信息集
treeTable.getNodesByFilter(id, filter, opts) 获取符合过滤规则的节点信息集
treeTable.getNodeDataByIndex(id, index) 通过行元素对应的 data-index 属性获取对应行数据。
treeTable.updateNode(id, index, data) 更新行数据。
treeTable.removeNode(id, index) 删除行记录。
treeTable.addNodes(id, opts) 新增行记录。
treeTable.expandNode(id, opts) 展开或关闭节点。
treeTable.expandAll(id, expandFlag) 展开或关闭全部节点。
treeTable.setRowChecked(id, opts) 设置行选中状态
treeTable.checkAllNodes(id, checked) 全选或取消全选
treeTable.on('event(filter)', callback) treeTable 相关事件

渲染

treeTable.render(options);

该组件渲染的使用方式与 table 组件完全相同。

属性

table 组件的所有基础属性均适用于 treeTable 组件。在此基础上,treeTable 还专门提供了 tree 属性集:

属性名 描述
tree

treeTable 组件的特定属性集,包含以下「子成员集」:

属性 描述
customName 自定义属性名的集合
view 视图相关的属性集合
data 数据相关的属性集合
async 异步相关的属性集合
callback 事件回调相关的属性集合

用法如下:

treeTable.render({
  elem: '',
  tree: { // treeTable 特定属性集
    customName: {},
    data: {},
    view: {},
    async: {},
    callback: {}
  },
  // 其他 table 属性
});
tree.customName

自定义属性名的集合,包含以下成员:

属性 描述 类型 默认值
children 自定义「子节点集合」的属性名 string children
isParent 自定义「是否属于父节点」的属性名 string isParent
name 自定义「节点」属性名 string name
id 自定义「节点索引」属性名 string id
pid 自定义「父节点索引」属性名 string parentId
icon 自定义图标的属性名称 string icon
tree.view

视图相关的属性集合,包含以下成员:

属性 描述 类型 默认值
indent 层级缩进量 number 14
flexIconClose 自定义关闭时的折叠按钮图标 string -
flexIconOpen 自定义打开时的折叠按钮图标 string -
showIcon 是否显示节点图标 boolean true
icon 自定义节点图标。若设置了该属性或数据中有该字段信息,不管打开还是关闭都以这个图标的值为准 string -
iconClose 自定义关闭时的节点图标 string -
iconOpen 自定义打开时的节点图标 string -
iconLeaf 自定义叶子节点的图标 string -
showFlexIconIfNotParent 若非父节点时,是否显示折叠图标 boolean false
dblClickExpand 双击节点时,是否自动展开父节点 boolean true
expandAllDefault 2.8.7+ 是否默认展开全部节点 boolean false

自定义图标支持 HTML 字符串和图标类名。例如:

  • '<i class="i-svg-spinners-blocks-wave"></i>'
  • 'layui-icon layui-icon-addition'
tree.data

数据相关的属性集合,包含以下成员:

属性 描述 类型 默认值
isSimpleData 是否使用平铺数据格式(Array) boolean false
rootPid 用于设置根节点的 pid 属性值 string null
cascade 用于设置复选的级联方式。支持以下可选值:
  • all : 所有节点联动
  • parent : 仅对父节点联动
  • children : 仅对子节点联动
  • none 2.8.16+ : 不做任何联动
string all
tree.async

异步相关的属性集合,包含以下成员:

属性 描述 类型 默认值
enable 是否开启异步加载模式。只有开启时 async 的其他属性配置才有效。 注意: 异步加载子节点不应跟 simpleData 同时开启,可以是 url+simpleData 的方式,获取完整的简单数据进行转换。若开启异步加载模式,即表示按需异步加载子节点。 boolean false
url 异步加载的接口,可以根据需要设置与顶层接口不同的接口,若相同可不设置该属性 string -
format 用于处理异步子节点数据的回调函数,该属性优先级高于 async.url 属性。用法详见下文。 function -
type 请求的接口类型,设置可缺省同上 string -
contentType 提交参数的数据类型,设置可缺省同上 string -
headers 提交请求头,设置可缺省同上 object -
where 提交参数的数据,设置可缺省同上 object -
autoParam 自动参数,可以根据配置项以及当前节点的数据传参,如: ['type', 'age=age', 'parentId=id'] ,那么其请求参数将包含: {type: '父节点 type', age: '父节点 age', parentId: '父节点 id'} array -

format 示例

treeTable.render({
  elem: '',
  tree: {
    enable: true,
    async: {
      format: function(trData, options, callback){
        // trData 为行数据、options 为 treeTable 属性配置项
        // callbacck 为子节点的渲染函数
        // 可利用该函数对子节点数据进行异步请求或其他格式化处理
        var nodeList = [
          {id: 111, name: '子节点1'},
          {id: 333, name: '子节点3'}
        ];
        callback(nodeList);
      }
    }
  }
})
tree.callback

事件回调相关的属性集合,包含以下成员:

属性 描述
beforeExpand 展开前回调函数。可以在展开或者关闭之前调用,传入当前表格 id ,当前操作的行数据以及要展开或关闭的状态,若回调返回 false 则取消该次操作。 返回的参数包含: function(tableId, trData, expandFlag){ console.log(arguments); }
onExpand 展开或关闭后的回调函数,返回参数同 beforeExpand

重载

即对一段已经渲染好的表格重新设置属性并渲染,可分为以下几种重载方式:

重载方式 API
完整重载 treeTable.reload(id, options)
仅数据重载 treeTable.reloadData(id, options)
  • 参数 id : treeTable 渲染时的 id 属性值
  • 参数 options : 基础属性配置项。#详见属性

使用方式与 table 组件完全相同,具体用法可参考:table 重载

重载异步子节点

treeTable.reloadAsyncNode(id, index)

  • 参数 id : treeTable 渲染时的 id 属性值
  • 参数 index : 节点对应的行下标,一般可通过 <tr> 元素的 data-index 属性获得

该方法用于在异步模式下,对节点进行重载。

// 渲染
treeTable.render({
  elem: '', // 绑定元素选择器
  id: 'test', // 自定义 id 索引
  async: {
    enable: true // 开启异步加载模式
  }
  // 其他属性 …
});
// 重载子节点
treeTable.reloadAsyncNode('test', 0); // 第一行

获取树表数据

treeTable.getData(id, isSimpleData);

  • 参数 id : treeTable 渲染时的 id 属性值
  • 参数 isSimpleData : 是否为简单数据,为 true 时返回简单数据结构的数据,否则则为带层级的数据

该方法用于获取表格当前页的全部数据,它对应的是接口返回的原始数据,不包含 treeTable 组件内部的特定字段。

// 渲染
treeTable.render({
  elem: '', // 绑定元素选择器
  id: 'test', // 自定义 id 索引
  // 其他属性 …
});
// 获取当前页接口的树表数据
var data = treeTable.getData('test'); // 获取第一行的数据
console.log(data);

获取节点信息集

treeTable.getNodeById(id, dataId)

  • 参数 id : treeTable 渲染时的 id 属性值
  • 参数 dataId : 数据项的 id 属性值
// 渲染
treeTable.render({
  elem: '', // 绑定元素选择器
  id: 'test', // 自定义 id 索引
  // 其他属性 …
});
// 获取节点信息集
var obj = treeTable.getNodeById('test', 1);
console.log(obj);

获取符合过滤规则的节点信息集

treeTable.getNodesByFilter(id, filter, opts)

  • 参数 id : treeTable 渲染时的 id 属性值
  • 参数 filter : 过滤函数
  • 参数 opts : 该方法的属性可选项,详见下表:
属性名 描述 类型 默认值
isSingle 是否只找到第一个 boolean false
parentNode 在指定在某个父节点下的子节点中搜索 object -
// 渲染
treeTable.render({
  elem: '', // 绑定元素选择器
  id: 'test', // 自定义 id 索引
  // 其他属性 …
});
// 获取节点信息集
var obj = treeTable.getNodesByFilter('test', function(item){
  // 自定义过滤条件
  return item.id > 1000;
});
console.log(obj);

获取树表对应下标的数据

treeTable.getNodeDataByIndex(id, index);

  • 参数 id : treeTable 渲染时的 id 属性值
  • 参数 index : 节点对应的行下标,一般可通过 <tr> 元素的 data-index 属性获得

该方法用于获取表格当前页对应下表的数据,返回的数据格式同 treeTable.getData() 方法。

// 渲染
treeTable.render({
  elem: '', // 绑定元素选择器
  id: 'test', // 自定义 id 索引
  // 其他属性 …
});
// 获取树表对应下标的数据
var obj = treeTable.getNodeDataByIndex('test', 0); // 获取第一行的数据
console.log(obj);

更新行数据

treeTable.updateNode(id, index, data);

  • 参数 id : treeTable 渲染时的 id 属性值
  • 参数 index : 节点对应的行下标,一般可通过 <tr> 元素的 data-index 属性获得
  • 参数 data : 更新的数据项,可包含要更新的各种字段
// 渲染
treeTable.render({
  elem: '', // 绑定元素选择器
  id: 'test', // 自定义 id 索引
  // 其他属性 …
});
// 更新行数据
var data = treeTable.updateNode('test', 0, {  // 更新第一行的数据
  title: '123'
});

删除行记录

treeTable.removeNode(id, index);

  • 参数 id : treeTable 渲染时的 id 属性值
  • 参数 index/node : 要删除的节点数据,也可以是节点对应的行下标( data-index
// 渲染
treeTable.render({
  elem: '', // 绑定元素选择器
  id: 'test', // 自定义 id 索引
  // 其他属性 …
});
// 删除行记录
treeTable.removeNode('test', 0); // 删除第一行

新增行数据

treeTable.addNodes(id, opts);

  • 参数 id : treeTable 渲染时的 id 属性值
  • 参数 opts : 该方法可支持的可选属性项,详见下表:
opts 描述 类型 默认值
parentIndex 父节点数据下标 number -
index 节点对应的行下标。若为 -1 表示插入到最后,否则则插入到对应下标。 number -1
data 新增的节点数据项。若新增的是多个节点,则用数组的形式。若只有一个节点可以是普通对象形式 object -
focus 是否聚焦到新增的节点。若存在多个,则聚焦到第一个新增的节点 boolean false

该方法可返回新增后的数据项。详细用法可参考:#示例

// 渲染
treeTable.render({
  elem: '', // 绑定元素选择器
  id: 'test', // 自定义 id 索引
  // 其他属性 …
});
// 新增行数据
treeTable.addNodes('test', {
  parentIndex: 0, // 一般在 tool 事件中,可通过对应数据项中的 `LAY_DATA_INDEX` 特定属性获得
  index: 1,
  data: {
    title: '新节点-1'
  }
});

展开或关闭节点

treeTable.expandNode(id, opts);

  • 参数 id : treeTable 渲染时的 id 属性值
  • 参数 opts : 该方法可支持的可选属性项,详见下表:
opts 描述 类型 默认值
index 节点对应的行下标,一般可通过 <tr> 元素的 data-index 属性获得 number -
expandFlag 设置展开或关闭状态,若为 true 则表示展开;false 则为关闭;null 则表示切换 boolean/null -
inherit 子节点是否继承父节点的展开或关闭状态,expandFlag 属性必须为 boolean 型时才有效。 boolean false
callbackFlag 是否触发事件(beforeExpand,onExpand boolean false

若操作的节点不是一个父节点,则返回 null,否则返回操作之后的折叠状态。

// 渲染
treeTable.render({
  elem: '', // 绑定元素选择器
  id: 'test', // 自定义 id 索引
  // 其他属性 …
});
// 展开或关闭对应节点
treeTable.expandNode('test', {
  index: 0, // 第一行
  expandFlag: true // 展开
});

展开或关闭全部节点

treeTable.expandAll(id, expandFlag);

  • 参数 id : treeTable 渲染时的 id 属性值
  • 参数 expandFlag : 折叠状态。 true 展开;false 关闭
// 渲染
treeTable.render({
  elem: '', // 绑定元素选择器
  id: 'test', // 自定义 id 索引
  // 其他属性 …
});
// 展开或关闭全部节点
treeTable.expandAll('test', false); // 关闭全部节点

设置行选中状态

treeTable.setRowChecked(id, opts);

  • 参数 id : treeTable 渲染时的 id 属性值
  • 参数 opts : 该方法可支持的可选属性项,详见下表:
opts 描述 类型 默认值
index 要设置选中状态的行下标或行数据 number/object -
checked 选中状态。true 选中;false 取消选中;null 切换。 其中,若为 radio 框,则不支持 null(切换)。 boolean -
callbackFlag 是否触发事件,若为 true,则 checked: false 无效。其对应的事件跟 tableradio,checkbox 事件用法一样 boolean false
// 渲染
treeTable.render({
  elem: '', // 绑定元素选择器
  id: 'test', // 自定义 id 索引
  // 其他属性 …
});
// 勾选或取消勾选单个节点
treeTable.setRowChecked('test', {
  index: 0,
  checked: true // 选中
}); 

设置全选或取消全选

treeTable.checkAllNodes(id, checked);

  • 参数 id : treeTable 渲染时的 id 属性值
  • 参数 checked : 选中状态。true 选中;false 取消选中;null 复选框模式时的切换。
// 渲染
treeTable.render({
  elem: '', // 绑定元素选择器
  id: 'test', // 自定义 id 索引
  // 其他属性 …
});
// 勾选或取消勾选单个节点
treeTable.checkAllNodes('test', true);  // 全选 

事件

treeTable.on('event(filter)', callback);

treeTable 事件继承于 table 事件,具体使用方法可参考:#table 事件

贴士

treeTable 基于 table 组件扩展而来,因此,熟练运用 treeTable 的前提是熟悉 table 组件。 亦可通过 table 提供的基础 API 操作 treeTable 组件,但 treeTable 无法操作 table