属性

除支持[通用属性]外，还支持如下属性：

名称 类型 默认值 必填 描述
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 false 否
indexercircle5+ boolean - 否 是否为环形索引。 穿戴设备默认为true，其他为false。indexer为false时不生效。
indexermulti5+ boolean false 否 是否开启索引条多语言功能。 indexer为false时不生效。
indexerbubble5+ boolean true 否 是否开启索引切换的气泡提示。 indexer为false时不生效。
divider5+ 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时播放过程动效。
chainanimation5+ 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 0 否 用于设置当前List初次加载时视口的起始偏移量，偏移量无法超过当前List可滑动的范围，如果超过会被截断为可滑动范围的极限值。当indexer为true或者scrollpage为true时，不生效。
selected5+ string - 否 指定当前列表中被选中激活的项，可选值为list-item的section属性值。

样式

除支持[通用样式]外，还支持如下样式：

名称 类型 默认值 必填 描述
divider-color5+ transparent 否 item分隔线颜色，仅当list的divider属性为true时生效。
divider-height5+ 1 否 item分隔线高度，仅当list的divider属性为true时生效。
divider-length5+ 主轴宽度 否 item分隔线长度，不设置时最大长度为主轴宽度，具体长度取决于divider-origin，仅当list的divider属性为true时生效。
divider-origin5+ 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 - 否
fade-color grey 否 设置渐隐物理动效的颜色。当滑动效果设置为渐隐物理动效时生效。
scrollbar-color6+ - 否 设置滚动条的颜色。
scrollbar-width6+ - 否 设置滚动条的宽度。
scrollbar-offset6+ 0 否 设置滚动条距离List默认位置的偏移量，只支持正数，默认位置在List右边缘，可以通过这个偏移量调整滚动条的水平位置，如果滚动条绘制在list外部，而list父组件有裁剪，会导致滚动条被裁剪。

事件

除支持[通用事件]外，还支持如下事件：

名称 参数 描述
indexerchange5+ { 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时，会触发该事件。
rotation7+ { rotateValue: number } 返回表冠旋转角度增量值，仅智能穿戴支持。

方法

支持[通用方法]外，还支持如下方法：

名称 参数 描述
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，返回值说明请见表 currentOffset返回对象属性说明。

表1 currentOffset返回对象属性说明

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

示例

<!-- index.hml -->
<div class="container">
  <list class="todo-wrapper">
    <list-item for="{{todolist}}" class="todo-item">
      <div style="flex-direction: column;align-items: center;justify-content: center;">
        <text class="todo-title">{{$item.title}}</text>
        <text class="todo-title">{{$item.date}}</text>
      </div>
    </list-item>
  </list>
</div>
html

/* index.css */
.container {
  display: flex;
  justify-content: center;
  align-items: center;
  width: 100%;
  height: 100%;
}
.todo-wrapper {
  width: 100%;
  height: 300px;
}
.todo-item {
  width: 100%;
  height: 120px;
  justify-content:center;
}
.todo-title {
  width: 100%;
  height: 80px;
  text-align: center;
}
css

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

外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传

加入鸿蒙学习阵营！

除了本文，面费领《HarmonyOS应用开发》+《鸿蒙openharmony系统开发大全》 等入门进阶资料！关注我的CSDN主页，持续获取：
在这里插入图片描述

最新鸿蒙技术文章
独家项目实战教程
免费直播/训练营信息
👉 下方资源区已为你备好！

# harmonyos # javascript # 华为 # 开发语言 # 鸿蒙系统
Logo
HarmonyOS开发者社区

讨论HarmonyOS开发技术，专注于API与组件、DevEco Studio、测试、元服务和应用上架分发等。

更多推荐

鸿蒙智能待办：钉钉学而思待办自动同步日历

点外卖后不用反复打开App看取餐号，智能待办会自动归集瑞幸、KFC、麦当劳等餐饮取餐号，在取餐时间到时主动提醒。出行方面，同程旅行、携程旅行平台的票务出行、酒店订单信息也能统一归集，时序化整理后自动提醒出发时间和登机信息。升级鸿蒙6.1，让AI帮你记住每一件重要的事。还可统一归集瑞幸、KFC、麦当劳等餐饮取餐号及各类同程旅行、携程旅行平台的票务出行、酒店订单信息，并进行时序化整理和智能提醒。Har

avatar HarmonyOS开发者社区

鸿蒙AI防诈能力：场景化防诈+换脸检测+亲情防诈

用AI对抗AI，用智能对抗狡猾，这正是鸿蒙安全"更智能"的体现。在AI换脸诈骗层出不穷的今天，鸿蒙用场景化防诈、换脸检测、亲情防诈三重AI防护对抗新型威胁——安全好用才是真好用。现在，AI技术飞速发展，电信诈骗手段层出不穷，从"冒充公检法"到"AI换脸视频通话"，用户防不胜防。HarmonyOS 6的AI防护能力已扩展至AI场景化防诈、AI换脸检测、亲情防诈三大方向，用AI对抗AI，为你筑起智能化

avatar HarmonyOS开发者社区

鸿蒙开发--IAPKit-ArkTS

HarmonyOS IAP Kit 应用内购买功能摘要 HarmonyOS IAP Kit 是华为提供的应用内支付解决方案，支持三种商品类型：消耗型（如游戏钻石）、非消耗型（如永久会员）和订阅型（如月度会员）。开发者需要先在AppGallery Connect后台开通商户服务并配置商品信息（包括商品ID、名称、价格等）。在代码实现上，主要流程包括：检查支付环境、查询商品信息、发起购买请求并处理支付

avatar HarmonyOS开发者社区