Skip to main content

Data List

ListView

Practical Guide

适用场景#

适用于从数据源中查询多条数据,并将返回列表循环展示的场景,如查询用户列表。

Basic Features

Data Query, Filtering, Pagination

The Data List Component is one of the core components for obtaining data, enabling quick querying of lists from data models and APIs and rendering them to the page's list, including features such as pagination.

image-20221024215721765

Data Usage and Display

Data List is a data provider, and the data it provides can be used by all business components. The data of Data List can be selected from data tables or bound expressions.

1. Quickly select a data table

Drag components that require data binding into the data container to select its data.

2. Binding Expression

Expressions can be static data or variables. You can connect to built-in data tables and external APIs, etc., via Query, and then bind a query in the expression.

image-20221024215721765

3. Binding APIs (removed in the latest version)

NoteStarting from the v2.30.0 component version, APIs invocation for Data Table has been removed. Please use expressions to select Query for querying APIs.
Parameter Requirements for Calling APIs
  1. Method input parameters:
  • pageNo: Page number (optional)
  • pageSize: Page size (optional)
  • orderBy: Sort field name (optional). Can be any field in the output parameter 'records'.
  • orderType: Sort order (optional). Pass 'asc' for ascending order or 'desc' for descending order.
  1. Method output parameters:
  • total: Total number of records (required)

  • records: An array of objects containing multiple data records. Note: Each object in the array must contain a unique identifier field _id (text type) for the paginator to function properly, such as page turning.

image-20221024221624468

Implementing Dynamic Pagination by Binding query

For data list binding expression scenarios, configure as follows to achieve dynamic pagination effects under these two pagination methods: click-to-load-more and scroll-to-bottom-load-more.

  1. Add data list:
  • Add a data list and switch to the expression scenario. image
  1. Create query:
  • Select data table

  • [Triggering Method] Automatically execute when input parameters change

  • [Page size] bound to the data list's pageSize

    $w.listView1.pageSize;
  • [Page number] bound to the data list's pageNo

    $w.listView1.pageNo;
  • image

  1. Create array variable: image
  2. Create event flow:
  • Select [Variable Assignment] for the execution action
  • Assign content as merge arrays:
[...$w.page.dataset.state.records, ...$w.query1.data.records];

image

  1. Chain data pipelines:
  • query Add event callback

  • Bind the array variable to the data list expression

    $w.page.dataset.state.records;
  • Enable dynamic pagination

  • Bind the total data count to the query's total field

    $w.query1.data.total;

    image

The following video demonstrates how to bind a query to retrieve data and configure pagination:

Field Query Scope Settings

Data lists, after supporting the v2 query protocol, enable on-demand configuration of field query scopes to improve query performance. image Field Query Scope Settings support the following three methods:

  • All Fields: returns all fields, including those from this table and associated tables.
  • Current Table Fields: returns all fields of the current table, excluding fields from associated tables. (default setting)
  • Custom Query Fields: supports on-demand configuration of main table fields to be returned and whether to return associated table fields. image

Property Introduction

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

属性名
属性标识
类型
说明
列表模板templatestring

列表内容样式的预设模板

示例:"simpleList"

数据源dataSourceTypestring

数据源类型选择

示例:"data-model"

数据模型datasourceobject

展示模型数据的数据来源

APIsbindConnectMetadataobject

展示数据的APIs来源选择

表达式dataSourceDataarray

新特性:数据列表追加绑定表达式数据,原APIs路径优化为表达式。注意:数组中默认需包含_id字段。且当输入的表达式变化时,会触发自动生成列表字段。因此建议先输入表达式再调整样式。查看示例

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

exprToFieldsSchemastring
调用方法connectorMethodobject

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

展示数据的APIs调用方法选择

查询入参connectorParamsobject

当配置了「每页条数」属性后,pageSize参数将不会生效

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

数据筛选queryConditionarray

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

对数据进行筛选过滤

排序字段orderBystring

选取对数据进行排序的字段

排序方式orderTypestring

设置升序或降序

示例:"asc"

启用多字段排序isSupportMultipleSortboolean

示例:false

数据排序sorterarray

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

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

字段查询范围selectFieldTypestring

默认查询本表字段

默认值:"main"

自定义查询字段selectFieldsarray
分页方式paginationstring

数据分页样式

示例:"loadMoreButton"

加载按钮名称loadButtonTextstring

示例:"加载更多"

每页条数pageSizenumber

设置单次加载的数据条数

示例:5

页码pageIndexnumber

初始页码

示例:1

启用动态分页enableTotalboolean

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

开启后,可支持动态分页

示例:false

数据总数totalnumber

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

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

空状态提示emptyTextstring

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

示例:"暂无数据"

加载到底提示loadCompletedTextstring

加载全部数据后的提示说明,内容为空时则不显示该提示

示例:""

显示加载状态isSetLoadingboolean

是否开启数据列表的加载状态,默认显示

默认值:true

显示异常状态isSetStatusboolean

是否开启数据列表的异常状态,默认不显示

数据加载状态loadingboolean

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

Event Introduction

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

事件名
事件code
事件出参 event.detail
适用情况
说明
查询为空queryEmpty兼容三端

数据查询为空时触发

查询成功querySuccess兼容三端

数据查询成功时触发

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

    组件内部抛出的错误信息

    • requestid: string请求 id

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

    • message: string错误提示信息
    • code: string错误码
    • original: 原始错误
兼容三端

数据查询失败时触发

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

    分页信息

    • pageNo: number
    • pageSize: number
兼容三端

分页变化

Property API

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

只读属性名
属性标识
类型
说明
列表记录recordsarray

列表记录

记录总条数totalnumber

记录总条数

页码pageNonumber

当前页码

每页大小pageSizenumber

每页大小

错误信息errorobject

组件内部抛出的错误信息

数据源协议版本dataSourceVersionstring

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

Method API

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

方法名
方法标识
参数
方法说明
刷新refreshstring刷新方式 默认值:refreshFromStart 可选值:refreshFromStart(刷新并回到第1页) refreshKeepPage(刷新当前页)

-

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

-

Application Example

The following example shows the model user list:

1. Add a data container

image-20221024211426230

2. Select data source

Data sources support data models and APIs.

image-20221024205037841

3. Drag the component into the data list, then click to bind the field interface and select data.

image-20221024205548537

4. Bind the component to the data field to display user information

image-20221024210014699

Thus, the user list query feature is now complete! The full implementation is as follows: img

Frequently Asked Questions

When using data container components, must other components be placed inside them?

The Data Container is the core component for page-data interaction, capable of directly querying and displaying data. On our platform, multiple data container components are available, such as ListView, DataView, WdForm, and WdTable.

The Data Container enables deep integration of data and page components. This greatly simplifies data operation processes. In addition to providing data, the Data Container also supports common page interaction features, such as pagination loading, loading status, and error prompts.

When using data containers, if a component relies on data returned by the data container, it is recommended to place the component inside the data container component. For example, to display an image from a specific field in a data detail, it is better to place the component inside the corresponding data container. This way, the data container can automatically handle loading states, loading failures, etc., without needing to worry about rendering timing.

If you only need to use the data container to obtain data without performing UI interactions, you can directly use the Query function to query data.

How to display Chinese labels for common option sets in data containers

Common option sets now support querying values by key. For usage, refer to the documentation: https://cloud.tencent.com/document/product/1301/95807

How do you refresh other components when an event is triggered?

When you need to refresh other components upon an event trigger, bind a variable to the target component's property, for example by referencing this variable in a filter parameter expression. Then change the variable's value in the triggering event to update the corresponding target component's content.

How to Get Selected Row Data When Checkboxes Are Added to the ListView

To obtain the multi-selected data in the data list, you can bind a custom method to the checkbox's change event. First, create a page array variable, such as selectedIds. In the custom method, you can process the data based on the selection state:

  1. When a checkbox is selected, add the current row's data to the selectedIds array.
  2. When a checkbox is deselected, remove the current row's data from the selectedIds array.

It is recommended to pass the current row's data identifier (such as _id) as a parameter to the custom method when binding it, to facilitate processing the selected row's data.