鸿蒙ArkUI实战：滑动操作与列表交互

滑动操作是移动端列表交互的核心模式。本文用 ArkUI 的swipeActionAPI 构建一个完整的滑动操作列表——左滑删除、右滑置顶覆盖双方向滑动、滑动阈值、操作确认以及空状态反馈。一、我们要做什么一个待办事项列表每条支持两个方向的滑动操作左滑删除— 从右向左滑动露出红色删除按钮。滑过阈值80vp自动触发删除也可轻点按钮删除。删除后 Toast 反馈。右滑置顶— 从左向右滑动露出蓝色置顶按钮。已置顶的项列表第一条不再显示右滑按钮——避免无意义的重复置顶。空状态— 删除全部 12 条后显示空状态提示。底部操作提示— “← 左滑删除 | 右滑置顶 →”引导用户发现滑动手势。二、数据模型classSwipeItem{id:number;title:string;subtitle:string;time:string;constructor(id:number,title:string,subtitle:string,time:string){this.idid;this.titletitle;this.subtitlesubtitle;this.timetime;}}12 条模拟数据模拟一个开发者的待办清单——标题是主要任务副标题是描述/备注时间是最后修改时间。三、swipeAction API 全解析3.1 基本结构ListItem(){// 列表项的正文内容}.swipeAction({start:{// 右滑从左侧露出按钮builder:(){this.pinButton()},onAction:(){this.pinItem(item.id)},actionAreaDistance:70},end:{// 左滑从右侧露出按钮builder:(){this.deleteButton()},onAction:(){this.deleteItem(item.id,item.title)},actionAreaDistance:80}})swipeAction接收一个配置对象包含两个可选字段字段方向按钮出现位置start从左向右滑列表项左侧露出按钮end从右向左滑列表项右侧露出按钮3.2 三个关键字段每个方向的配置对象包含字段类型说明builderCustomBuilder滑动后露出的按钮 UI必须是() void类型的 BuilderonAction() void滑动距离超过阈值时的回调。触发后自动收起滑动状态actionAreaDistancenumbervp阈值距离。滑过这个距离松手 →onAction触发未滑过 → 按钮弹回三个执行路径滑过阈值松手→onAction触发自动执行操作轻滑后松手按钮露出但未过阈值→ 按钮保持在露出状态用户可轻点按钮轻点露出的按钮→ 按钮的onClick触发onAction的语义是滑动到位执行操作——它替代了按钮的 onClick。所以通常做法是builder 只负责视觉onAction 负责逻辑按钮的 onClick 可以省略。3.3 为什么 builder 不能直接传 Builder 引用builder字段的类型是CustomBuilder定义为() void。你不能写builder: this.pinButton因为 ArkTS 不支持直接传 Builder 方法引用。必须用箭头函数包裹builder: () { this.pinButton() }。这个箭头函数也解决了闭包捕获问题——在 ForEach 内部箭头函数捕获当前循环的item每个 ListItem 的 swipeAction 持有对各自 item 的正确引用。四、交互点1左滑删除4.1 删除按钮 BuilderBuilderdeleteButton(){Row(){Text(删除).fontSize(FontSize.BODY).fontColor(Color.White)}.width(80).height(100%).backgroundColor(AppColors.ERROR).justifyContent(FlexAlign.Center)}关键细节.height(100%)让删除按钮自动撑满 ListItem 的高度。不需要写死高度——List 的每个 ListItem 高度可能不同百分比高度让按钮与内容等高视觉效果干净统一。红色背景AppColors.ERROR (#FF4D4F)是删除操作的通用颜色——用户看到红色就知道是破坏性操作。4.2 删除逻辑privatedeleteItem(id:number,title:string):void{constidxthis.items.findIndex((item:SwipeItem)item.idid);if(idx0){this.items.splice(idx,1);this.items[...this.items];promptAction.showToast({message:已删除${title},duration:1500});}}Toast 包含了被删条目的标题——让用户知道删了什么比已删除三个字更有信息量。1500ms 的 duration 足够阅读。4.3 actionAreaDistance 80为什么设 80vpArkUI 默认的actionAreaDistance是 56vp。设得更大80vp意味着用户需要滑得更远才会触发自动执行——降低误操作概率。删除是破坏性操作不应该太容易触发。置顶的actionAreaDistance设 70vp——比删除略低因为置顶不是破坏性操作用户不慎触发也容易恢复。五、交互点2右滑置顶5.1 置顶按钮的条件显示start:this.items[0]?.id!item.id?{builder:(){this.pinButton()},onAction:(){this.pinItem(item.id)},actionAreaDistance:70}:undefined,this.items[0]?.id ! item.id判断当前项是否已经是第一条。如果是 →start: undefined→ 右滑无操作。如果不是第一条 →start: { builder, onAction, actionAreaDistance }→ 右滑可置顶。这个条件判断避免了第一条也能置顶的无意义操作——已经是第一条了再置顶等于没动。5.2 置顶逻辑privatepinItem(id:number):void{constidxthis.items.findIndex((item:SwipeItem)item.idid);if(idx0){constitemthis.items[idx];this.items.splice(idx,1);this.items[item,...this.items];this.items[...this.items];promptAction.showToast({message:已置顶,duration:1200});}}三步splice(idx, 1)从原位置取出[item, ...this.items]插入到数组头部[...this.items]触发 State 更新注意idx 0而非idx 0——idx 为 0 时已在顶部不操作。六、交互点3滑动阈值与松手回弹actionAreaDistance定义了临界点。用户滑动时有两种松手结果滑过 80vp → 松手 → onAction 触发 → 删除 → Toast 未过 80vp → 松手 → 按钮保持露出状态 → 用户可轻点按钮或右滑收回在实际测试中用户可以轻滑露出按钮 → 看一眼 → 决定不删 → 反方向滑回 → 按钮隐藏轻滑露出按钮 → 点击红色删除文字 → 删除用力滑过 80vp → 松手即删 → 最快路径这给了用户分层次的操作自由度——这是好的手势设计。七、交互点4空状态if(this.items.length0){Column(){Image($r(sys.symbol.archivebox)).width(48).height(48).fillColor(AppColors.TEXT_DISABLED).margin({bottom:Spacing.MD})Text(列表为空).fontSize(FontSize.BODY).fontColor(AppColors.TEXT_DISABLED)Text(左右滑动列表项进行操作).fontSize(FontSize.CAPTION).fontColor(AppColors.TEXT_DISABLED).margin({top:Spacing.XS})}.width(100%).layoutWeight(1).justifyContent(FlexAlign.Center)}用sys.symbol.archivebox已验证可用的符号作为空状态图标。两条提示文字——列表为空是当前状态左右滑动列表项进行操作是操作引导。在空状态下这条引导没有实际作用但它强化了用户对滑动手势的认知——下次有数据的时候就知道可以滑了。八、列表项内容布局Row(){Column(){Text(item.title).fontSize(FontSize.BODY).fontColor(AppColors.TEXT_PRIMARY).maxLines(1).textOverflow({overflow:TextOverflow.Ellipsis})Text(item.subtitle).fontSize(FontSize.CAPTION).fontColor(AppColors.TEXT_TERTIARY).maxLines(1).textOverflow({overflow:TextOverflow.Ellipsis}).margin({top:2})}.layoutWeight(1).alignItems(HorizontalAlign.Start)Text(item.time).fontSize(FontSize.CAPTION).fontColor(AppColors.TEXT_DISABLED).margin({left:Spacing.SM})}.width(100%).padding({left:Spacing.LG,right:Spacing.LG,top:Spacing.MD,bottom:Spacing.MD}).backgroundColor(Color.White)双行文本 右侧时间和微信消息列表布局一致。layoutWeight(1)让标题区域占据剩余宽度时间文字靠右对齐。两个maxLines(1) textOverflow防止长文本溢出。九、底部操作提示Text(← 左滑删除 | 右滑置顶 →).fontSize(FontSize.CAPTION).fontColor(AppColors.TEXT_DISABLED).width(100%).textAlign(TextAlign.Center).padding({top:Spacing.SM,bottom:Spacing.SM}).backgroundColor(AppColors.BACKGROUND)这条提示固定在列表底部。左右箭头符号配合文字直观告诉用户两个方向分别对应什么操作——滑动手势的发现性差很多用户不知道可以滑一行提示能大幅提升交互的曝光率。十、页面结构总结SwipePage (~190 行) ├── 数据层 │ ├── SwipeItem 类 (id, title, subtitle, time) │ └── MOCK_ITEMS 常量 (12 条) ├── 状态层 │ └── State items: SwipeItem[] ├── 业务方法 │ ├── deleteItem(id, title) — 删除 Toast │ └── pinItem(id) — 置顶 Toast ├── 操作按钮 Builder │ ├── deleteButton() — 红色 80vp 宽 │ └── pinButton() — 蓝色 70vp 宽 └── UI 结构 ├── Header (返回 标题 计数) ├── List ForEach (swipeAction: start end) ├── 空状态 (archivebox 图标) └── 底部提示 (← 左滑删除 | 右滑置顶 →)十一、常见面试题 / 踩坑点11.1actionAreaDistance设多少合适删除等破坏性操作— 60-80vp稍长减少误操作收藏/标记等非破坏性操作— 40-60vp快速触发默认值— 56vp不要设到 100vp 以上— 用户滑不到等于这个功能不存在11.2 为什么用findIndex splice而不用filter两种写法的差异// splice 方案constidxthis.items.findIndex(mm.idid);this.items.splice(idx,1);this.items[...this.items];// filter 方案this.itemsthis.items.filter(mm.id!id);splice方案在删除后立即退出O(n) 查找 O(1) 删除。filter方案遍历整个数组创建新数组O(n) 遍历 O(n) 空间。对于 12 条数据差异可忽略但对于 1000 条数据splice只要找到目标就停止。更重要的是deleteItem需要拿到被删项的title用于 Toast 提示——splice方案在删除前已经拿到了引用filter方案需要在外面再 find 一次。11.3start和end可以同时作用于一个 ListItem 吗可以如本 Demo。但要注意两个方向的滑动操作互斥——同时只能滑一个方向如果某个方向设为undefined该方向不能滑动第一条的start: undefined就是利用了这个特性11.4builder闭包中的item引用安全吗安全。ForEach 的每次迭代创建独立的闭包作用域builder: () { this.pinButton() }中的箭头函数捕获了外层 ForEach 回调中的item变量。由于item是constForEach 的回调参数不存在变量被后续迭代覆盖的问题。11.5swipeAction对 ListItem 的性能有影响吗每个 ListItem 的 swipeAction 会创建额外的 DOM 节点按钮区域。对于 50 条以内的列表几乎无影响。如果需要优化 500 条的列表建议配合LazyForEach使用只渲染可见区域的 ListItem。11.6 滑动手势和 List 的滚动冲突吗不冲突。ArkUI 的手势系统内部处理了水平滑动swipeAction和垂直滚动List的手势竞争——水平滑动优先触发 swipeAction垂直滑动优先触发列表滚动。用户斜向滑动时系统根据主要轴向判断意图。十二、运行方式代码位于dev/entry/src/main/ets/pages/SwipePage.ets。用 DevEco Studio 打开dev/项目首页点击滑动操作 — 左滑删除与右滑置顶即可体验进入页面 → 12 条待办事项底部提示← 左滑删除 | 右滑置顶 →左滑任意条目 → 露出红色删除按钮继续滑过 80vp 松手 → 自动删除 Toast左滑后松手未过阈值→ 按钮保持露出轻点删除文字 → 同样删除右滑非首条 → 露出蓝色置顶按钮 → 自动或手动触发 → 条目跳到列表第一列表首条右滑无效 → 没有置顶按钮已是最顶删除全部 12 条 → 空状态提示列表为空查看顶部计数 → 实时显示剩余条目数十三、扩展方向两段式滑动— 第一阶段露出单个按钮70vp第二阶段滑到 140vp 露出第二个按钮如删除 归档参考 iOS 邮件 App自定义操作菜单— 不止一个按钮露出后显示 2-3 个操作编辑、删除、分享用 Row 布局撤销删除— 删除后不立即 splice先软删除灰色 划线3 秒内可撤销。类似 Gmail 的撤销模式振动反馈— 滑过阈值时触发vibrator.vibrate(10)物理反馈增强操作感滑动选择模式— 长按进入多选模式每个 ListItem 左侧出现 Checkbox不再触发 swipeAction左滑操作记录— 左滑删除后写入操作历史数组在页面外提供最近删除入口恢复弹性动画— 自定义 swipeAction 的回弹曲线让松手后的回弹更自然Dark Mode 适配— 操作按钮在暗黑模式下调整色彩饱和度避免红色在暗底上刺眼