文档管理中心
API参考快应用组件list

list

概述

列表视图容器。

使用限制

展开

限制条件

说明

适用终端

手机、平板、智慧屏、车机

适用区域

全球

子组件

仅支持 <list-item> 子组件。

属性

除了支持 通用属性 以外,还支持如下属性。

展开

名称

类型

默认值

是否必填

描述

scrollpage

boolean

false

是否将list顶部页面中非list部分随list一起滑出可视区域,开启该属性会降低list渲染性能。

注意

list为水平方向时,不支持scrollpage属性。

样式

除了支持 通用样式 以外,还支持如下样式。

说明

如果list只设置宽度,未设置高度时,flex-grow样式默认值为0和设置为0的效果不一样。

展开

名称

类型

默认值

是否必填

描述

flex-direction

column | row | row-reverse(1035+) | column-reverse(1035+)

column

设置flex容器主轴的方向,指定flex项如何放置在flex容器中。 在list组件中默认值为column,其他组件默认值为row。

columns

number

1

list显示列数。

layout-type(1070+)

grid | stagger

grid

  • grid:网格展示。
  • stagger:瀑布流展示,该模式下可自定义各个list-item的高度。

事件

除了支持 通用事件 以外,还支持如下事件。

展开

名称

参数

描述

scroll

{scrollX:scrollXValue, scrollY:scrollYValue, scrollState:stateValue 1010+,topIndex:topIndexValue 1110+,bottomIndex:bottomIndexValue 1110+}

列表滑动。

  • stateValue:0 列表没有在滑动
  • stateValue:1 列表正在通过用户的手势滑动
  • stateValue:2 列表正在滑动,用户已松手
  • topIndex:list组件中当前顶部list-item的索引(完全可见的item)
  • bottomIndex:list组件中当前底部list-item的索引(完全可见的item)

scrollbottom

-

列表滑动到底部。

scrolltop

-

列表滑动到顶部。

scrollend(1035+)

-

列表滑动结束。

scrolltouchup(1035+)

-

手指抬起并有惯性滑动。

方法

展开

名称

参数

描述

scrollTo

object

list滚动到指定item位置。

scrollBy

object

使list的内容滑动一定距离(手机、平板设备从1070版本开始支持)。

注意

智慧屏仅支持dx、dy、smooth参数。

scrollTo的参数说明:

展开

名称

类型

是否必填

默认值

备注

index

number

-

指定滚动的目标位置。

smooth(1060+)

boolean

false

是否平滑滚动。

behavior(1065+)

string

auto

功能同smooth参数,支持参数 smooth(平滑滚动),instant(瞬间滚动),默认值auto,效果等同于instant

scrollBy的参数说明:

展开

名称

类型

是否必填

默认值

备注

dx

int

0

从当前位置水平方向滑动距离,单位px。

dy

int

0

从当前位置垂直方向滑动距离,单位px。

smooth

boolean

true

是否平滑滑动。

或者

展开

名称

类型

是否必填

默认值

备注

left

number

0

从当前位置水平方向滑动距离,单位px。值为正时向左滑动,为负时向右滑动。flex-direction为column或column-reverse时不生效。

top

number

0

从当前位置垂直方向滑动距离,单位px。值为正时向上滑动,为负时向下滑动。flex-direction为row或row-reverse时不生效。

behavior

string

auto

是否平滑滑动,支持参数 smooth(平滑滚动),instant(瞬间滚动),默认值auto,效果等同于instant。

示例代码

收起
自动换行
深色代码主题
复制
  1. <template>
  2. <div class="container">
  3. <div class="page-title-wrap">
  4. <text class="page-title">{{componentName}}</text>
  5. </div>
  6. <div class="nav">
  7. <text class="nav-item {{listClass}}"
  8. onclick="showListMethod">列表组件方法</text>
  9. <text class="nav-item {{arrayClass}}"
  10. onclick="showArrayMethod">数组对象方法</text>
  11. </div>
  12. <!-- List component method -->
  13. <div class="btn-wrap-column" show="{{showListBtn}}">
  14. <input type="button" class="btn" name="listmethod" value="回到第一个item"
  15. onclick="goIndex" />
  16. <input type="button" class="btn" name="listmethod" value="向右平滑移动200px"
  17. onclick="scrollBy" />
  18. </div>
  19. <!-- Array object method -->
  20. <div class="btn-wrap-row" show="{{!showListBtn}}">
  21. <input type="button" class="btn-little" onclick="clickPush" value="push"></input>
  22. <input type="button" class="btn-little" onclick="clickPop" value="pop"></input>
  23. <input type="button" class="btn-little" onclick="clickShift" value="shift"></input>
  24. <input type="button" class="btn-little" onclick="clickUnshift" value="unshift"></input>
  25. </div>
  26. <div class="btn-wrap-row" show="{{!showListBtn}}">
  27. <input type="button" class="btn-little" onclick="clickSplice" value="splice"></input>
  28. <input type="button" class="btn-little" onclick="clickSort" value="sort"></input>
  29. <input type="button" class="btn-little" onclick="clickReverse" value="reverse"></input>
  30. </div>
  31. <div class="nav">
  32. <text class="nav-item {{gridClass}}" onclick="showGridLayout">网格布局</text>
  33. <text class="nav-item {{staggerClass}}"
  34. onclick="showStaggerLayout">瀑布流布局</text>
  35. </div>
  36. <!-- List -->
  37. <list show="{{showGridLayout}}" class="list grid" onclick="listClick" onlongpress="listLongPress"
  38. onscrollbottom="scrollbottom" onscrolltop="scrolltop" onscroll="scroll" onscrollend="scrollend"
  39. onscrolltouchup="scrolltouchup" id="list" scrollpage="{{scrollPage}}">
  40. <!-- List elements, when the attribute type values are the same, you need to ensure that the rendered view layout is also the same, use show instead of if to ensure that the layout view is unchanged -->
  41. <list-item type="listItem" class="item item-color" onlongpress="listItemLongPress" onclick="listItemClick"
  42. for="{{listData}}">
  43. <text onclick="textClick" class="txt">{{$item}}--{{$idx}}</text>
  44. </list-item>
  45. <!-- Loading More -->
  46. <list-item type="loadMore" class="load-more" if="{{loadMore}}">
  47. <progress type="circular"></progress>
  48. <text>更多...</text>
  49. </list-item>
  50. </list>
  51. <list show="{{!showGridLayout}}" class="list stagger" onclick="listClick" onlongpress="listLongPress"
  52. onscrollbottom="scrollbottom" onscrolltop="scrolltop" onscroll="scroll" onscrollend="scrollend"
  53. onscrolltouchup="scrolltouchup" id="list-stagger" scrollpage="{{scrollPage}}">
  54. <!-- List elements, when the attribute type values are the same, you need to ensure that the rendered view layout is also the same, use show instead of if to ensure that the layout view is unchanged -->
  55. <list-item style="height: {{$idx % 10}}00px" type="listItem" class="item item-color"
  56. onlongpress="listItemLongPress" onclick="listItemClick" for="{{listData}}">
  57. <text onclick="textClick" class="txt">{{$item}}--{{$idx}}</text>
  58. </list-item>
  59. <!-- Loading More -->
  60. <list-item type="loadMore" class="load-more" if="{{loadMore}}">
  61. <progress type="circular"></progress>
  62. <text>更多...</text>
  63. </list-item>
  64. </list>
  65. </div>
  66. </template>
  67. <style>
  68. .list {
  69. height: 800px;
  70. padding-left: 60px;
  71. padding-right: 60px;
  72. columns: 4;
  73. border-color: #FF0000;
  74. border-width: 5px;
  75. }
  76. .grid {
  77. flex-direction: row-reverse;
  78. }
  79. .stagger {
  80. flex-direction: column;
  81. }
  82. .container{
  83. flex: 1;
  84. flex-direction: column;
  85. }
  86. .page-title-wrap {
  87. padding-top: 50px;
  88. padding-bottom: 80px;
  89. justify-content: center;
  90. }
  91. .page-title{
  92. padding-top: 30px;
  93. padding-bottom: 30px;
  94. padding-left: 40px;
  95. padding-right: 40px;
  96. border-color: #bbbbbb;
  97. color: #bbbbbb;
  98. border-bottom-width: 2px;
  99. }
  100. .btn {
  101. height: 80px;
  102. text-align: center;
  103. border-radius: 5px;
  104. margin-right: 60px;
  105. margin-left: 60px;
  106. margin-bottom: 50px;
  107. color: #ffffff;
  108. font-size: 30px;
  109. background-color: #0faeff;
  110. }
  111. .item {
  112. height: 150px;
  113. align-items: flex-start;
  114. margin-bottom: 15px;
  115. border-color: #9400D3;
  116. border-width: 5px;
  117. margin-right: 20px;
  118. }
  119. .load-more {
  120. justify-content: center;
  121. align-items: center;
  122. height: 100px;
  123. border-color: #bbbbbb;
  124. border-bottom-width: 1px;
  125. }
  126. .btn-wrap-column {
  127. flex-direction: column;
  128. margin-right: 60px;
  129. margin-left: 60px;
  130. }
  131. .btn-wrap-row {
  132. margin-right: 60px;
  133. margin-left: 45px;
  134. margin-bottom: 30px;
  135. }
  136. .btn-little {
  137. flex: 1;
  138. height: 80px;
  139. margin-left: 15px;
  140. border-radius: 5px;
  141. color: #ffffff;
  142. font-size: 30px;
  143. text-align: center;
  144. background-color: #0faeff;
  145. }
  146. .item-color {
  147. background-color: #f76160;
  148. }
  149. .nav {
  150. padding-left: 60px;
  151. padding-right: 60px;
  152. padding-bottom: 30px;
  153. }
  154. .nav-item {
  155. flex: 1;
  156. padding-bottom: 30px;
  157. border-bottom-width: 5px;
  158. border-color: #fbf9fe;
  159. font-size: 35px;
  160. color: #666666;
  161. text-align: center;
  162. }
  163. .selected {
  164. border-color: #0faeff;
  165. }
  166. </style>
  167. <script>
  168. import prompt from '@system.prompt'
  169. export default {
  170. data: {
  171. componentName: 'list',
  172. loadMore: true,
  173. listAdd: ['A', 'B', 'C', 'D', 'E', 'F', 'G', 'H', 'I', 'J', 'K', 'L', 'M', 'N', 'O', 'P', 'Q', 'R', 'S', 'T', 'U', 'V', 'W', 'X', 'Y', 'Z'],
  174. listData: [],
  175. scrollPage: false,
  176. showListBtn: true,
  177. showGridLayout: true,
  178. listClass: 'selected',
  179. arrayClass: '',
  180. gridClass: 'selected',
  181. staggerClass: '',
  182. },
  183. onInit: function () {
  184. this.$page.setTitleBar({ text: 'list' })
  185. // Initialize list data
  186. this.listData = [].concat(this.listAdd)
  187. },
  188. showListMethod: function () {
  189. if (!this.showListBtn) {
  190. this.showListBtn = true
  191. this.listClass = 'selected'
  192. this.arrayClass = ''
  193. }
  194. },
  195. showArrayMethod: function () {
  196. if (this.showListBtn) {
  197. this.showListBtn = false
  198. this.listClass = ''
  199. this.arrayClass = 'selected'
  200. }
  201. },
  202. showStaggerLayout: function () {
  203. if (this.showGridLayout) {
  204. this.showGridLayout = false
  205. this.gridClass = ''
  206. this.staggerClass = 'selected'
  207. }
  208. },
  209. showGridLayout: function () {
  210. if (!this.showGridLayout) {
  211. this.showGridLayout = true
  212. this.gridClass = 'selected'
  213. this.staggerClass = ''
  214. }
  215. },
  216. scrollbottom: function () {
  217. prompt.showToast({
  218. message: "到底部了"
  219. })
  220. // Load next page
  221. var that = this
  222. var renderData = [].concat(that.listData, that.listAdd)
  223. setTimeout(function () {
  224. that.listData = renderData
  225. }, 1000)
  226. },
  227. scrolltop: function () {
  228. prompt.showToast({
  229. message:"在最顶部了"
  230. })
  231. },
  232. scrollend: function () {
  233. prompt.showToast({
  234. message: "停止滑动了"
  235. })
  236. console.error(this.$t('message.component.list.scrollStoped'))
  237. },
  238. scrolltouchup: function () {
  239. prompt.showToast({
  240. message: "手指抬起了"
  241. })
  242. },
  243. // monitoring during sliding
  244. scroll: function (e) {
  245. let msg = " 滑动中 "+ '.scrollX:' + e.scrollX
  246. + ' .scrollY:' + e.scrollY
  247. + ' .scrollState:' + e.scrollState
  248. console.info(msg)
  249. },
  250. goIndex: function () {
  251. if (this.showGridLayout) {
  252. this.$element('list').scrollTo({ index: 0, behavior: 'smooth' })
  253. } else {
  254. this.$element('list-stagger').scrollTo({ index: 0, behavior: 'smooth' })
  255. }
  256. },
  257. scrollBy: function () {
  258. console.log('list.scrollBy: left=200, behavior= smooth')
  259. if (this.showGridLayout) {
  260. this.$element('list').scrollBy({ left: 200, behavior: 'smooth' })
  261. } else {
  262. this.$element('list-stagger').scrollBy({ top: 200, behavior: 'smooth' })
  263. }
  264. },
  265. clickPush: function () {
  266. this.listData.push('push')
  267. prompt.showToast({
  268. message: "向数组的末尾添加一个元素"
  269. })
  270. },
  271. clickPop: function () {
  272. prompt.showToast({
  273. message: " 删除数组的最后一个元素 "+ JSON.stringify(this.listData.pop())
  274. })
  275. },
  276. clickShift: function () {
  277. prompt.showToast({
  278. message: "删除数组的第一个元素 "+ JSON.stringify(this.listData.shift())
  279. })
  280. },
  281. clickUnshift: function () {
  282. this.listData.unshift('unshift')
  283. prompt.showToast({
  284. message: "向数组的开头添加一个'unshift'元素"
  285. })
  286. },
  287. clickSplice: function () {
  288. prompt.showToast({
  289. message: "删除第一个元素 "+ JSON.stringify(this.listData.splice(0, 1, 'splice')[0]) + ',' + "并添加一个'splice元素'"
  290. })
  291. },
  292. clickSort: function () {
  293. this.listData.sort()
  294. prompt.showToast({
  295. message: 'sort'
  296. })
  297. },
  298. clickReverse: function () {
  299. this.listData.reverse()
  300. prompt.showToast({
  301. message: 'reverse'
  302. })
  303. },
  304. listItemClick: function (e) {
  305. e.stopPropagation()
  306. console.info('List Item is clicked.')
  307. prompt.showToast({
  308. message: 'List Item is clicked.'
  309. })
  310. },
  311. listClick: function (e) {
  312. e.stopPropagation()
  313. console.info('List is clicked.')
  314. prompt.showToast({
  315. message: 'List is clicked.'
  316. })
  317. },
  318. textClick: function (e) {
  319. e.stopPropagation()
  320. console.info('Text is clicked.')
  321. prompt.showToast({
  322. message: 'Text is clicked.'
  323. })
  324. },
  325. listLongPress: function (e) {
  326. e.stopPropagation()
  327. console.info('List is long pressed.')
  328. prompt.showToast({
  329. message: 'List is long pressed.'
  330. })
  331. },
  332. listItemLongPress: function (e) {
  333. e.stopPropagation()
  334. console.info('List Item is long pressed.')
  335. prompt.showToast({
  336. message: 'List Item is long pressed.'
  337. })
  338. },
  339. }
  340. </script>

效果图如下:

  • layout-type设置为grid:

  • layout-type 设置为 stagger:

版本更新说明

展开

版本

发布日期

描述

1110

2024-02-07

scroll事件新增topIndex和bottomIndex参数。

1070

2020-05-19

  • 新增scrollBy属性,用于控制 list从当前位置进行滑动。
  • scrollTo方法新增behavior属性,用于控制是否进行平滑滚动。
  • 新增layout-type样式,用于控制子元素是按网格展示还是瀑布流展示。

1060

2019-12-10

list的scrollTo增加smooth属性,使页面有平滑滚动的效果。

1040

2019-06-24

  • 样式flex-direction类型新增row-reverse和column-reverse。
  • 新增scrollend和touchup事件。

1010

2018-04-20

scroll事件增加scrollState设置。

Tips

调用scrollto方法偶尔会出现无法滚动到指定位置,此问题可能和组件未渲染完成有关,建议延迟50ms再调用。

相关链接

在 API参考 中进行搜索
请输入您想要搜索的关键词