跳到主要内容

数据表格

WdTable

适用场景

以表格形式展示多行数据,支持对数据进行排序、搜索、分页、自定义显示内容和操作

基础能力说明

模型页面自动生成表格组件

在创建模型应用、模型页面时,会自动在数据的管理表格页面生成该组件,并与数据的新增/更新/查看页面构建关联关系,实现对应的页面跳转逻辑

配置表格数据

表格的数据可选择数据表、或绑定表达式。

1. 快速选择数据表

如下图,直接选择数据表并配置查询入参。表格内部请求会自带分页、排序、筛选等功能。并且点击右上角可跳转到该数据表的管理后台查看数据。

2. 绑定表达式

表达式可为静态数据、变量。您可通过 Query 连接内置数据表和外部 APIs 等,然后在表达式中选择 query 进行绑定。

下列视频展示了如何从 APIs 查询数据,并配置分页:

3. 绑定 APIs(最新版本已下架)

注意:自v2.30.0版本组件起,数据表格支持APIs调用已经下线,请通过表达式选择Query查询APIs。
调用 APIs 的参数要求
  1. 当「数据源类型」选择 APIs 时,可绑定 APIs 方法来查询数据并显示在表格中,方法中需要包含以下出入参,并符合有相关要求

    1. 方法入参:

      • pageNo:页码
      • pageSize:每页大小
      • orderBy:排序字段名称,可传值出参 records 中的各字段(非必需,如无该参数,将无法进行排序控制)
      • orderType:排序方式,升序传值 asc,降序传值 desc(非必需,如无该参数,将无法进行排序控制)
    2. 方法出参:

      • total:记录总条数
      • records:对象数组格式的多条数据,对象内部各元素为表格列字段。注:数组中对象需包含数据唯一标识 _id(文本类型) 字段,分页器翻页等功能才可以正常使用。
    3. 字段标识必须与上述标识完全一致,并且都是一级参数,不能包含在其他对象参数中,可参考任一数据模型的「查询列表方法」的参数格式

  2. APIs 连接器方法的出入参格式可参考任意数据模型中预置的「查询列表」方法参数

设置表格列的排序

表格列默认按所绑定数据模型中的字段顺序进行排序,可在「列管理」属性中拖动调整列顺序

添加表格列

表格列默认不展示系统字段,包括「数据标识、创建时间、更新时间、所有人、创建人、修改人、所属部门」,可再「列管理」属性中点击「添加列」按钮添加系统字段或之前删除的字段

列设置

选中「列管理」中的列项目后,会展示列设置弹窗,进行列标题、展示内容类型、列宽、对齐方式、排序导出等效果进行控制

字段查询范围设置

数据表格支持v2 查询协议后,支持按需配置字段的查询范围,从而提升查询性能。 image 字段查询范围设置支持以下三种方式:

  • 全部字段:返回所有字段,包含本表及关联表的所有字段。
  • 表格列字段:返回本表的全部字段,不包含关联表的字段。(默认设置)
  • 自定义查询字段:支持按需配置需要返回的主表字段,及是否返回关联表字段。 image

扩展场景说明

配置自定义列自定义显示内容和样式

  1. 将表格列的展示内容属性设置为「自定义内容」,则该列会形成插槽,允许放入其他组件
  2. 插槽内部组件的属性,可通过表达式获取当前行相关信息,例如:在自定义列的插槽中拖入文本组件,选中该组件,点击「文本内容」属性右侧的数据绑定按钮,在表达式编辑器中选取行数据字段,或写入其他函数内容,来显示所需信息

定义动态行背景

表格组件支持对行数据内容进行判断,进而显示不同的背景颜色,示例如下:

  1. 在「代码编辑器-当前页面-handler」中创建 1 个新的方法
export default function ({ event, data }) {
//event.detail中可获得record,rowkey,recordIndex等值,用于行背景颜色的判断控制
return event.detail.recordIndex % 2 === 0
? 'rgb(199,237,204)'
: 'rgb(250,249,222)';
}
  1. 在表格组件的「行背景色」属性中,点击数据绑定按钮,打开弹窗,在表达式模块中写入:$w.page.handler.color,即可实现奇偶数行显示不同的背景

操作列按钮跳转表单页面,并传参当前行数据_id,实现数据的编辑更新

  1. 在表格组件的操作列节点中,拖拽放入一个按钮组件

  2. 将该按钮内容调整为编辑;为保证按钮样式合理美观,可再将按钮类型调整为链接

  3. 创建一个表单页面,放入表单容器组件,绑定与表格组件一致的数据模型,表单场景设置为更新

  4. 再在大纲树中选中页面节点,条件一个 URL 参数,命名为 id,并将该参数绑定到表单容器的数据标识属性上

  5. 返回表格页面,选中刚才添加的按钮组件,配置点击时-打开刚才配置的表格页面,为页面参数 id 绑定表达式,表达式选取「数据标识」字段

  6. 完成如上配置,即可实现点击「编辑」按钮,跳转到表单页面,回显表单数据,修改后,点击提交,实现数据修改,再返回表格页面

获取「选择框列」选中值

表格组件的「选中行改变」事件,可以获取到所选的多行数据信息

  1. 表格组件的「选中行改变」事件,可以获取到所选的多行数据信息,可将多行数据以 array 形式赋值到变量中

自定义配置筛选器

  1. 表格组件的「筛选器」属性支持绑定变量,实现筛选器的自定义配置

  2. 变量绑定示例

({filterConfig:[
{
name: '_id',
value: '111',
label: '数据标识111',
filterType:'search',
filterTypeOption:['search']

},
{
name: 'createdAt',
value: ['2023-07-04 00:00:00','2023-08-17 00:00:00'],
label: '创建时间111',

},
{
name: 'date',
value:['2023-07-04','2023-08-17 00:00:00'],
label: '日期111',

},
{
name: 'mjdx11',
value:'110101',

},
{
name: 'mjdx',
value:['110101','110102'],
label: '枚举多选111',

},{
name:'belx',
value:[true, false, null]
}

]})
  1. 字段属性说明
属性说明类型默认值是否必填
name筛选字段的 name 值,对应数据源字段的 name 值string-
label自定义标题string数据源字段名称
value筛选字段初始值string/string[]-
filterType默认筛选计算方式string参考筛选默认值列表
filterTypeOption筛选字段支持的计算方式列表string[]参考筛选默认值列表

​ 4. 筛选器默认值列表

数据源字段默认支持的计算方式列表 默认计算方式
日期/时间/数字/年龄字段
范围scopescope
等于eq
不等于neq
大于gt
小于lt
大于等于gte
小于等于lte
字符串/邮箱/网址/手机号码/电话号码/中文姓名 字段
包含searchsearch
不包含exclude
等于eq
不等于neq
开头是startWith
布尔型字段/枚举多选
等于任意一个inin
不等于任意一个nin
枚举单选/主子明细/关联关系
等于eqeq
不等于neq

注:

  • 默认筛选计算方式(filterType)的取值范围为对应数据源字段支持的计算方式的 value 值
  • 筛选方式支持的字段列表(filterTypeOption)为对应数据源字段支持的计算方式的 value 值数组,若不传,则为该字段默认支持的计算方式列表
  1. 可通过$w.componentId.filterConfig 获取到实时的筛选配置

示例

交互式预览

样式 API 自定义样式

// 表格样式需要配合id选择器使用
#wd-page-root .wd-table {
background-color: #ecebf6;
}
#wd-page-root .wd-table__header {
background-color: #d7d3f0;
}
#wd-page-root .wd-table--bordered {
border: 1px solid #d7d3f0;
}

CSS 变量自定义样式

#wd-page-root .wd-table {
// 表格背景色
--wd-table-color-bg: #f7ffee;
// 鼠标悬浮行背景颜色
--wd-table-row-color-bg-hover: #c7e1bf;
// 表头背景颜色
--wd-table-header-color-bg: #c7e1bf;
// 行选中颜色
--wd-table-row-color-bg-selected: #cadbc0;
// 表格边框颜色
--wd-table-color-border: #c7e1bf;
// 表格默认行高(中行高)
--wd-table-td-height-md: 70px;
}

属性

组件接收的外部传入的属性

属性名
属性标识
类型
说明
数据源dataSourceTypestring

选择数据源类型

示例:"data-model"

数据模型bindMetadataobject

数据模型字段发生变化时,点击上方刷新图标同步数据模型结构;字段新增时,可通过下方列管理-添加列,配置最新字段表格列展示。

展示数据的数据来源,包括数据模型/视图

表达式dataSourceDataarray

新特性:表格追加绑定表达式数据,原APIs路径优化为表达式。表格展示的数据,格式为数组。查看示例

表格展示的数据,可选择变量。

数据主键recordKeystring

用于区分不同的数据,影响行选择、行编辑等功能。一般采用数据库中唯一自增ID。

用于区分不同的数据,影响行选择、行编辑等功能。一般采用数据库中唯一自增ID。

示例:"_id"

数据加载状态loadingboolean

开启后会展示数据加载中状态

数据筛选queryConditionarray

点击fx支持编辑数据筛选表达式 查看格式

对数据进行筛选过滤

排序方式orderTypestring

可设置升序或降序,绑定表达式时,升序传值asc,降序传值desc

默认值:"desc"

启用多字段排序isSupportMultipleSortboolean

示例:false

数据排序sorterarray

可设置数据排序规则,支持拖拽调整排序优先级,数组下标越小优先级越高。绑定数据示例:[{"orderBy":"updatedAt","orderType":"desc"}],升序传值asc,降序传值desc

示例:[ { "orderBy": "updatedAt", "orderType": "desc", "label": "更新时间" } ]

筛选器filterFieldsobject

通过开启fx、绑定表达式,可配置默认筛选值、默认筛选方式等功能 查看示例

配置表格运行态的筛选器,支持对象类型数据绑定,属性字段为filterConfig

示例:{}

APIsbindConnectMetadataobject

展示数据的 APIs 来源选择

调用方法connectorMethodobject

方法的出入参需满足组件要求,查看文档

进行数据的 APIs 调用方法选择

查询入参connectorParamsstring

对APIs 调用方法获取的数据进行筛选过滤。例如 {name:'',value:''}

列管理columnSetsarray

配置表格列,支持拖拽调整列排序

示例:[]

操作列(最后一列)enableCellCustomOptionboolean

开启后,可拖拽按钮等组件,放入大纲树的操作列节点或表格的操作列区域

示例:true

操作列标题customOptionTitlestring

默认值:"操作"

数据选择列(首列)columnSelectTypestring

控制表格数据选择列的样式

默认值:"select"

左冻结fixedFrontstring

冻结首列至所选列,仅PC端生效

左冻结与右冻结属性配置的列出现交叉重复时,为避免表格的横向滚动锁定,冻结属性会自动失效

右冻结fixedEndstring

冻结所选列至尾列,仅PC端生效

左冻结与右冻结属性配置的列出现交叉重复时,为避免表格的横向滚动锁定,冻结属性会自动失效

字段查询范围selectFieldTypestring

仅查询范围中的字段,可在表格自定义列中被引用

默认查询表格列字段

默认值:"table"

自定义查询字段selectFieldsarray
空状态提示emptyTextstring

无数据时的提示说明,内容为空时则不显示该提示

默认值:"暂无数据"

行背景颜色rowColorstring

设置固定值或绑定低码方法,实现行背景颜色的改变

表头在页面顶部悬停isSuspendHeaderboolean

仅PC端有效;且可能因为父级组件的样式干扰,导致该属性失效

如无法生效,请确保祖先元素没有设置overflow属性为hidden、scroll或auto。这些属性会导致position: sticky失效。另外,如果页面已经有fixed的元素,那么悬停有可能会看不到,需要通过样式手动调整下悬停的位置

默认值:true

显示分页器enablePaginationboolean

开启后,可支持表格分页

默认值:true

每页行数defaultPageSizenumber

配置PC端表格默认的每页行数

默认值:10

PC端默认页码defaultPageIndexnumber

配置PC端表格默认的初始页码

默认值:1

分页器在页面底部悬停isSuspendFooterboolean

仅PC端有效;且可能因为父级组件的样式干扰,导致该属性失效

如无法生效,请确保祖先元素没有设置overflow属性为hidden、scroll或auto。这些属性会导致position: sticky失效。另外,如果页面已经有fixed的元素,那么悬停有可能会看不到,需要通过样式手动调整下悬停的位置

默认值:true

启用服务端分页enableTotalboolean

默认为客户端分页,启用后可实现动态加载数据

开启后,可支持服务端分页

示例:false

数据总数totalnumber

默认为表达式输入的数组长度,请输入数据表实际数据总数。详见后端分页指引

默认为表达式输入的数组长度,请输入数据表实际数据总数。

行高调节按钮enableTableHeightSizeBtnboolean

开启后,可支持调节行高

默认值:true

全局按钮enableGlobalButtonboolean

开启后,可拖拽按钮等组件,放入大纲树的全局按钮节点或表格的全局按钮区域

示例:true

刷新按钮enableRefreshBtnboolean

开启后,可展示刷新按钮

默认值:true

事件

组件暴露的事件,可以监听组件的事件来触发一些外部的动作

事件名
事件code
事件出参 event.detail
适用情况
说明
点击表格行tabTableRowobject
  • record: array选中行记录

    选中行记录

    • object
    • rowKey: string选中行记录id

      选中行记录id

    • recordIndex: number选中行index

      选中行index

    移动端,PC端

    点击表格某一行时触发

    点击表格列cellClickobject
    • record: array选中行记录

      选中行记录

      • object
      • column: array选中列表头

        选中列表头

        • object
        • rowKey: string选中行记录id

          选中行记录id

        • recordIndex: number选中行index

          选中行index

        • columnIndex: number选中列index

          选中列index

        移动端,PC端

        点击表格某一行时触发

        选中行改变rowsSelectedobject
        • data: array选中行记录

          选中行记录

          • object
          移动端,PC端

          点击数据选择列(多选/单选列),改变已选中的行时触发

          查询成功querySuccessobject
          • data: object 查询结果,查询条件

            查询结果,查询条件

            • data:
            • query:
          移动端,PC端

          每次数据查询成功时均会触发,包括切换分页、修改筛选条件时

          查询为空queryEmptyobject
          • data: object

            查询结果,查询条件

            • data:
            • query:
          移动端,PC端

          每次数据查询成功时均会触发,包括切换分页、修改筛选条件时

          查询失败queryFailobject
          • error: object 错误信息

            组件内部抛出的错误信息

            • requestid: string请求 id

              如果是接口相关错误会提供请求 id

            • message: string错误提示信息
            • code: string错误码
            • original: 原始错误
          移动端,PC端

          每次数据查询失败时均会触发,包括切换分页、修改筛选条件时

          点击排序sortobject
          • sort: array当前引起变更的排序信息

            当前引起变更的排序信息

            • object
              • orderType: string
              • orderBy: string
          移动端,PC端

          点击排序

          点击刷新按钮onRefreshBtnClick移动端,PC端

          点击刷新按钮

          分页变化onPagingChangeobject
          • query: object 分页信息

            分页信息

            • pageIndex: number
            • pageSize: number
          移动端,PC端

          分页变化

          筛选器值变化onFilterChangeobject
          • searchValues: object 变更的目标值

            变更的目标值

            • key: string
            • val: string
            • rel: string
          移动端,PC端

          筛选面板搜索值变化/搜索触发回调

          选中行(已废弃)rowsSelect移动端,PC端

          点击数据选择列(多选/单选列),改变已选中的行时触发。可通过$w.组件id.selectedRecords获取选中行的详细数据。

          属性 API

          通过属性 API,可以获取组件内部的状态和属性值,可以通过$w.componentId.propertyName 来访问组件内部的值,如 $w.input1.value ,详请请参考 属性 API

          只读属性名
          属性标识
          类型
          说明
          数据源dataSourceTypestring

          选择数据源类型

          数据模型bindMetadataobject

          展示数据的数据来源,包括数据模型/视图

          表达式dataSourceDataarray

          表格展示的数据,可选择变量。

          数据主键recordKeystring

          用于区分不同的数据,影响行选择、行编辑等功能。一般采用数据库中唯一自增ID。

          列管理columnSetsarray

          配置表格列,支持拖拽调整列排序

          每页行数defaultPageSizenumber

          配置PC端表格默认的每页行数

          PC端默认页码defaultPageIndexnumber

          配置PC端表格默认的初始页码

          表格数据recordsarray

          表格数据

          表格数据总数totalnumber

          表格数据总数

          页码pageNonumber

          表格当前页码

          页长pageSizenumber

          每页显示行数

          表格选中数据selectedRecordsarray

          表格选中的数据

          错误信息errorobject

          组件内部抛出的错误信息

          表格排序的数据sortarray

          表格排序的数据,用于表格请求查询,格式与当前数据源协议一致。详见查询协议示例

          表格筛选的数据filter

          表格排序的数据,用于表格请求查询,格式与当前数据源协议一致。详见查询协议示例

          数据源协议版本dataSourceVersionstring

          数据源类型为数据模型时,当前表格支持的数据源协议版本

          筛选面板的配置filterConfigarray

          筛选面板的配置

          方法 API

          通过方法 API,可以通过程序触发组件内部的方法,比如提交表单,显示弹窗等, 可以通过$w.componentId.methodName来调用组件方法,如 $w.form1.submit()

          方法名
          方法标识
          参数
          方法说明
          数据导入import

          仅当数据源为数据模型场景时支持导入,可按照模版,上传 excel 文件,录入数据

          数据导出(可选导出模式)exportOptionalMode

          支持将表格数据导出为excel,可选:导出全部数据、筛选后的数据、选中数据

          数据导出(导出选中数据)export

          支持将当前选中数据导出为 excel

          删除单条数据deleteOnestring删除数据的标识

          仅当数据源为数据模型场景时,支持删除行数据

          删除选中数据deleteSelected

          仅当数据源为数据模型场景时,支持删除当前选中的行记录

          刷新表格(查看第1页数据)refresh

          刷新表格(查看第 1 页数据)

          刷新表格(查看当前页数据)refreshKeepPage

          刷新表格(查看当前页数据)

          打开操作列弹窗(仅移动端生效)openOperationDialog

          打开操作列弹窗

          重置筛选器resetFilter

          重置筛选器

          清空选中项clearSelection

          清空选中项

          样式 API

          通过样式 API,可以覆盖组件中内部元素的样式来实现自定义,例如在低代码编辑器中中通过 #wd-page-root .wd-btn 即可为所有的按钮组件编写样式,通过 :scope 可以控制单个组件样式, 详细说明请参考样式 API

          名称
          类名
          说明和示例
          根元素.wd-table-wrap数据表格组件根元素
          /* :scope 指的是当前组件元素 */
          /* 具体可参考样式 API 文档 */
          :scope.wd-table-wrap {
            /* 在这里编写CSS 样式 */
          }
          PC 端表格组件根元素.wd-pc-table可以为 PC 端的表格编写样式
          /* :scope 指的是当前组件元素 */
          /* 具体可参考样式 API 文档 */
          :scope.wd-pc-table {
            /* 在这里编写CSS 样式 */
          }
          H5 端表格组件根元素.wd-h5-table可以为 H5 端的表格编写样式
          /* :scope 指的是当前组件元素 */
          /* 具体可参考样式 API 文档 */
          :scope.wd-h5-table {
            /* 在这里编写CSS 样式 */
          }
          表头文字样式.wd-table__box th>div表头文字样式
          
                  :scope .wd-table__box th>div {
                    font-size: 20px;
                    color: gray;
                  }
                
          表头背景样式.wd-table__box th表头背景样式
          
                  :scope .wd-table__box th {
                    background-color: red;
                  }
                
          表格文字样式.wd-table__box td>div表格文字样式
          
                  :scope .wd-table__box td>div {
                    font-size: 20px;
                    color: gray;
                  }
                
          表格文字样式.wd-table__box td表格文字样式
          
                  :scope .wd-table__box td {
                    background-color: lightgray;
                    height: 36px;
                  }
                
          表格主体样式.wd-table表格主体样式
          
                  :scope .wd-table {
                    border: 2px solid gray;
                    border-radius: 10px;
                  }
                

          了解样式 API

          CSS 变量

          .wd-table-wrap {
          //默认背景颜色
          --wd-table-color-bg: var(--wd-color-bg-container);
          //表头背景颜色
          --wd-table-header-color-bg: var(--wd-color-bg-secondarycontainer);

          //行背景颜色-默认
          --wd-table-box-header-tr-color-bg: transparent;
          //行背景颜色-鼠标悬停
          --wd-table-row-color-bg-hover: var(--wd-color-bg-container-hover);
          //行背景颜色-选中状态
          --wd-table-row-color-bg-selected: var(--wd-color-brand-light);

          //表格文字字号
          --wd-table-font-size: var(--wd-font-size-default);
          //表格文字颜色
          --wd-table-color-text: var(--wd-color-text-default);
          //表格文字字重
          --wd-table-color-text-weight: var(--wd-color-text-default);

          //表头文字颜色
          --wd-table-header-color-text: var(--wd-color-text-default);
          //表头文字字重
          --wd-table-header-font-weight: var(--wd-font-weight-medium);

          //表格行高-低
          --wd-table-td-height-sm: 3rem;
          //表格行高-中
          --wd-table-td-height-md: 3.375rem;
          //表格行高-高
          --wd-table-td-height-lg: 5.125rem;

          //表格外边框颜色
          --wd-table-color-border: var(--wd-color-border-default);
          //表格内边框颜色
          --wd-table-color-border-inner: var(--wd-color-border-separator);

          //表格圆角
          --wd-table-border-radius: calc(var(--wd-border-radius) * 2);

          //移动端底部按钮区域边框颜色
          --wd-table-footer-border-color: var(--wd-color-border-default);
          }

          版本变化

          • 本次升级提供全新的 PC 端/移动端表格样式
          • 完善筛选器、表格列配置能力
          • 新增点击表格行事件
          • 规范组件属性名称与分类

          查询协议示例

          • 表格排序的数据,用于表格请求查询,格式与当前数据源协议一致。组件升级到 2.30.0 后,新添加的表格组件,数据模型查询协议升级为 v2 版本,已有表格组件仍沿用 v1 版本协议。v1 版本协议的参数结构示例:[{"orderBy":"updateAt","orderType":"desc"}],v2 版本协议的参数结构示例:[{"updateAt":"desc"}]
          • 表格筛选的数据,用于表格请求查询,格式与当前数据源协议一致。组件升级到 2.30.0 后,新添加的表格组件,数据模型查询协议升级为 v2 版本,已有表格组件仍沿用 v1 版本协议。v1 版本协议的参数结构示例:[{"key":"test","val":"1","rel":"search"}],v2 版本协议的参数结构示例:{"where":{"$and":[{"test":{"$search":"1"}}]}}。

          升级指南

          1. 旧的表格组件,点击右侧升级按钮,可一键升级为新表格。操作列和全局按钮升级为插槽,可拖拽按钮等组件,放入表格的全局按钮插槽或操作列插槽。
          1. 全局按钮及操作列配置

          表格升级后,将原来的全局按钮及操作列按钮升级为插槽+按钮,原来配置的选区事件也同步升级为按钮事件。对于复杂的传参场景,需要重新手动配置参数。可参照如下用例:

          此场景为表格删除场景,给按钮绑定表格删除事件,同时配置入参

            1. 选择需要调整的按钮,选中按钮事件,选择对应的组件和组件方法
            1. 编辑入参【删除数据的标识】,可通过提示选择所在行记录,点选需要传递的参数

          常见问题

          使用数据容器类组件,一定要将组件放在数据容器类组件内部么?

          数据容器(Data Container)是页面与数据交互的核心组件,它能直接查询并展示数据。在我们的平台中,有多种数据容器组件可供选择,如数据列表(ListView)、数据详情(DataView)、表单容器(WdForm)以及数据表格(WdTable)。

          数据容器可实现数据与页面组件的深度整合。这大大简化了数据操作流程。除了提供数据,数据容器还支持常见的页面交互功能,例如分页加载、加载状态以及错误提示等。

          在使用数据容器时,若组件依赖于数据容器返回的数据,建议将组件置于数据容器类组件内部。例如,若要展示某条数据详情中的某个字段的图片,将组件放在相应的数据容器内部会更好。这样,数据容器可以自动处理加载中、加载失败等情况,无需关注渲染时机。

          如果只需使用数据容器获取数据,而无需进行 UI 交互,您可以直接使用 Query 功能来查询数据。

          如何在某个事件触发时刷新其他组件?

          当需要在某个事件触发时刷新其他组件时,可以在目标组件的属性上绑定一个变量,例如筛选参数的表达式中引用这个变量。然后在触发事件中改变这个变量的值,从而重新更新对应的目标组件的内容。