Layui快速入门之第八节 表格渲染与属性的使用

目录

一:表格的渲染

API

方法配置渲染

模板配置渲染

静态表格渲染

二:表格的属性 

基础属性

异步属性

返回数据中的特定字段

表头属性

重载

完整重载

仅数据重载 2.7+

获取选中行

设置行选中状态 2.8+

获取当前页接口数据

获取表格缓存数据集

重置尺寸

导出数据

获取配置项 2.8+

设置列显示或隐藏 2.8+


一:表格的渲染

API

API 描述
var table = layui.table 获得 table 模块。
table.render(options) table 组件渲染,核心方法。
table.init(filter, options) 初始化渲染静态表格。
table.reload(id, options, deep) 表格完整重载。
table.reloadData(id, options, deep) 2.7+ 表格数据重载。
table.checkStatus(id) 获取选中行相关数据。
table.setRowChecked(id, opts) 2.8+ 设置行选中状态。
table.getData(id) 获取当前页所有行表格数据。
table.cache 获取表格缓存数据集(包含特定字段)。
table.resize(id) 重置表格尺寸。
table.exportFile(id, data, opts) 导出表格数据到本地文件。
table.getOptions(id) 2.8+ 获取表格实例配置项。
table.hideCol(id, cols) 2.8+ 设置表格列的显示隐藏属性。
table.on('event(filter)', callback) table 相关事件。

渲染

table 提供了以下三种渲染模式,在实际使用时,一般按情况选择其中一种即可。

渲染方式 描述
方法配置渲染 通过 table 组件提供的核心方法 table.render(options) 完成的渲染。推荐
模板配置渲染 通过  标签的 lay-options="{}" 属性定义模板,组件自动对其进行解析并完成渲染。
静态表格渲染 对一段已经包含数据内容的静态表格进行动态化转换,使其具备 table 组件的相关功能。

方法配置渲染

table.render(options);

  • 参数 options : 基础属性配置项。#详见属性

该方法返回当前实例对象,包含可操作当前表格的一些成员方法。

模板配置渲染

在 

 元素中直接书写 lay-options="{}" 属性,组件将自动对其进行解析并完成渲染。


Title

2.8 之前版本通过 lay-data="{}" 定义属性配置项;
2.8+ 版本推荐采用 lay-options,但同时兼容 lay-data

静态表格渲染

table.init(filter, options);

  • 参数 filter :  元素对应的 lay-filter 属性值
  • 参数 options : 基础属性配置项。#详见属性
  • 该方法用于将已输出在页面中的静态表格内容转换为动态 table 组件

    表格内容

    二:表格的属性 

    属性是指 table 渲染、重载 时的配置选项(options),它本身是一个 object 参数。如: 

    // 渲染
    table.render({
      // options
      elem: '',
      cols: [[]],
      // …
    }); 
    // 重载
    table.reload(id, {
      // options
    });
           
    若为模板配置渲染,则 lay-options 或 lay-data 的属性值即为属性的配置选项(:
     … 

    table 的属性众多,我们大致分为以下几种:

    属性类别 描述
    基础属性 -
    异步属性 用于和异步数据请求相关的基础属性,由于相关属性成员较多,所以单独提取介绍。
    表头属性 基础属性 cols 的子属性集。

    基础属性

    属性名 描述 类型 默认值
    elem 绑定原始 table 元素,方法渲染方式必填。 string/DOM -

    url

    发送异步请求的 URL。更多异步相关属性见 : #异步属性

    - -

    cols

    表头属性集,通过二维数组定义多级表头。方法渲染时必填。 更多表头属性见 : #表头属性

    array -
    data

    直接赋值数据。既适用于只展示一页数据,也能对一段已知数据进行多页展示。该属性与 url 属性只能二选一。

    array -
    id

    设定实例唯一索引,以便用于其他方法对 table 实例进行相关操作。若该属性未设置,则默认从 elem 属性绑定的原始 table 元素中的 id 属性值中获取。

    string -
    toolbar

    开启表格头部工具栏。支持以下几种值写法:

    • toolbar: '#template-id' 自定义工具栏模板选择器
    • toolbar: '
      xxx
       直接传入模板字符
    • toolbar: true 仅开启工具栏右侧,不显示左侧模板
    • toolbar: 'default' 开启工具栏并显示默认模板
    string
    boolean

    false

    defaultToolbar

    设置头部工具栏右侧图标。值是一个数组,可选成员有: filter,exports,print (分别代表:筛选图标、导出图标、打印图标)。图标可根据数组值的顺序排列,如:defaultToolbar: ['filter','print','exports']
    支持自定义图标及事件,用法详见示例: #综合演示

    array -
    width 设置容器宽度,默认自适应。 number -

    height

    设置表格容器高度,默认自适应。其他可选值的规则如下:

    • height: 315 设置固定高度
    • height: 'full-30' 设置自适应高度。这是一个特定的语法格式:full 表示铺满;后面的数字表示当前 table 之外的元素占用的高度,如:表格头部到页面最顶部表格底部距离页面最底部的“距离和”
    • height: '#id-30' 设置相对父元素的高度自适应,其中 #id 即父元素的 ID 选择器,其计算原理和上述 full 相同。
    number
    string
    -
    maxHeight 2.8+

    设置表格容器的最大高度,设置该属性后,height 属性将被认定为默认的自适应值。

    number -
    cellMinWidth

    设置所有普通单元格的最小宽度,一般用于列宽自动分配的情况。其优先级低于表头属性中的 minWidth

    number

    60

    cellMaxWidth 2.8+

    设置所有普通单元格的最大宽度。其优先级低于表头属性中的 maxWidth

    number -
    lineStyle 2.7+

    用于定义表格的多行样式,如每行的高度等。该参数一旦设置,单元格将会开启多行模式,且鼠标 hover 时会通过显示滚动条的方式查看到更多内容。 请按实际场景使用。
    示例:lineStyle: 'height: 95px;'

    string -
    className 2.7+ 用于给表格主容器追加 css 类名,以便更好地扩展表格样式 string -
    css 2.7+

    用于给当前表格主容器直接设定 css 样式,样式值只会对所在容器有效,不会影响其他表格实例。如:css: '.layui-table-page{text-align: right;}'

    string -
    escape 2.6+ 是否开启对内容的编码(转义 html) boolean

    true

    totalRow 是否开启合计行区域 string

    false

    page

    用于开启分页。
    支持传入 laypage 组件的基础属性(jump,elem 除外)

    boolean
    object

    false

    pagebar 2.7+

    用于开启分页区域的自定义模板,用法同 toolbar 属性。

    string -
    limit

    每页显示的条数。值需对应 limits 参数的选项。优先级低于 page 属性中的 limit 属性。

    number

    10

    limits 每页条数的选择项。 array

    [10,…,90]

    loading

    是否显示加载条。若为 false,则在切换分页时,不会出现加载条。必须设置了 url 属性才生效。

    boolean

    true

    scrollPos 2.7+

    用于设置重载数据或切换分页时的滚动条位置状态。可选值:

    • fixed 重载数据时,保持滚动条位置不变
    • reset 重载数据时,滚动条位置恢复置顶
    • default 默认方式,无需设置。即重载数据或切换分页时,纵向滚动条置顶,横向滚动条位置不变。
    string -
    editTrigger 2.7+

    是用于设定单元格编辑的事件触发方式。如双击: dblclick

    string

    click

    title 定义 table 的大标题(在文件导出等地方会用到) string -
    text 自定义文本,如空数据时的异常提示等。 object 查看默认值
    autoSort

    是否由组件自动进行前端排序。若为 false,则需自主排序,即由后端直接返回排序好的数据。#详细用法

    boolean

    true

    initSort

    初始排序状态。用于在数据表格渲染完毕时,按某个字段排序显示。它接受一个 object 类型的值,包含属性有:

    • field 排序字段。对应 cols 设定的各字段名
    • type 排序方式。可选值 : 'asc','desc',null,即:升序、降序、默认
    
    
    1. initSort: {
    2. field: 'id', // 按 id 字段排序
    3. type: 'desc' // 降序排序
    4. }
    object -
    skin

    设置表格边框风格。可选值:grid|line|row|nob

    string

    grid

    size

    设置表格其他尺寸。可选值:sm|md|lg

    string

    md

    even

    是否开启隔行背景。

    string

    false

    before 2.7+ 数据渲染之前的回调函数。 function -

    done

    数据渲染完毕的回调函数。返回的参数如下:

    
    
    1. table.render({
    2. done: function(res, curr, count){
    3. console.log(res); // 得到当前渲染的数据
    4. console.log(curr); // 得到当前页码
    5. console.log(count); // 得到数据总量
    6. }
    7. // … // 其它属性
    8. });
    function -
    error 2.6+ 数据请求失败的回调函数。返回两个参数:错误对象、内容。 function -

    异步属性

    异步属性本质也是基础属性,当开启 url 属性时才有效,由于相关属性成员较多,所以单独提取介绍。

    属性名 描述
    url

    发送异步请求的 URL。默认会自动传递两个参数:?page=1&limit=30(该参数可通过 request 属性自定义)
    page 代表当前页码、limit 代表每页数据条数。

    method

    请求的方式,默认:get

    where

    请求的其他参数。如:where: {token: 'sasasas', id: 123}

    headers

    请求的数据头参数。如:headers: {token: 'sasasas'}

    contentType

    请求的内容编码类型。若要发送 json 内容,可设置:
    contentType: 'application/json'

    dataType 2.7+

    请求的数据类型,默认 json

    jsonpCallback 2.7+

    设置当 dataType: 'jsonp' 时的回调函数名。

    request

    用于对默认的分页相关的请求参数 page,limit 重新设定名称。如:

    
    
    1. request: {
    2. pageName: 'curr', // 页码的参数名称,默认:page
    3. limitName: 'nums' // 每页数据条数的参数名,默认:limit
    4. }

    那么请求数据时的参数将会变为 ?curr=1&nums=30

    parseData

    数据格式解析的回调函数,用于将返回的任意数据格式解析成 table 组件规定的数据格式:

    
    
    1. {
    2. "code": 0,
    3. "msg": "",
    4. "count": 1000,
    5. "data": [{}, {}]
    6. }

    很多时候,您接口返回的数据格式并不一定都符合 table 默认规定的格式,比如:

    
    
    1. {
    2. "status": 0,
    3. "message": "",
    4. "total": 180,
    5. "data": {
    6. "item": [{}, {}]
    7. }
    8. }

    此时我们可以借助 parseData 回调函数将数据解析并转换为默认规定的格式:

    
    
    1. table.render({
    2. elem: '',
    3. url: '',
    4. parseData: function(res){ // res 即为原始返回的数据
    5. return {
    6. "code": res.status, // 解析接口状态
    7. "msg": res.message, // 解析提示文本
    8. "count": res.total, // 解析数据长度
    9. "data": res.data.item // 解析数据列表
    10. };
    11. },
    12. // … //其他参数
    13. });

    该函数非常实用

    返回数据中的特定字段

    在返回的数据中,允许规定某些特定字段,以便 table 组件进行相应的特定解析。

    特定字段名 描述 读写状态
    LAY_CHECKED 当前行的选中状态 可读可写
    LAY_DISABLED 当前行是否禁止选择 可读可写
    LAY_INDEX 当前行下标。每页重新从零开始计算 只读
    LAY_NUM 当前行序号 只读
    LAY_COL 当前列的表头属性配置项 只读

    示例一: 在返回的数据中设置特定字段:

    1. {
    2. "code": 0,
    3. "count": 1000,
    4. "data": [{},{
    5. LAY_DISABLED: true
    6. }]
    7. }

    示例二: 在模板中读取特定字段示例:

    表头属性

    表头属性是基础属性 cols 的子集,其使用频率甚至超过基础属性本身。

    属性名 描述 类型 默认值
    field

    设置字段名。通常是表格数据列的唯一标识

    string -
    title

    设置列的标题。

    string -
    fieldTitle 2.8+

    设置列的字段标题。该属性在筛选列和导出场景中优先级高于 title 属性

    string -
    width

    设置列宽。若不填写,则自动分配;若填写,则支持值为:数字、百分比。如: width: 200 / width: '30%'

    number/string -
    minWidth

    设置当前列的最小宽度,一般用于列宽自动分配的情况。其优先级高于基础属性中的 cellMinWidth

    number

    60

    maxWidth 2.8+

    设置当前列的最大宽度。其优先级高于基础属性中的 cellMaxWidth

    number -
    type

    设置列类型。可选值有:

    • normal 常规列,无需设定
    • checkbox 复选框列
    • radio 单选框列
    • numbers 序号列
    • space 空列
    string

    normal

    LAY_CHECKED

    设置全选状态,当列设置 type: 'checkbox' 时才有效。

    boolean

    false

    fixed

    设置固定列,即不跟随 table 横向滚动条而滚动。可选值有:

    • left 固定在左
    • right 固定在右
    string -

    templet

    设置列的自定义模板,核心属性。模板遵循 laytpl 组件语法。

    templet 提供了三种使用方式,选择任一用法即可:

    • 设置模版选择器

    
    
    
    
    1. table.render({
    2. cols: [[
    3. {field: 'title', templet: '#TPL-demo-title'}
    4. // …
    5. ]],
    6. // …
    7. });

    • 设置模板内容

    该方式必须在内容中包裹一层 

    ,否则无法读取模板。

    
    
    1. table.render({
    2. cols: [[
    3. {field: 'title', templet: ''}
    4. // …
    5. ]],
    6. // …
    7. });

    • 设置模板函数

    函数将返回一个 d 参数,包含当前行数据及特定的额外字段。

    
    
    1. table.render({
    2. cols: [[
    3. {field: 'title', templet: function(d){
    4. console.log(d); // 得到当前行数据
    5. console.log(this); // 得到表头当前列配置项
    6. console.log(d.LAY_NUM); // 得到序号。或其他特定字段
    7. // 返回模板内容
    8. return ''+ d.title +''
    9. }}
    10. // …
    11. ]],
    12. // …
    13. });
    exportTemplet 2.6.9+

    设置表格导出时的模板,用法同 templet 属性。当 templet 指向的模板内容较复杂时建议使用,如下以模板存在 select 元素为例:

    
    
    1. exportTemplet: function(d, obj){
    2. // 当前 td
    3. var td = obj.td(this.field);
    4. // 返回 select 选中值
    5. return td.find('select').val();
    6. }
    string
    function
    -

    totalRow

    是否开启该列的自动合计功能。

    • 前端合计
    
    
    1. totalRow: true // 开启合计行,并默认对当前所有行数据进行前端合计
    • 后端合计

    前端合计的数据有限,因此常常需要后端直接返回合计行结果,此时将优先读取后端的合计行返回结果,其格式如下:

    
    
    1. {
    2. "code": 0,
    3. "totalRow": {
    4. "score": "777",
    5. "experience": "999"
    6. },
    7. "data": [{}, {}],
    8. "msg": "",
    9. "count": 1000
    10. }

    如上,在 totalRow 中返回所需统计的列字段名和值即可。
    totalRow 字段同样可以通过 parseData 回调来解析成为 table 组件所规定的数据格式。

    • 合计行模板

    
    
    1. totalRow: '{{= d.TOTAL_NUMS }} 单位' // 还比如只取整:'{{= parseInt(d.TOTAL_NUMS) }}'

    boolean
    string

    false

    edit

    用于对列所在的单元格开启编辑功能。可选值有:

    • edit: 'text' 单行输入模式
    • edit: 'textarea' 多行输入模式 2.7+

    函数写法 2.7+

    
    
    1. edit: function(d){
    2. // d 即为当前行数据,此时可根据行相关字段来开启该行是否编辑的权限
    3. if(d.editable){ // editable 为任意字段名
    4. return 'text'; // 编辑模式
    5. }
    6. }
    string
    function

    false

    hide

    是否初始隐藏列

    boolean

    false

    escape

    是否对当前列进行内容编码(转义 html),优先级大于基础属性中的 escape

    boolean

    true

    sort

    是否开启列的排序功能。
    注意:不推荐对值同时存在“数字和普通字符”的列开启排序,因为会进入字典序排序计算中,如:'张三' > '2' > '100',这可能并不是你想要的结果,但字典序排列采用的是 ASCII 码比对。

    boolean

    false

    unresize

    是否禁用拖拽列宽。默认情况下会根据列类型 type 属性来决定是否禁用,如复选框列,会自动禁用。而其它普通列,默认允许拖拽列宽,当然你也可以设置 true 来禁用该功能。

    boolean

    false

    event

    自定义单元格点击事件名,以便在 单元格工具事件 中完成对该单元格的事件处理。

    string -
    style

    自定义单元格样式。可传入任意的 CSS 内容,如:style: 'font-size: 13px; color: red;'

    string -
    align

    单元格排列方式。可选值有:left | center | right

    string

    left

    colspan

    单元格所占列数。一般用于多级表头

    number

    1

    rowspan

    单元格所占行数。一般用于多级表头

    number

    1

    重载

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

    重载方式 API
    完整重载 table.reload(id, options, deep)
    仅数据重载 table.reloadData(id, options, deep)

    重载的使用方式完全相同,区别只是在于参与重载时的属性差异及其对应的效果差异。一般按照实际需求选择使用。

    完整重载

    table.reload(id, options, deep);

    • 参数 id : table 渲染时的 id 属性值
    • 参数 options : 为基础属性配置项
    • 参数 deep 2.6+ : 是否采用深度重载(即重载时始终携带初始时及上一次重载时的参数),默认 false。

      2.6 之前版本的 table.reload() 方法兼容性说明

    该方法用于对表格的视图和数据在内的全部重载,所有属性均会参与到重载中,对应的表格会有一个直观的刷新效果。

    1. // 渲染
    2. table.render({
    3. elem: '', // 绑定元素选择器
    4. id: 'test', // 自定义 id 索引
    5. // 其他属性 …
    6. });
    7. // 完整重载 - 所有属性属性(options)均可参与到重载中
    8. table.reload('test', {
    9. where: { // 传递数据异步请求时携带的字段
    10. aaa: '111',
    11. bbb: '222'
    12. //…
    13. },
    14. height: 1000 // 重设高度
    15. });

    仅数据重载 2.7+

    table.reloadData(id, options, deep);

    • 参数同 table.reload(id, options, deep) 参数

    该方法用于对表格的数据重载,与数据无关的属性不会参与到重载中。因此若只是更新数据,该方法可大幅提升体验。

    1. // 渲染
    2. table.render({
    3. elem: '', // 绑定元素选择器
    4. id: 'test', // 自定义 id 索引
    5. // 其他属性 …
    6. });
    7. // 数据重载 - 仅与数据相关的属性(options)能参与到重载中
    8. table.reloadData('test', {
    9. where: {}, // 数据异步请求时携带的字段集 --- 属性设置有效,因属于数据相关属性
    10. scrollPos: true, // 设定重载数据或切换分页时的滚动条的位置状态 --- 属性设置有效
    11. // …
    12. height: 2000 // 高度 --- 属性设置无效,因不属于数据相关属性
    13. });

    获取选中行

    table.checkStatus(id);

    • 参数 id : table 渲染时的 id 属性值

    该方法用于获取表格当前选中行相关数据

    1. // 渲染
    2. table.render({
    3. elem: '', // 绑定元素选择器
    4. id: 'test', // 自定义 id 索引
    5. // 其他属性 …
    6. });
    7. // 获取选中行相关数据
    8. var tableStatus = table.checkStatus('test');
    9. console.log(checkStatus.data) // 选中行的数据
    10. console.log(checkStatus.data.length) // 选中行数量,可作为是否有选中行的条件
    11. console.log(checkStatus.isAll ) // 表格是否全选

    设置行选中状态 2.8+

    table.setRowChecked(id, opts);

    • 参数 id : table 渲染时的 id 属性值
    • 参数 opts : 设置行选中时的可选属性,详见下表
    opts 描述 类型 默认值
    type 选中方式。可选值: checkbox,radio string checkbox
    index 选中行的下标。即数据的所在数组下标(0 开头)。
    可设置 all 表示全选。
    number
    string
    -
    checked 选中状态值。 若为 false 可取消选中。 boolean true
    selectedStyle 是否仅设置样式状态。若为 true 则只标注选中样式,不对数据中的 LAY_CHECKED 属性赋值。 boolean false

    该方法用于设置行的选中样式及相关的特定属性值 LAY_CHECKED

    1. // 渲染
    2. table.render({
    3. elem: '', // 绑定元素选择器
    4. id: 'test', // 自定义 id 索引
    5. // 其他属性 …
    6. });
    7. // 设置某行选中
    8. table.setRowChecked('test', {
    9. index: 0, // 选中行的下标。 0 表示第一行
    10. });
    11. // 取消选中行
    12. table.setRowChecked('test', {
    13. index: 'all', // 所有行
    14. checked: false
    15. });

    获取当前页接口数据

    table.getData(id);

    • 参数 id : table 渲染时的 id 属性值

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

    1. // 渲染
    2. table.render({
    3. elem: '', // 绑定元素选择器
    4. id: 'test', // 自定义 id 索引
    5. // 其他属性 …
    6. });
    7. // 获取当前页接口数据
    8. var data = table.getData('test');
    9. console.log(data);

    获取表格缓存数据集

    var tableCache = table.cache;

    table.cache 是一段存储当前页表格所有实例的当前页的临时数据,通过 id 作为索引,它包含接口返回的原始数据和组件内部的特定字段。 使用该静态属性可对表格数据进行读写操作。

    1. // 渲染
    2. table.render({
    3. elem: '', // 绑定元素选择器
    4. id: 'test', // 自定义 id 索引
    5. // 其他属性 …
    6. });
    7. // 获取对应 table 的临时数据
    8. var thisCache = table.cache['test'] || {};
    9. // 变更对应 table 的临时数据中的某个字段值
    10. thisCache.fieldName = 123;

    重置尺寸

    table.resize(id);

    • 参数 id : table 渲染时的 id 属性值

    该方法用于重置表格尺寸和结构,其内部完成了固定列高度平铺、动态分配列宽、容器滚动条宽高补丁 等适配。它一般用于修复特殊情况下导致的列宽适配异常(如浏览器窗口尺寸改变导致的表格父容器宽度变化),以保证表格尺寸依旧能友好展示。

    1. // 渲染
    2. table.render({
    3. elem: '', // 绑定元素选择器
    4. id: 'test', // 自定义 id 索引
    5. // 其他属性 …
    6. });
    7. // 重置对应 table 的尺寸,一般写在表格外部容器宽高发生变化后的段落
    8. table.resize('test');

    导出数据

    table.exportFile(id, data, opts);

    • 参数 id : table 渲染时的 id  要导出的数据表头(当 id 为 array 类型时)。
    • 参数 data : 要导出的自定义数据,参数可选。
    • 参数 opts 2.7+: 导出数据时的属性可选项,支持: type,title

    该方法用于外部导出对应 table 的数据和任意自定义数据。

    1. // 渲染
    2. table.render({
    3. elem: '', // 绑定元素选择器
    4. id: 'test', // 自定义 id 索引
    5. // 其他属性 …
    6. });
    7. // 外部导出对应 table 的数据
    8. table.exportFile('test');
    9. // 导出自定义数据
    10. table.exportFile(['名字','性别','年龄'], [
    11. ['张三','男','20'],
    12. ['李四','女','18'],
    13. ['王五','女','19']
    14. ], {
    15. type: 'csv', // 导出的文件格式,支持: csv,xls
    16. title: '导出的文件标题'
    17. });

    获取配置项 2.8+

    table.getOptions(id);

    • 参数 id : table 渲染时的 id 属性值

    该方法用于外部获取对应 table 实例的属性配置项。

    1. // 渲染
    2. table.render({
    3. elem: '', // 绑定元素选择器
    4. id: 'test', // 自定义 id 索引
    5. // 其他属性 …
    6. });
    7. // 获取配置项
    8. var thisOptions = table.getOptions('test');
    9. console.log(thisOptions);

    设置列显示或隐藏 2.8+

    table.hideCol(id, cols);

    • 参数 id : table 渲染时的 id 属性值
    • 参数 cols : 设置列(表头)显示或隐藏状态

    该方法用于外部设置对应 table 列的显示与隐藏状态。

    1. // 渲染
    2. table.render({
    3. elem: '', // 绑定元素选择器
    4. id: 'test', // 自定义 id 索引
    5. // 其他属性 …
    6. });
    7. // 设置对应列的显示或隐藏
    8. table.hideCol('test', {
    9. field: 'title', // 对应表头的 field 属性值
    10. hide: true // `true` or `false`
    11. });

    你可能感兴趣的:(Layui,layui,前端,javascript)