list

权限列表
子组件
属性
事件
样式
方法
示例

列表包含一系列相同宽度的列表项。适合连续、多行呈现同类数据，例如图片和文本。

权限列表

无

子组件

属性

名称	类型	默认值	必填	描述
scrollpage	boolean	false	否	设置为true时，将 list 顶部页面中非 list 部分随 list 一起滑出可视区域，当list方向为row时，不支持此属性。
cachedcount	number	0	否	长列表延迟加载时list-item最少缓存数量。可视区域外缓存的list-item数量少于该值时，会触发requestitem事件。
scrollbar	string	off	否	侧边滑动栏的显示模式（当前只支持纵向）： off：不显示。 auto：按需显示(触摸时显示，2s后消失)。 on：常驻显示。
scrolleffect	string	spring	否	滑动效果，目前支持如下滑动效果： spring：弹性物理动效，滑动到边缘后可以根据初始速度或通过触摸事件继续滑动一段距离，松手后回弹。 fade：渐隐物理动效，滑动到边缘后展示一个波浪形的渐隐，根据速度和滑动距离的变化渐隐也会发送一定的变化。 no：滑动到边缘后无效果。
indexer	boolean \| Array<string>	false	否	是否展示侧边栏快速字母索引栏。设置为true或者自定义索引时，索引栏会显示在列表右边界处。示例： "indexer" : "true"表示使用默认字母索引表。 "indexer" : "false"表示无索引。 "indexer" : ["#", "A", ".", "E", ".", "P", "Q", "R", "S", "T", "U", "V", "W", "X", "Y", "Z"]表示自定义索引表。自定义时"#"必须要存在。说明： indexer属性生效需要flex-direction属性配合设置为column，且columns属性设置为1。点击索引条进行列表项索引需要list-item子组件配合设置相应的section属性。
indexermulti⁵⁺	boolean	false	否	是否开启索引条多语言功能。 indexer为false时不生效。
indexerbubble⁵⁺	boolean	true	否	是否开启索引切换的气泡提示。 indexer为false时不生效。
divider⁵⁺	boolean	false	否	item是否自带分隔线。其样式参考样式列表的divider-color、divider-height、divider-length、divider-origin。
shapemode	string	default	否	侧边滑动栏的形状类型。 default：不指定，跟随主题； rect：矩形； round：圆形。
updateeffect	boolean	false	否	用于设置当list内部的item发生删除或新增时是否支持动效。 false：新增删除item时无过渡动效。 true：新增删除item时播放过程动效。
chainanimation⁵⁺	boolean	false	否	用于设置当前list是否启用链式联动动效，开启后列表滑动以及顶部和底部拖拽时会有链式联动的效果。链式联动效果：list内的list-item间隔一定距离，在基本的滑动交互行为下，主动对象驱动从动对象进行联动，驱动效果遵循弹簧物理动效。 false：不启用链式联动 true：启用链式联动说明：不支持动态修改。如同时配置了indexer，链式动效不生效。如配置了链式动效，list-item的sticky不生效。
initialindex	number	0	否	用于设置当前List初次加载时视口起始位置显示的item，默认为0，即显示第一个item，如设置的序号超过了最后一个item的序号，则设置不生效，当同时设置了initialoffset属性时，当前属性不生效。当indexer为true或者scrollpage为true时，不生效。
initialoffset	<length>	0	否	用于设置当前List初次加载时视口的起始偏移量，偏移量无法超过当前List可滑动的范围，如果超过会被截断为可滑动范围的极限值。当indexer为true或者scrollpage为true时，不生效。
selected⁵⁺	string	-	否	指定当前列表中被选中激活的项，可选值为list-item的section属性值。
id	string	-	否	组件的唯一标识。
style	string	-	否	组件的样式声明。
class	string	-	否	组件的样式类，用于引用样式表。
ref	string	-	否	用来指定指向子元素或子组件的引用信息，该引用将注册到父组件的$refs 属性对象上。
disabled	boolean	false	否	当前组件是否被禁用，在禁用场景下，组件将无法响应用户交互。
data	string	-	否	给当前组件设置data属性，进行相应的数据存储和读取。

事件

名称	参数	描述
indexerchange⁵⁺	{ local: booleanValue }	多语言索引条切换事件，仅当indexer属性为true，indexermulti为true时生效。booleanValue可能值为true或者false： true: 当前展示本地索引。 false: 当前展示字母索引。
scroll	{ scrollX: scrollXValue, scrollY: scrollYValue, scrollState: stateValue }	列表滑动的偏移量和状态回调。 stateValue: 0表示列表滑动已经停止。 stateValue: 1表示列表正在用户触摸状态下滑动。 stateValue: 2表示列表正在用户松手状态下滑动。
scrollbottom	-	当前列表已滑动到底部位置。
scrolltop	-	当前列表已滑动到顶部位置。
scrollend	-	列表滑动已经结束。
scrolltouchup	-	手指已经抬起且列表仍在惯性滑动。
requestitem	-	请求创建新的list-item。长列表延迟加载时，可视区域外缓存的list-item数量少于cachedcount时，会触发该事件。
touchstart	TouchEvent	手指刚触摸屏幕时触发该事件。
touchmove	TouchEvent	手指触摸屏幕后移动时触发该事件。
touchcancel	TouchEvent	手指触摸屏幕中动作被打断时触发该事件。
touchend	TouchEvent	手指触摸结束离开屏幕时触发该事件。
click	-	点击动作触发该事件。
longpress	-	长按动作触发该事件。
swipe⁵⁺	SwipeEvent	组件上快速滑动后触发。

样式

名称	类型	默认值	必填	描述
divider-color⁵⁺	<color>	transparent	否	item分隔线颜色，仅当list的divider属性为true时生效。
divider-height⁵⁺	<length>	1	否	item分隔线高度，仅当list的divider属性为true时生效。
divider-length⁵⁺	<length>	主轴宽度	否	item分隔线长度，不设置时最大长度为主轴宽度，具体长度取决于divider-origin，仅当list的divider属性为true时生效。
divider-origin⁵⁺	<length>	0	否	item分隔线相对于item主轴起点位置的偏移量，仅当list的divider属性为true时生效。
flex-direction	string	column	否	设置flex容器主轴的方向，指定flex项如何放置在flex容器中，可选值为： column：主轴为纵向。 row：主轴为横向。其他组件默认值为row，在list组件中默认值为column。
columns	number	1	否	list交叉轴方向的显示列数，默认为1列。说明：设置多列时，在list交叉轴上进行均分，每一列大小相同。
align-items	string	stretch	否	list每一列交叉轴上的对齐格式，可选值为： stretch：弹性元素被在交叉轴方向被拉伸到与容器相同的高度或宽度。 flex-start：元素向交叉轴起点对齐。 flex-end：元素向交叉轴终点对齐。 center：元素在交叉轴居中。说明： align-items样式作用在每一列的子元素上，列与列之间采用均分方式布局。
item-extent	<length> \| <percentage>	-	否	设置内部item为固定大小，设置为百分比格式时，指相对于list的视口主轴方向长度的百分比。
fade-color	<color>	grey	否	设置渐隐物理动效的颜色。当滑动效果设置为渐隐物理动效时生效。
width	<length> \| <percentage>	-	否	设置组件自身的宽度。缺省时使用元素自身内容需要的宽度。
height	<length> \| <percentage>	-	否	设置组件自身的高度。缺省时使用元素自身内容需要的高度。
padding	<length> \| <percentage>⁵⁺	0	否	使用简写属性设置所有的内边距属性。该属性可以有1到4个值：指定一个值时，该值指定四个边的内边距。指定两个值时，第一个值指定上下两边的内边距，第二个指定左右两边的内边距。指定三个值时，第一个指定上边的内边距，第二个指定左右两边的内边距，第三个指定下边的内边距。指定四个值时分别为上、右、下、左边的内边距（顺时针顺序）。
padding-[left\|top\|right\|bottom]	<length> \| <percentage>⁵⁺	0	否	设置左、上、右、下内边距属性。
padding-[start\|end]	<length> \| <percentage>⁵⁺	0	否	设置起始和末端内边距属性。
margin	<length> \| <percentage>⁵⁺	0	否	使用简写属性设置所有的外边距属性，该属性可以有1到4个值。只有一个值时，这个值会被指定给全部的四个边。两个值时，第一个值被匹配给上和下，第二个值被匹配给左和右。三个值时，第一个值被匹配给上, 第二个值被匹配给左和右，第三个值被匹配给下。四个值时，会依次按上、右、下、左的顺序匹配 (即顺时针顺序)。
margin-[left\|top\|right\|bottom]	<length> \| <percentage>⁵⁺	0	否	设置左、上、右、下外边距属性。
margin-[start\|end]	<length> \| <percentage>⁵⁺	0	否	设置起始和末端外边距属性。
border	-	0	否	使用简写属性设置所有的边框属性，包含边框的宽度，样式，颜色属性，顺序设置为border-width、border-style、border-color，不设置时，各属性值为默认值。
border-style	string	solid	否	使用简写属性设置所有边框的样式，可选值为： dotted：显示为一系列圆点，圆点半径为border-width的一半。 dashed：显示为一系列短的方形虚线。 solid：显示为一条实线。
border-[left\|top\|right\|bottom]-style	string	solid	否	分别设置左、上、右、下四个边框的样式，可选值为dotted、dashed、solid。
border-[left\|top\|right\|bottom]	-	-	否	使用简写属性设置对应位置的边框属性，包含边框的宽度，样式，颜色属性，顺序设置为border-width、border-style、border-color，不设置的值为默认值。
border-width	<length>	0	否	使用简写属性设置元素的所有边框宽度，或者单独为各边边框设置宽度。
border-[left\|top\|right\|bottom]-width	<length>	0	否	分别设置左、上、右、下四个边框的宽度。
border-color	<color>	black	否	使用简写属性设置元素的所有边框颜色，或者单独为各边边框设置颜色。
border-[left\|top\|right\|bottom]-color	<color>	black	否	分别设置左、上、右、下四个边框的颜色。
border-radius	<length>	-	否	border-radius属性是设置元素的外边框圆角半径。设置border-radius时不能单独设置某一个方向的border-[left\|top\|right\|bottom]-width，border-[left\|top\|right\|bottom]-color ，border-[left\|top\|right\|bottom]-style，如果要设置color、width和style，需要将四个方向一起设置（border-width、border-color、border-style）。
border-[top\|bottom]-[left\|right]-radius	<length>	-	否	分别设置左上，右上，右下和左下四个角的圆角半径。
background	<linear-gradient>	-	否	仅支持设置渐变样式，与background-color、background-image不兼容。
background-color	<color>	-	否	设置背景颜色。
background-image	string	-	否	设置背景图片。与background-color、background不兼容；支持本地图片资源地址。示例： background-image: url("/common/background.png")
background-size	string <length> <length> <percentage> <percentage>	auto	否	设置背景图片的大小。 string可选值： contain：把图像扩展至最大尺寸，以使其高度和宽度完全适用内容区域。 cover：把背景图像扩展至足够大，以使背景图像完全覆盖背景区域；背景图像的某些部分也许无法显示在背景定位区域中。 auto：保持原图的比例不变。 length值参数方式：设置背景图像的高度和宽度。第一个值设置宽度，第二个值设置高度。如果只设置一个值，则第二个值会被设置为 "auto"。百分比参数方式：以父元素的百分比来设置背景图像的宽度和高度。第一个值设置宽度，第二个值设置高度。如果只设置一个值，则第二个值会被设置为 "auto"。
background-repeat	string	repeat	否	针对重复背景图像样式进行设置，背景图像默认在水平和垂直方向上重复。 repeat：在水平轴和竖直轴上同时重复绘制图片。 repeat-x：只在水平轴上重复绘制图片。 repeat-y：只在竖直轴上重复绘制图片。 no-repeat：不会重复绘制图片。
background-position	string string <length> <length> <percentage> <percentage>	0px 0px	否	关键词方式：如果仅规定了一个关键词，那么第二个值为"center"。两个值分别定义水平方向位置和竖直方向位置。 left：水平方向上最左侧。 right：水平方向上最右侧。 top：竖直方向上最顶部。 bottom：竖直方向上最底部。 center：水平方向或竖直方向上中间位置。 length值参数方式：第一个值是水平位置，第二个值是垂直位置。左上角是 0 0。单位是像素 (0px 0px) 。如果仅规定了一个值，另外一个值将是50%。百分比参数方式：第一个值是水平位置，第二个值是垂直位置。左上角是 0% 0%。右下角是 100% 100%。如果仅规定了一个值，另外一个值为50%。可以混合使用<percentage>和<length>
opacity	number	1	否	元素的透明度，取值范围为0到1，1表示为不透明，0表示为完全透明。
display	string	flex	否	确定一个元素所产生的框的类型，可选值为： flex：弹性布局。 none：不渲染此元素。
visibility	string	visible	否	是否显示元素所产生的框。不可见的框会占用布局（将'display'属性设置为'none'来完全去除框），可选值为： visible：元素正常显示。 hidden：隐藏元素，但是其他元素的布局不改变，相当于此元素变成透明。说明： visibility和display样式都设置时，仅display生效
flex	-	-	否	规定当前组件如何适应父组件中的可用空间。 flex可以指定1个，2个⁵⁺或3个⁵⁺值。单值语法：一个无单位数：用来设置组件的flex-grow 一个有效的宽度值⁵⁺：用来设置组件的flex-basis 双值语法⁵⁺：第一个值必须是无单位数，用来设置组件的flex-grow。第二个值是以下之一：一个无单位数：用来设置组件的flex-shrink 一个有效的宽度值：用来设置组件的flex-basis 三值语法⁵⁺：第一个值必须是无单位数，用来设置组件的flex-grow；第二个值必须是无单位数，用来设置组件的flex-shrink；第三个值必须是一个有效的宽度值，用来设置组件的flex-basis。说明：仅父容器为<div>、<list-item>、<tabs>、<refresh>、<stepper-item>⁵⁺时生效。
flex-grow	number	0	否	设置组件的拉伸样式，指定父组件容器主轴方向上剩余空间（容器本身大小减去所有flex子元素占用的大小）的分配权重。0为不伸展。说明：仅父容器为<div>、<list-item>、<tabs>、<refresh>、<stepper-item>⁵⁺时生效。
flex-shrink	number	1	否	设置组件的收缩样式，元素仅在默认宽度之和大于容器的时候才会发生收缩，0为不收缩。说明：仅父容器为<div>、<list-item>、<tabs>、<refresh>、<stepper-item>⁵⁺时生效。
flex-basis	<length>	-	否	设置组件在主轴方向上的初始大小。说明：仅父容器为<div>、<list-item>、<tabs>、<refresh>、<stepper-item>⁵⁺时生效。
position	string	relative	否	设置元素的定位类型，不支持动态变更。 fixed：相对与整个界面进行定位。 absolute：相对于父元素进行定位。 relative：相对于其正常位置进行定位。说明： absolute属性仅在父容器为<div>、<stack>时生效。
[left\|top \|right\|bottom]	<length>	-	否	left\|top \|right\|bottom需要配合position样式使用，来确定元素的偏移位置。 left属性规定元素的左边缘。该属性定义了定位元素左外边距边界与其包含块左边界之间的偏移。 top属性规定元素的顶部边缘。该属性定义了一个定位元素的上外边距边界与其包含块上边界之间的偏移。 right属性规定元素的右边缘。该属性定义了定位元素右外边距边界与其包含块右边界之间的偏移。 bottom属性规定元素的底部边缘。该属性定义了一个定位元素的下外边距边界与其包含块下边界之间的偏移。

方法

名称	参数	描述
scrollTo	{ index: number(指定位置) }	list滑动到指定index的item位置。
scrollTop	{ smooth: boolean }	smooth缺省为false，表示直接滚动到顶部。 smooth为true，表示平滑滚动到顶部。
scrollBottom	{ smooth: boolean }	smooth缺省为false，表示直接滚动到底部。 smooth为true，表示平滑滚动到底部。
scrollPage	{ reverse: boolean, smooth: boolean }	reverse缺省值为false，表示下一页，无完整页则滚动到底部。 reverse为true，表示上一页，无完整页则滚动到顶部。 smooth缺省值为false，表示直接滚动一页。 smooth为true，表示平滑滚动一页。
scrollArrow	{ reverse: boolean, smooth: boolean }	reverse缺省值为false，表示向底部方向滑动一段距离，无足够距离则滚动到底部。 reverse为true，表示向顶部方向滑动一段距离，无足够距离则滚动到顶部。 smooth缺省值为false，表示直接滚动。 smooth为true，表示平滑滚动。
collapseGroup	{ groupid: string }	收拢指定的group。 groupid：需要收拢的group的id。当groupid未指定时收拢所有的group。
expandGroup	{ groupid: string }	展开指定的group。 groupid：需要展开的group的id。当groupid未指定时展开所有的group。
currentOffset	-	返回当前滑动的偏移量。返回值类型是Object，返回值说明请见表2。

表 1 ListScrollByOptions

名称	类型	是否必选	默认值	备注
dx	number	否	0	水平方向滑动的偏移量，单位px。
dy	number	否	0	垂直方向滑动的偏移量，单位px。
smooth	boolean	否	true	列表位置跳转时是否有滑动动画。

表 2 currentOffset返回对象属性说明

名称	类型	备注
x	number	当前x轴滑动偏移量，单位px。
y	number	当前y轴滑动偏移量，单位px。

示例

<!-- index.hml -->
<div class="container">
  <list class="todo-wraper">
    <list-item for="{{todolist}}" class="todo-item">
      <text class="todo-title">{{$item.title}}</text>
      <text class="todo-title">{{$item.date}}</text>
    </list-item>
  </list>
</div>

// index.js
export default {
  data: {
    todolist: [{
      title: '刷题',
      date: '2021-12-31 10:00:00',
    }, {
      title: '看电影',
      date: '2021-12-31 20:00:00',
    }],
  },
}

/* index.css */
.container {
  display: flex;
  justify-content: center;
  align-items: center;
  left: 0px;
  top: 0px;
  width: 454px;
  height: 454px;
}
.todo-wraper {
  width: 454px;
  height: 300px;
}
.todo-item {
  width: 454px;
  height: 80px;
  flex-direction: column;
}
.todo-title {
  width: 454px;
  height: 40px;
  text-align: center;
}