示例
两种布局模式
list
的layout
支持两种布局模式:
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时的下拉刷新,滑动到底翻页,虚拟滚动功能将无法使用。
<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
子组件一起实现。
<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
设置后可开启行选择功能。
<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
后,组件内部会完成接口调用和数据渲染,如果对请求的入参和接口返回的数据结构有修改需求,可分别在beforeRequest
和beforeRender
中处理并返回修改后的数据。
注意:由于接口调用逻辑组件全部内置,对接口返回的数据结构有一定要求,具体可看beforeRender
的介绍,如接口返回不满足,请在beforeRender
中处理并返回修改后的数据。
<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()
关闭下拉动效。
<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
后,列表滚动到底部自动翻页,否则仅拉取第一页的数据。
<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
(无法提前得知每行高度,可设置个每行的最小高度)属性一起使用。
<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',
},
});
最佳实践
资源列表
资源列表显示相同类型对象的集合,如产品、订单、客户。资源列表的主要工作是帮助用户找到一个对象,并导航到它的整页表示。
<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'}
}
}
});
配置列表
<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) | String | fixed/auto | PC:fixed/Mobile:auto | PC/Mobile | -- |
data | 定义列表显示数据(请勿和ajax同时使用),mode开启时需要配置的值参考下面data | Array/String | -- | -- | PC/Mobile | -- |
height | 列表高度 | String | 100%、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 | 是否开启 异步 分页,具体配置参考 pageable | Boolean/Object | false | PC/Mobile | -- | |
selectable | 行选择器 | Boolean/Object | 单选:selectable=true,多选:selectable.multiple=true | false | PC/Mobile | -- |
autoQuery | 组件初始化时立即执行ajax | Boolean | - | true | PC/Mobile | -- |
mode | 开启内置布局模式,需要和子组件x-list-item配合使用 | Boolean | - | false | PC | -- |
modeConfig | 内置布局对应模式的参数配置,详细查看mode-config | Object | - | - | PC | -- |
Attributes - layout
layout = fixed
layout
为fixed
时,为固定操作区域模式。
当前模式类似表格,列表底部有固定的分页栏和操作区域(actions
),更符合PC端的用户习惯,因此PC默认使用该模式。
layout = auto
layout
为auto
时,为无限滚动模式,当前布局模式没有固定的底部区域,分页通过触底上拉触发,不支持操作区域(actions
),但支持下拉刷新和虚拟滚动。交互方式移动端比较常用,因此Mobile默认使用该模式。
当前模式时支持的属性配置如下表。
属性 | 说明 | 类型 | 可选值 | 默认值 | 端 | 版本 |
---|---|---|---|---|---|---|
pullrefresh | 是否开启下拉刷新功能,可结合@refresh一起使用达到数据刷新的目的(推荐页面滚动区域仅有list时使用) | Boolean | -- | false | PC/Mobile | -- |
virtualScroll | 是否开启虚拟无限滚动功能,请结合itemSize和minItemSize一起使用(推荐当显示的数据量较大,且每行模板内容较少时使用,注:该功能对设备性能要求较高) | Boolean | -- | false | PC/Mobile | -- |
itemSize | 指定每行固定高度(开启虚拟滚动时可用) | Number | -- | -- | PC/Mobile | -- |
minItemSize | 指定每行最小高度(开启虚拟滚动时可用),一般无法提前得知每行固定高度时使用 | Number | -- | 48 | PC/Mobile | -- |
fetchData | 自定义请求数据函数,返回一个Promise对象 | Function | - | - | PC/Mobile | -- |
Attributes - mode
mode
为true时(即使用内置模板时)mode-config
对象中和data
数组中支持的配置分别如下
modeConfig
mode
为true时(即使用内置模板时)以下配置有效
属性 | 说明 | 类型 | 可选值 | 默认值 | 端 | 版本 |
---|---|---|---|---|---|---|
layout | list-item的布局方式 | String | normal | normal | PC | -- |
avatar | 是否显示图片部分 | Boolean | -- | false | PC | -- |
defaultProps | data中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 | 请求的url | String | -- | -- | PC/Mobile | -- |
ajax.params | 请求的参数 | Object | -- | -- | PC/Mobile | -- |
ajax.method | http method | string | get/post | -- | PC/Mobile | -- |
ajax.contentType | 请求资源MIME类型 注意:由于公司禁止使用options请求,所以可以选值请参考多点研发必知必会中的 跨域问题 章节跨域请求时,Content-Type默认为application/json, browser会发起预检请求(method: options), 由于安全原因公司部分接口禁止options请求,所以预检通过不过会报403,开发过程中发现这种情况,请检查Content-Type是否为允许的三种类型 | String | application/json、 application/x-www-form-urlencoded、 multipart/form-data、 text/plain | application/json | PC/Mobile | -- |
pageable
属性 | 说明 | 类型 | 可选值 | 默认值 | 端 | 版本 |
---|---|---|---|---|---|---|
pageable | 是否开启异步分页,!!默认不会开启!!,关闭情况下,只会从服务器拉取50条数据 | Boolean | true/false | false | PC/Mobile | -- |
pageable.pageSize | 默认每页条数 | Number | -- | 50 | PC/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/fixed | Array<[rowNum,rowNum..]> / Number< rowNum > | -- | PC/Mobile | -- |
unselect | 取消选中单个或多个行 | auto/fixed | Array<[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 | -- |