HarmonyOS ArkUI滚动类组件-List、ListItem

List 是很常用的滚动类容器组件之一，它按照水平或者竖直方向线性排列子组件， List 的子组件必须是 ListItem ，它的宽度默认充满 List 的宽度。

List定义介绍

interface ListInterface {
  (value?: { initialIndex?: number; space?: number | string; scroller?: Scroller }): ListAttribute;
}

initialIndex：默认值为 0 ，设置 List 第一次加载数据时所要显示的第一个子组件的下标，如果超过最后一个子组件的下标，则设置不生效。
space：设置列表间的间隔距离。
scroller：设置滚动控制器。

简单样例如下所示：

List({space: 10}) {                       // 设置ListItem之间的间隔为10
  ListItem() {                            // List的子组件只能是ListItem
    Text('Text1')
      .size({width: '100%', height: 60})
      .fontSize(26)
      .backgroundColor('#aabbcc')
  }
  .width('100%')

  ListItem() {                            // List的子组件只能是ListItem
    Text('Text2')
      .size({width: '100%', height: 60})
      .fontSize(26)
      .backgroundColor('#aabbcc')
  }
  .width('100%')

  ListItem() {                            // List的子组件只能是ListItem
    Text('Text3')
      .size({width: '100%', height: 60})
      .fontSize(26)
      .backgroundColor('#aabbcc')
  }
  .width('100%')

  ListItem() {                            // List的子组件只能是ListItem
    Text('Text4')
      .size({width: '100%', height: 60})
      .fontSize(26)
      .backgroundColor('#aabbcc')
  }
  .width('100%')

  ListItem() {                            // List的子组件只能是ListItem
    Text('Text5')
      .size({width: '100%', height: 60})
      .fontSize(26)
      .backgroundColor('#aabbcc')
  }
  .width('100%')
}
.width('100%')
.height(200)
.padding(10)
.backgroundColor(Color.Pink)

List属性介绍

declare class ListAttribute<T> extends CommonMethod<T> {
  listDirection(value: Axis): T;
  scrollBar(value: BarState): T;
  edgeEffect(value: EdgeEffect): T;
  divider(value: {
    strokeWidth: number | string | Resource, color?: Color | number | string | Resource,
    startMargin?: number | string | Resource, endMargin?: number | string | Resource
  } | null): T;
  editMode(value: boolean): T;
  cachedCount(value: number): T;
  chainAnimation(value: boolean): T;
}

listDirection：设置子组件的排列方向， Axis 定义了以下 2 种排列方向：
- Vertical（默认值）：设置子组件竖直方向排列
- Horizontal：设置子组件水平方向排列
edgeEffect：设置 List 滑动到边缘时的滑动效果， EdgeEffect 定义了以下 2 种滑动效果：
- Spring（默认值）：弹性物理动效，滑动到边缘后可以根据初始速度或通过触摸事件继续滑动一段距离，松手后回弹。
- None：没有滑动效果。
divider：设置分割线样式，默认无分割线，分割线样式说明如下：
- strokeWidth：分割线的宽度
- color：分割线的颜色
- startMargin：分割线距离列表侧边起始端的距离。
- endMargin：分割线距离列表侧边结束端的距离。

简单样例如下所示：

    // private items: number[] = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14];
    List() {// List默认竖直方向排列子组件
      ForEach(this.items, (item: any, index?: number) => {
        ListItem() {
          Text('Text: ' + item)
            .fontSize(20)
            .height(40)
            .backgroundColor("#aabbcc")
            .width('100%')
        }
      })
    }
    .height(120)
    .width('100%')
    .divider({
      strokeWidth: 4,   // 设置分割线宽度
      color: Color.Pink // 设置分割线颜色
    })

editMode：设置 List 是否可编辑，默认不可编辑。
chainAnimation：时候开启联动效果，默认不开启。
scrollBar：设置滚动条状态，功能同 Scroll 。
cachedCount：设置 List 的缓存数量。

List事件介绍

declare class ListAttribute<T> extends CommonMethod<T> {
  onScroll(event: (scrollOffset: number, scrollState: ScrollState) => void): T;
  onScrollIndex(event: (start: number, end: number) => void): T;
  onReachStart(event: () => void): T;
  onReachEnd(event: () => void): T;
  onScrollStop(event: () => void): T;
  onItemDelete(event: (index: number) => boolean): T;
  onItemMove(event: (from: number, to: number) => boolean): T;
}

onItemDelete：列表项被删除时触发该回调。
onScrollIndex：当前列表显示的起始位置和终止位置发生变化时触发该回调。
onReachStart：滚动到顶部触发该回调。
onReachEnd：滚动到底部触发该回调。

ListItem定义介绍

ListItem 用来展示 List 的具体 item，它的宽度默认充满 List 的宽度，它必须配合 List 使用才有效果，定义如下：

interface ListItemInterface {
  (value?: string): ListItemAttribute;
}

value：标记位，标记当前 item 的 flag。

ListItem属性介绍

declare class ListItemAttribute<T> extends CommonMethod<T> {
  sticky(value: Sticky): T;
  editable(value: boolean | EditMode): T;
}

sticky：设置 ListItem 的吸顶效果， Sticky 提供了以下 2 种类型：
- None（默认值）：没有吸顶效果。
- Normal：设置当前 item 有吸顶效果。
editable：是否可以编辑，进入编辑模式后可以删除 item ，默认为 false。

简单样例如下所示：

List({space: 10}) {
  ListItem() {
    Text('Text1')
      .size({width: '100%', height: 60})
      .fontSize(26)
      .backgroundColor('#aabbcc')
  }
  .sticky(Sticky.Normal)// 设置吸顶效果
  .width('100%')

  ListItem() {
    Text('Text2')
      .size({width: '100%', height: 60})
      .fontSize(26)
      .backgroundColor('#aabbcc')
  }
  .width('100%')

  ListItem() {
    Text('Text3')
      .size({width: '100%', height: 60})
      .fontSize(26)
      .backgroundColor('#aabbcc')
  }
  .width('100%')

  ListItem() {
    Text('Text4')
      .size({width: '100%', height: 60})
      .fontSize(26)
      .backgroundColor('#aabbcc')
  }
  .width('100%')

  ListItem() {
    Text('Text5')
      .size({width: '100%', height: 60})
      .fontSize(26)
      .backgroundColor('#aabbcc')
  }
  .width('100%')
}
.width('100%')
.height(200)
.padding(10)
.backgroundColor(Color.Pink)

完整样例

List 结合 ListItem 完整样例如下所示：

@Entry @Component struct ComponentTest {

  private arr: number[] = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
  @State editFlag: boolean = false

  build() {
    Column() {
      List({ space: 20, initialIndex: 0 }) {
        ListItem() {
          Text('sticky:Normal , click me edit list')
            .width('100%')
            .height(60)
            .fontSize(14)
            .textAlign(TextAlign.Center)
            .backgroundColor(Color.Pink)
            .onClick(() => {
              this.editFlag = !this.editFlag
            })
        }.sticky(Sticky.Normal)

        ForEach(this.arr, (item, index) => {
          ListItem() {
            Text('' + item)
              .width('100%')
              .height(100)
              .fontSize(16)
              .textAlign(TextAlign.Center)
              .borderRadius(10)
              .backgroundColor('#bbccaa')
          }
          .editable(this.editFlag)
          .sticky(0 == index ? Sticky.Opacity : Sticky.None)
        }, item => item)
      }
      .editMode(true)
      .onItemDelete((index: number) => {
        this.arr.splice(index - 1, 1)
        this.editFlag = false
        return true
      }).width('90%')
    }.width('100%').height('100%').backgroundColor(0xDCDCDC).padding({ top: 5 })
  }

  private aboutToAppear() {
    for(var i: number = 0; i < 20; i++) {
      this.arr[i] = i;
    }
  }
}

码牛课堂也为了积极培养鸿蒙生态人才，让大家都能学习到鸿蒙开发最新的技术，针对一些在职人员、0基础小白、应届生/计算机专业、鸿蒙爱好者等人群，整理了一套纯血版鸿蒙（HarmonyOS Next）全栈开发技术的学习路线。大家可以进行参考学习：https://qr21.cn/FV7h05

①全方位，更合理的学习路径：
路线图包括ArkTS基础语法、鸿蒙应用APP开发、鸿蒙能力集APP开发、次开发多端部署开发、物联网开发等九大模块，六大实战项目贯穿始终，由浅入深，层层递进，深入理解鸿蒙开发原理！

②多层次，更多的鸿蒙原生应用：
路线图将包含完全基于鸿蒙内核开发的应用，比如一次开发多端部署、自由流转、元服务、端云一体化等，多方位的学习内容让学生能够高效掌握鸿蒙开发，少走弯路，真正理解并应用鸿蒙的核心技术和理念。

③实战化，更贴合企业需求的技术点：
学习路线图中的每一个技术点都能够紧贴企业需求，经过多次真实实践，每一个知识点、每一个项目，都是码牛课堂鸿蒙研发团队精心打磨和深度解析的成果，注重对学生的细致教学，每一步都确保学生能够真正理解和掌握。

为了能让大家更好的学习鸿蒙（HarmonyOS NEXT）开发技术，这边特意整理了《鸿蒙开发学习手册》（共计890页），希望对大家有所帮助：https://qr21.cn/FV7h05