跳到主要内容
List
列表用于显示一些同类型的数据,由多个项目列表组成,每个列表项可以包含一段文字、图片、链接等内容,也可以承载按钮进行交互。

示例

两种布局模式

listlayout支持两种布局模式:

  • fixed,固定操作区域。该模式类似表格,列表底部有固定的分页栏和操作区域(actions),更符合PC端的用户习惯,因此PC默认使用该模式。
  • auto,无固定操作区域,可无限滚动。当前布局模式没有固定的底部区域,分页通过触底上拉触发,不支持操作区域(actions),但支持下拉刷新和虚拟滚动。交互方式移动端比较常用,因此Mobile默认使用该模式。
    PCPhonePad
    <page>
    <module title="固定模式,fixed" height="300px">
    <list data="{{listData}}" pageable layout="fixed">
    <module :title="cellData.data.name">
    <form type="info">
    <item label="日期" colspan="1" value="{{cellData.data.date}}"></item>
    <item label="地址" colspan="5" value="{{cellData.data.address}}"></item>
    </form>
    </module>
    <actions>
    <button text="按钮1"></button>
    <button text="按钮2"></button>
    </actions>
    </list>
    </module>

    <module title="无限滚动模式,auto" height="300px">
    <list data="{{listData}}" layout="auto">
    <module :title="cellData.data.name">
    <form type="info">
    <item label="日期" colspan="1" value="{{cellData.data.date}}"></item>
    <item label="地址" colspan="5" value="{{cellData.data.address}}"></item>
    </form>
    </module>
    </list>
    </module>
    </page>



    export default XPage({
    data: {
    listData: [{
    date: '2016-05-02',
    name: '王小虎',
    address: '上海市普陀区金沙江路 1518 弄'
    }, {
    date: '2016-05-04',
    name: '王小虎',
    address: '上海市普陀区金沙江路 1517 弄'
    }, {
    date: '2016-05-01',
    name: '王小虎',
    address: '上海市普陀区金沙江路 1519 弄'
    }, {
    date: '2016-05-03',
    name: '王小虎',
    address: '上海市普陀区金沙江路 1516 弄'
    }]
    }
    });




高度设置

列表默认高度是100%撑满容器的,当列表内容超出最大高度会在列表内部自动出现滚动条。如想取消列表内部滚动条,随着容器滚动,请给列表设置height="auto",此时list的高度由内容撑高。

注意

height="auto"时,高度由内容撑高,意味着列表内部无法产生滚动条,和列表内部滚动条相关的功能如:模板布局为auto时的下拉刷新,滑动到底翻页,虚拟滚动功能将无法使用。

PCPhonePad
<page>
<module title="默认100%" height="300px">
<list data="{{listData}}" pageable layout="fixed">
<module :title="cellData.data.name">
<form type="info">
<item label="日期" colspan="1" value="{{cellData.data.date}}"></item>
<item label="地址" colspan="5" value="{{cellData.data.address}}"></item>
</form>
</module>
<actions>
<button text="按钮1"></button>
<button text="按钮2"></button>
</actions>
</list>
</module>
<module title="内容撑高,auto" height="300px">
<list data="{{listData}}" layout="auto" height="auto">
<module :title="cellData.data.name">
<form type="info">
<item label="日期" colspan="1" value="{{cellData.data.date}}"></item>
<item label="地址" colspan="5" value="{{cellData.data.address}}"></item>
</form>
</module>
</list>
</module>
<module title="自定义高度" height="300px">
<list data="{{listData}}" layout="auto" height="200px">
<module :title="cellData.data.name">
<form type="info">
<item label="日期" colspan="1" value="{{cellData.data.date}}"></item>
<item label="地址" colspan="5" value="{{cellData.data.address}}"></item>
</form>
</module>
</list>
</module>
</page>



export default XPage({
data: {
listData: [{
date: '2016-05-02',
name: '王小虎',
address: '上海市普陀区金沙江路 1518 弄'
}, {
date: '2016-05-04',
name: '王小虎',
address: '上海市普陀区金沙江路 1517 弄'
}, {
date: '2016-05-01',
name: '王小虎',
address: '上海市普陀区金沙江路 1519 弄'
}, {
date: '2016-05-03',
name: '王小虎',
address: '上海市普陀区金沙江路 1516 弄'
}]
}
});




内置模板

一般来说list模板默认需要用户自己定义,list仅作为壳子实现渲染等其他操作。但该组件提供了内置模板,目前仅支持一种,需要设置mode开启,和结合list-item子组件一起实现。

PCPhonePad
<page>
<list data="{{listData}}"
height="300px"
layout="auto"
mode
modeConfig="{{modeConfig}}"
>
<list-item data="{{cellData.data}}">
<actions>
<button text="按钮1"></button>
<button text="按钮2"></button>
<button text="按钮3"></button>
</actions>
</list-item>
</list>
</page>


let listData = [];
for (var i = 0; i < 30; i++) {
listData.push({
img: 'https://fuss10.elemecdn.com/d/e6/c4d93a3805b3ce3f323f7974e6f78jpeg.jpeg',
name: '标题' + i,
tags: [{label: '标签', status: 'blue'}, {label: '标签1', status: 'purple'}],
status: {label: '成功', status: 'success'},
description: '我是描述信息' + i,
});
}


export default XPage({
data: {
listData: listData,
modeConfig: {
avatar: true,
defaultProps: {title: 'name'}
}
}
});


行操作

selectable设置后可开启行选择功能。

PCPhonePad
<page>
<module title="单选" height="300px">
<list x="list"
data="{{listData}}"
layout="auto"
selectable
mode
modeConfig="{{modeConfig}}"
bind-selected="selectedHandler"
>
<list-item data="{{cellData.data}}">
<actions>
<button text="按钮1"></button>
<button text="按钮2"></button>
<button text="按钮3"></button>
</actions>
</list-item>
</list>
</module>

<module title="多选" height="300px">
<list x="mutipleList"
data="{{listData}}"
selectable="{{multiple:true}}"
pageable
layout="fixed"
bind-selected="selectedHandler"
bind-unselected="unselectedHandler"
>
<module :title="cellData.data.name">
<form type="info">
<item label="日期" colspan="1" value="{{cellData.data.date}}"></item>
<item label="地址" colspan="5" value="{{cellData.data.address}}"></item>
</form>
</module>
<actions>
<button text="按钮1"></button>
<button text="按钮2"></button>
</actions>
</list>
</module>
</page>


let listData = [];
for (var i = 0; i < 30; i++) {
listData.push({
img: 'https://fuss10.elemecdn.com/d/e6/c4d93a3805b3ce3f323f7974e6f78jpeg.jpeg',
name: '标题' + i,
tags: [{label: '标签', status: 'blue'}, {label: '标签1', status: 'purple'}],
status: {label: '成功', status: 'success'},
description: '我是描述信息' + i,
});
}


export default XPage({
data: {
listData: listData,
modeConfig: {
avatar: true,
defaultProps: {title: 'name'}
}
},
show(){
this.getComponent('list').select(1);
this.getComponent('mutipleList').select([0]);
},
selectedHandler(data){
console.info('selected',data);
},
unselectedHandler(data){
console.info('unselected',data);
},
});


远程获取数据

设置ajax后,组件内部会完成接口调用和数据渲染,如果对请求的入参和接口返回的数据结构有修改需求,可分别在beforeRequestbeforeRender中处理并返回修改后的数据。

注意:由于接口调用逻辑组件全部内置,对接口返回的数据结构有一定要求,具体可看beforeRender的介绍,如接口返回不满足,请在beforeRender中处理并返回修改后的数据。

PCPhonePad
<page class="demo-box">

<module title="常规ajax" height="300px">
<list
x="list"
:pageable="{pageSize:10}"
ajax="{{ajax}}"
beforeRequest="{{beforeRequest}}"
>
<module :title="cellData.data.name">
<form type="info">
<item label="日期" colspan="1" value="{{cellData.data.date}}"></item>
<item label="地址" colspan="5" value="{{cellData.data.address}}"></item>
</form>
</module>
</list>
</module>

<module title="ajax为Promise对象" height="300px">
<head>
<form type="search" confirm-button bindconfirm="search">
<item label="姓名" node="input" name="name"></item>
<item label="学历" node="select" data="{{educations}}" name="education"></item>
</form>
</head>
<list
x="list"
:pageable="{pageSize:10}"
ajax="{{fetchData}}"
beforeRequest="{{beforeRequest}}"
>
<module :title="cellData.data.name">
<form type="info">
<item label="日期" colspan="1" value="{{cellData.data.date}}"></item>
<item label="地址" colspan="5" value="{{cellData.data.address}}"></item>
</form>
</module>
</list>
</module>
</page>




export default XPage({
props: {
ajaxIsFunc: {
type: Boolean,
default: false,
}
},

data: {
educations: [],
ajax:{
url: '//testapi-nodedmallos.dmall.com/cabinx/pcapi/table/data',
}
},

show() {
this.init();
},

init() {
this.setData({
educations: [
{label: '全部', value: ''}, {label: '大专', value: '大专'}, {label: '本科', value: '本科'}
],
});
},

search(value) {
const list = this.getComponent('list');

list.query({params: value});
},

handleEdit(name) {
CabinX.alert({
title: '编辑',
text: `${name}Edit`,
});
},

handleOper(name) {
CabinX.alert({
title: '操作',
text: `${name}Oper`
});
},

/**
* 接口请求前,自定义入参
* @param {Object} args
* @param {Array} sorts 表格列排序字段
*/
beforeRequest(params, sorts) {
let newParams = params;

// 编辑参数
newParams.custom = '大幅度发';

return newParams;
},

fetchData(params) {
return CabinX.ajax({withCredentials: true}).get({
url: '//testapi-nodedmallos.dmall.com/cabinx/pcapi/table/data',
params,
});
},
});



下拉刷新

layout="auto"时,配置pullrefresh后,列表滚动到顶部后,继续下拉会开启下拉刷新动效,释放后会触发配置的refresh事件,对数据的刷新修改逻辑请在该函数中自行定义,修改完毕后需手动通过stopPullRefresh()关闭下拉动效。

PCPhonePad
<page>
<list x="list"
data="{{listData}}"
height="300px"
layout="auto"
pullrefresh
@refresh="onRefresh">
<module :title="cellData.data.name">
<form type="info">
<item label="日期" colspan="1" value="{{cellData.data.date}}"></item>
<item label="地址" colspan="5" value="{{cellData.data.address}}"></item>
</form>
</module>
</list>
</page>

export default XPage({
data: {
listData: [{
date: '2016-05-02',
name: '王小虎',
address: '上海市普陀区金沙江路 1518 弄'
}, {
date: '2016-05-04',
name: '王小虎',
address: '上海市普陀区金沙江路 1517 弄'
}, {
date: '2016-05-01',
name: '王小虎',
address: '上海市普陀区金沙江路 1519 弄'
}, {
date: '2016-05-03',
name: '王小虎',
address: '上海市普陀区金沙江路 1516 弄'
}]
},
onRefresh() {
setTimeout(() => {
// 接口调用结束后,手动关闭下拉刷新动效
this.getComponent('list').stopPullRefresh();
}, 1000);
},
});



滚动触底翻页

layout="auto"时,配置ajax后,列表会自动开启远程拉取数据,配置pageable后,列表滚动到底部自动翻页,否则仅拉取第一页的数据。

PCPhonePad
<page>
<list x="list"
height="300px"
layout="auto"
:pageable="{pageSize:10}"
:ajax="ajax"
>
<module :title="cellData.data.name">
<form type="info">
<item label="日期" colspan="1" value="{{cellData.data.date}}"></item>
<item label="地址" colspan="5" value="{{cellData.data.address}}"></item>
</form>
</module>
</list>
</page>


export default XPage({
data: {
ajax: '//testapi-nodedmallos.dmall.com/cabinx/pcapi/table/data',
},
});


虚拟滚动

layout="auto"时,配置virtualScroll后,列表开启虚拟滚动功能。由于虚拟滚动功能对设备性能要求较高,建议大数据展示,且每行模板展示的内容较少时使用,否则滚动时会有较明显的卡顿和白屏效果。

虚拟滚动请分别结合itemSize(提前知道每行高度的情况使用)和minItemSize(无法提前得知每行高度,可设置个每行的最小高度)属性一起使用。

PCPhonePad
<page>
<list x="list"
height="300px"
layout="auto"
:pageable="{pageSize:10}"
:ajax="ajax"
virtualScroll
>
<module :title="cellData.data.name">
<form type="info">
<item label="日期" colspan="1" value="{{cellData.data.date}}"></item>
<item label="地址" colspan="5" value="{{cellData.data.address}}"></item>
</form>
</module>
</list>
</page>



export default XPage({
data: {
ajax: '//testapi-nodedmallos.dmall.com/cabinx/pcapi/table/data',
},
});



最佳实践

资源列表

资源列表显示相同类型对象的集合,如产品、订单、客户。资源列表的主要工作是帮助用户找到一个对象,并导航到它的整页表示。

PCPhonePad
<page>
<module height="300px">
<list data="{{listData}}"
layout="auto"
mode
selectable="{{multiple:true}}"
modeConfig="{{modeConfig}}"
>
<list-item data="{{cellData.data}}">
<actions>
<button text="{{cellData.data.buttonText}}"></button>
</actions>
</list-item>
</list>
</module>
</page>


export default XPage({
data: {
listData: [
{
img: 'https://fuss10.elemecdn.com/d/e6/c4d93a3805b3ce3f323f7974e6f78jpeg.jpeg',
name: '1000000485761',
tags: [{label: '自提', status: 'blue'}],
status: {label: '待拣货', status: 'info'},
description: '预计自提时间 :2023-05-06 12:00:00 pm-01:00:00 pm | 1件商品',
buttonText:'分配拣货员',
},
{
img: 'https://fuss10.elemecdn.com/d/e6/c4d93a3805b3ce3f323f7974e6f78jpeg.jpeg',
name: '1000000485761',
tags: [{label: '配送', status: 'blue'}],
status: {label: '已超时', status: 'error'},
description: '预计送达时间 :2023-05-05 03:00:00 pm-04:00:00 pm | 1件商品 | 配送员:履约2号 秦资鸿',
buttonText:'拒收入站',
},
{
img: 'https://fuss10.elemecdn.com/d/e6/c4d93a3805b3ce3f323f7974e6f78jpeg.jpeg',
name: '1000000485761',
tags: [{label: '自提', status: 'blue'}],
status: {label: '拣货中', status: 'warning'},
description: '预计自提时间 :2023-05-05 05:00:00 pm-06:00:00 pm | 2件商品 | 拣货员:履约 秦',
buttonText:'完成拣货',
},

],
modeConfig: {
avatar: true,
defaultProps: {title: 'name'}
}
}
});


配置列表

PCPhonePad
<page>
<module height="300px">
<list data="{{listData}}"
layout="auto"
mode
modeConfig="{{modeConfig}}"
>
<list-item data="{{cellData.data}}">
<actions>
<button text="设置"></button>
</actions>
</list-item>
</list>
</module>
</page>


export default XPage({
data: {
listData: [
{
name: '商城主题',
description: '系统已默认商城的主题风格,您可以前往前往进行个性化设置',
},
{
name: '商城信息',
description: '填写商城信息,确认经营时区、货币及长度&重量单位',
},
{
name: '发件邮箱',
description: '当前向用户发件营销、订单相关邮件的发件邮箱为shdh@dmall.com,如需使用您公司邮箱,请前往自行设置',
},

],
modeConfig: {
avatar: true,
defaultProps: {title: 'name'}
}
}
});


Attributes

属性说明类型可选值默认值版本
layout布局模式,支持固定操作区域模式(fixed)和无限滚动模式(auto)Stringfixed/autoPC:fixed/Mobile:autoPC/Mobile--
data定义列表显示数据(请勿和ajax同时使用),mode开启时需要配置的值参考下面dataArray/String----PC/Mobile--
height列表高度String100%、auto、自定义px高度100%PC/Mobile--
beforeRequest该回调方法用于修改接口的传参格式,默认格式参考“beforeRequest的入参”Function----PC/Mobile--
beforeRender该回调方法用于将接口数据转换成表格渲染数据 转换成的标准格式参考“beforeRender的返回值格式”Function----PC/Mobile--
ajax组件调用请求的相关配置string/Object/Function<{url, method(默认get,可选:get、post), params}>----PC/Mobile--
pageable是否开启 异步 分页,具体配置参考 pageableBoolean/ObjectfalsePC/Mobile--
selectable行选择器Boolean/Object单选:selectable=true,多选:selectable.multiple=truefalsePC/Mobile--
autoQuery组件初始化时立即执行ajaxBoolean-truePC/Mobile--
mode开启内置布局模式,需要和子组件x-list-item配合使用Boolean-falsePC--
modeConfig内置布局对应模式的参数配置,详细查看mode-configObject--PC--

Attributes - layout

layout = fixed

layoutfixed时,为固定操作区域模式。 当前模式类似表格,列表底部有固定的分页栏和操作区域(actions),更符合PC端的用户习惯,因此PC默认使用该模式。

layout = auto

layoutauto时,为无限滚动模式,当前布局模式没有固定的底部区域,分页通过触底上拉触发,不支持操作区域(actions),但支持下拉刷新和虚拟滚动。交互方式移动端比较常用,因此Mobile默认使用该模式。

当前模式时支持的属性配置如下表。

属性说明类型可选值默认值版本
pullrefresh是否开启下拉刷新功能,可结合@refresh一起使用达到数据刷新的目的(推荐页面滚动区域仅有list时使用)Boolean--falsePC/Mobile--
virtualScroll是否开启虚拟无限滚动功能,请结合itemSize和minItemSize一起使用(推荐当显示的数据量较大,且每行模板内容较少时使用,注:该功能对设备性能要求较高)Boolean--falsePC/Mobile--
itemSize指定每行固定高度(开启虚拟滚动时可用)Number----PC/Mobile--
minItemSize指定每行最小高度(开启虚拟滚动时可用),一般无法提前得知每行固定高度时使用Number--48PC/Mobile--
fetchData自定义请求数据函数,返回一个Promise对象Function--PC/Mobile--

Attributes - mode

mode为true时(即使用内置模板时)mode-config对象中和data数组中支持的配置分别如下

modeConfig

mode为true时(即使用内置模板时)以下配置有效

属性说明类型可选值默认值版本
layoutlist-item的布局方式StringnormalnormalPC--
avatar是否显示图片部分Boolean--falsePC--
defaultPropsdata中key的映射关系Object--{title: 'title', img: 'img', description: 'description', tags: 'tags', status: 'status'}PC--

data

mode为true时(即使用内置模板时)以下配置有效

属性说明类型可选值默认值版本
title标题String----PC--
img图片地址,当modeConfig.avatar为true时有效string/Object<{lable:String,status:String}>----PC--
description描述信息String----PC--
status有语义的标签,只能展示一个string/Object<{lable:String,status:String}>可通过对象配置,其中label为展示文案;status为标签语义,取值参考基础组件Tag类型为status时的可选项--PC--
tags无语义标签,可展示多个string/Array<{lable:String,status:String}>可通过配置数组展示多个,其中label为展示文案;status为标签颜色,取值参考基础组件Tag类型为normal时的可选项--PC--

ajax配置

属性说明类型可选值默认值版本
ajax如果ajax为string时,表示请求的url 作用与 ajax:{url:'xxx.dmall.com/abc/abc.json'} 相同String----PC/Mobile--
ajax.url请求的urlString----PC/Mobile--
ajax.params请求的参数Object----PC/Mobile--
ajax.methodhttp methodstringget/post--PC/Mobile--
ajax.contentType请求资源MIME类型 注意:由于公司禁止使用options请求,所以可以选值请参考多点研发必知必会中的 跨域问题 章节跨域请求时,Content-Type默认为application/json, browser会发起预检请求(method: options), 由于安全原因公司部分接口禁止options请求,所以预检通过不过会报403,开发过程中发现这种情况,请检查Content-Type是否为允许的三种类型Stringapplication/json、 application/x-www-form-urlencoded、 multipart/form-data、 text/plainapplication/jsonPC/Mobile--

pageable

属性说明类型可选值默认值版本
pageable是否开启异步分页,!!默认不会开启!!,关闭情况下,只会从服务器拉取50条数据Booleantrue/falsefalsePC/Mobile--
pageable.pageSize默认每页条数Number--50PC/Mobile--

beforeRender格式要求

before-render函数需要返回的格式如下。

表格自带的ajax请求返回的数据结构需要满足如下格式(二选一),如果接口无法满足,可在beforeRender函数中手动调整为正确格式。

第一种
{
code:'',//错误码(非必须)
data:{
result:[{},{}],//列表数据
currentPage:1,//当前的页码
pageCount:10,//总页数
totalCount:100,//总数据条数
pageSize:10//每页条数
}

}

第二种
{
data:[{},{},{}],//列表数据
pagination:{
total:100,//总数据条数
per_page:10,//每页条数
current_page:1,//当前的页码
last_page:10//总页数
}
}

Events

名称说明生效条件:layout的值为回调参数版本
refresh开启下拉刷新功能时,下拉释放后触发该事件auto--PC/Mobile--
row-activated--auto/fixed{ activated: String/Number, rowData: Object }PC--
rendered渲染完成回调fixed--PC/Mobile--
selected行选中时触发auto/fixed{ data: Array< CellData >, row: Array< ChangedRowIndex >, selected: Array< SelectedIndex > }PC/Mobile--
unselected行取消选中时触发auto/fixed{ data: Array< CellData >, row: Array< ChangedRowIndex >, selected: Array< SelectedIndex > }PC/Mobile--

Methods

名称说明生效条件:layout的值为入参返回版本
getData获取列表数据auto/fixed--{ data:Array }PC/Mobile--
query在列表配置了ajax时,可使用该方法请求刷新数据,请结合下拉刷新场景使用,需在onRefresh里面调用,调用前后也可根据需要执行其他的逻辑。注:调用query时,不用自己关闭下拉刷新动效,query内部接口请求回来后会自动关闭。auto/fixed入参均是可选,未配置时会默认使用ajax和pageable中的配置。{url:String<请求url>,params:Object<业务请求参数>,pageSize:Number<每页的数据条数>,httpMethod:String}--PC/Mobile--
getPagination获取分页信息auto/fixed----PC/Mobile--
select选中单个或多个行auto/fixedArray<[rowNum,rowNum..]> / Number< rowNum >--PC/Mobile--
unselect取消选中单个或多个行auto/fixedArray<[rowNum,rowNum..]> / Number< rowNum >--PC/Mobile--
selectAll选中全部行,selectable中配置了多选multiple时有效auto/fixed----PC/Mobile--
unselectAll取消选中全部行,selectable中配置了多选multiple时有效auto/fixed----PC/Mobile--
goTop滚动条回到顶部auto----PC/Mobile--
stopPullRefresh关闭下拉刷新动效,需要在refresh回调函数中执行auto----PC/Mobile--