当前位置：首页 > news >正文

HarmonyOS6 ArkTS ListItem设置划出组件

news 2026/6/13 17:32:20

文章目录

- 一、功能说明
- 二、完整标准代码
- 三、核心 API：swipeAction 配置详解
- - 1. 基础结构
  - 2. end 右侧划出配置项
- 四、关键用法逐行解析
- - 1. 定义划出组件 UI（@Builder 复用）
  - 2. 绑定划出组件到 ListItem
  - 3. 滑动删除动画
  - 4. 控制滑动行为（ListScroller）
  - 5. 滑动状态监听
- 五、运行效果
- 总结

一、功能说明

ListItem 的swipeAction属性用于配置侧滑划出组件，是列表类应用的核心交互能力：

支持右侧滑出（end）/左侧滑出（start）自定义操作按钮
支持滑出按钮点击事件、滑动区域进入/退出监听
支持控制滑动距离、自动关闭滑动等行为
常用于列表项删除、编辑、标记、置顶等操作场景

二、完整标准代码

// xxx.ets @Entry @Component struct ListItemExample2 { @State arr: number[] = [0, 1, 2, 3, 4]; @State enterEndDeleteAreaString: string = 'not enterEndDeleteArea'; @State exitEndDeleteAreaString: string = 'not exitEndDeleteArea'; private scroller: ListScroller = new ListScroller(); @Builder itemEnd() { Row() { Button('Delete').margin('4vp') Button('Set').margin('4vp').onClick(() => { this.scroller.closeAllSwipeActions(); }) }.padding('4vp').justifyContent(FlexAlign.SpaceEvenly) } build() { Column() { List({ space: 10, scroller: this.scroller }) { ForEach(this.arr, (item: number) => { ListItem() { Text('item' + item) .width('100%') .height(100) .fontSize(16) .textAlign(TextAlign.Center) .borderRadius(10) .backgroundColor(0xFFFFFF) } .transition(TransitionEffect.OPACITY) .swipeAction({ end: { builder: () => { this.itemEnd() }, onAction: () => { this.getUIContext()?.animateTo({ duration: 1000 }, () => { let index = this.arr.indexOf(item); this.arr.splice(index, 1); }); }, actionAreaDistance: 56, onEnterActionArea: () => { this.enterEndDeleteAreaString = 'enterEndDeleteArea'; this.exitEndDeleteAreaString = 'not exitEndDeleteArea'; }, onExitActionArea: () => { this.enterEndDeleteAreaString = 'not enterEndDeleteArea'; this.exitEndDeleteAreaString = 'exitEndDeleteArea'; } } }) }, (item: number) => item.toString()) } Text(this.enterEndDeleteAreaString).fontSize(20) Text(this.exitEndDeleteAreaString).fontSize(20) } .padding(10) .backgroundColor(0xDCDCDC) .width('100%') .height('100%') } }

运行效果如图：
默认情况：

当把最后一个往左滑：

当左滑超过一半本条item会消失，或者点击delete也会消失：

三、核心 API：swipeAction 配置详解

swipeAction是 ListItem 提供的划出组件专属属性，用于定义左右侧滑显示的操作栏，是官方标准API。

1. 基础结构

.swipeAction({ start?: {}, // 左侧滑出组件（可选） end?: {} // 右侧滑出组件（本文示例使用） })

2. end 右侧划出配置项

参数名	类型	说明
builder	CustomBuilder	必填，划出组件的UI构造器
onAction	() => void	滑动触发动作（滑动到阈值后执行）
actionAreaDistance	number	滑动阈值，单位vp
onEnterActionArea	() => void	手指滑动进入有效操作区域时触发
onExitActionArea	() => void	手指滑动退出有效操作区域时触发

四、关键用法逐行解析

1. 定义划出组件 UI（@Builder 复用）

使用@Builder装饰器定义可复用的侧滑按钮布局，是官方推荐写法：

@Builder itemEnd() { Row() { Button('Delete').margin('4vp') Button('Set').margin('4vp').onClick(() => { // 关闭所有ListItem的滑动展开 this.scroller.closeAllSwipeActions(); }) }.padding('4vp').justifyContent(FlexAlign.SpaceEvenly) }

2. 绑定划出组件到 ListItem

直接在 ListItem 后链式调用.swipeAction()：

ListItem() { ... } .swipeAction({ end: { builder: () => { this.itemEnd() }, // 绑定侧滑布局 onAction: () => { ... }, // 滑动删除逻辑 actionAreaDistance: 56, // 触发阈值 56vp onEnterActionArea: () => { ... }, // 进入滑动区域 onExitActionArea: () => { ... } // 退出滑动区域 } })

3. 滑动删除动画

使用animateTo实现平滑删除动画，提升交互体验：

this.getUIContext()?.animateTo({ duration: 1000 }, () => { let index = this.arr.indexOf(item); this.arr.splice(index, 1); });

4. 控制滑动行为（ListScroller）

closeAllSwipeActions()可一键关闭所有展开的滑动项：

this.scroller.closeAllSwipeActions();

5. 滑动状态监听

实时监听用户是否进入滑动有效区域，可用于提示、音效、震动等交互增强：

onEnterActionArea: () => { this.enterEndDeleteAreaString = 'enterEndDeleteArea'; } onExitActionArea: () => { this.exitEndDeleteAreaString = 'exitEndDeleteArea'; }