1# list 2 3<!--Kit: ArkUI--> 4<!--Subsystem: ArkUI--> 5<!--Owner: @yylong--> 6<!--Designer: @yylong--> 7<!--Tester: @liuzhenshuo--> 8<!--Adviser: @HelloCrease--> 9 10列表包含一系列相同宽度的列表项。适合连续、多行呈现同类数据，例如图片和文本。 11 12> **说明：** 13> 14> 从API Version 8 开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 15> 16> 针对卡片场景，建议开发者控制list中的子节点list-item的数量（建议30条以内）以便获取更好的卡片交互体验。 17 18 19 20 21## 子组件 22 23仅支持<[list-item](js-service-widget-container-list-item.md)>子组件。 24 25 26## 属性 27 28除支持[通用属性](js-service-widget-common-attributes.md)外，还支持如下属性： 29 30| 名称 | 类型 | 默认值 | 必填 | 描述 | 31| ------------- | -------------- | ------- | ---- | ---------------------------------------- | 32| cachedcount | number | 0 | 否 | 长列表延迟加载时list-item最少缓存数量。 | 33| scrollbar | string | off | 否 | 侧边滑动栏的显示模式（当前只支持纵向）：<br/>- off：不显示。<br/>- auto：按需显示(触摸时显示，2s后消失)。<br/>- on：常驻显示。 | 34| scrolleffect | string | spring | 否 | 滑动效果，目前支持如下滑动效果：<br/>- spring：弹性物理动效，滑动到边缘后可以根据初始速度或通过触摸事件继续滑动一段距离，松手后回弹。<br/>- fade：渐隐物理动效，滑动到边缘后展示一个波浪形的渐隐，根据速度和滑动距离的变化渐隐也会发生一定的变化。<br/>- no：滑动到边缘后无效果。 | 35| divider | boolean | false | 否 | item是否自带分隔线。<br/>其样式参考[样式列表](#样式)的divider-color、divider-height、divider-length、divider-origin。<br/>- false：item不自带分隔线。<br/>- true：item自带分隔线。 | 36| shapemode | string | default | 否 | 侧边滑动栏的形状类型。<br/>- default：不指定，跟随主题。<br/>- rect：矩形。<br/>- round：圆形。 | 37| updateeffect | boolean | false | 否 | 用于设置当list内部的item发生删除或新增时是否支持动效。<br/>- false：新增删除item时无过渡动效。<br/>- true：新增删除item时播放过程动效。 | 38| initialindex | number | 0 | 否 | 用于设置当前List初次加载时视口起始位置显示的item，默认为0，即显示第一个item，如设置的序号超过了最后一个item的序号，则设置不生效，当同时设置了initialoffset属性时，当前属性不生效。 | 39| initialoffset | <length> | 0 | 否 | 用于设置当前List初次加载时视口的起始偏移量，偏移量无法超过当前List可滑动的范围，如果超过会被截断为可滑动范围的极限值。 | 40| selected | string | - | 否 | 指定当前列表中被选中激活的项，可选值为list-item的section属性值。 | 41 42 43## 样式 44 45除支持[通用样式](js-service-widget-common-styles.md)外，还支持如下样式： 46 47| 名称 | 类型 | 默认值 | 必填 | 描述 | 48| ---------------- | ---------------------------------------- | ----------- | ---- | ---------------------------------------- | 49| divider-color | <color> | transparent | 否 | item分隔线颜色，仅当list的divider属性为true时生效。 | 50| divider-height | <length> | 1 | 否 | item分隔线高度，仅当list的divider属性为true时生效。 | 51| divider-length | <length> | 主轴宽度 | 否 | item分隔线长度，不设置时最大长度为主轴宽度，具体长度取决于divider-origin，仅当list的divider属性为true时生效。 | 52| divider-origin | <length> | 0 | 否 | item分隔线相对于item主轴起点位置的偏移量，仅当list的divider属性为true时生效。 | 53| flex-direction | string | column | 否 | 设置flex容器主轴的方向，指定flex项如何放置在flex容器中，可选值为：<br/>- column：主轴为纵向。<br/>- row：主轴为横向。<br/>其他组件默认值为row，在list组件中默认值为column。 | 54| columns | number | 1 | 否 | list交叉轴方向的显示列数，默认为1列。<br/>设置多列时，在list交叉轴上进行均分，每一列大小相同。 | 55| align-items | string | stretch | 否 | list每一列交叉轴上的对齐格式，可选值为：<br/>- stretch：弹性元素被在交叉轴方向被拉伸到与容器相同的高度或宽度。<br/>- flex-start：元素向交叉轴起点对齐。<br/>- flex-end：元素向交叉轴终点对齐。<br/>- center：元素在交叉轴居中。<br/> align-items样式作用在每一列的子元素上，列与列之间采用均分方式布局。 | 56| item-extent | <length> \| <percentage> | - | 否 | 设置内部item为固定大小，设置为百分比格式时，指相对于list的视口主轴方向长度的百分比。 | 57| fade-color | <color> | grey | 否 | 设置渐隐物理动效的颜色。当滑动效果设置为渐隐物理动效时生效。 | 58| scrollbar-color | <color> | - | 否 | 设置滚动条的颜色。 | 59| scrollbar-width | <length> | - | 否 | 设置滚动条的宽度。 | 60| scrollbar-offset | <length> | 0 | 否 | 设置滚动条距离List默认位置的偏移量，只支持正数，默认位置在List右边缘，可以通过这个偏移量调整滚动条的水平位置，如果滚动条绘制在list外部，而list父组件有裁剪，会导致滚动条被裁剪。 | 61 62 63## 事件 64 65支持[通用事件](js-service-widget-common-events.md)。 66 67 68## 示例 69 70 71```html 72<!-- index.hml --> 73<div class="container"> 74 <list class="todo-wrapper"> 75 <list-item for="{{todolist}}" class="todo-item"> 76 <text class="todo-title">{{$item.title}}</text> 77 <text class="todo-title">{{$item.date}}</text> 78 </list-item> 79 </list> 80</div> 81``` 82 83 84```json 85{ 86 "data": { 87 "todolist": [{ 88 "title": "work", 89 "date": "2021-12-31 10:00:00" 90 }, { 91 "title": "watch movie", 92 "date": "2021-12-31 20:00:00" 93 }] 94 } 95} 96``` 97 98 99```css 100/* index.css */ 101.container { 102 display: flex; 103 justify-content: center; 104 align-items: center; 105 left: 0px; 106 top: 0px; 107 width: 454px; 108 height: 454px; 109} 110.todo-wrapper { 111 width: 454px; 112 height: 300px; 113} 114.todo-item { 115 width: 454px; 116 height: 80px; 117 flex-direction: column; 118} 119.todo-title { 120 width: 454px; 121 height: 40px; 122 text-align: center; 123} 124``` 125**4*4卡片** 126 127
