鸿蒙 HarmonyOS 6 | Swiper滑动状态变化事件回调开发实战续篇-洪萨配资

前言

Swiper 这类组件，首页 Banner、引导页、卡片切换、内容流滑动都会用到。过去做这类交互时，索引变化可以用onChange，动画起止可以看onAnimationStart和onAnimationEnd，跟手偏移还能靠onGestureSwipe拿到一部分信息。但很多业务真正想要的是另一层能力，用户什么时候开始拖，什么时候已经松手进入惯性动画，什么时候页面彻底停住。API 20 把onScrollStateChanged补进来之后，这条链路才算完整了。这个事件从 HarmonyOS 6.0.0(20) 开始支持，回调参数为ScrollState。

这项能力一旦接到业务里，很多原来写得比较别扭的逻辑就能顺下来。浮层显隐、自动轮播暂停与恢复、图片预加载时机、埋点上报时机，都可以挂到明确的状态点上去做，代码会更稳，交互也更自然。

一、先把三种滑动状态看清楚

onScrollStateChanged返回的是ScrollState枚举。这里一共三个值。Dragging表示用户正在跟手拖拽，页面位置跟着输入持续变化。Settling表示用户已经松手，Swiper 正在执行离手动画，可能会继续翻页，也可能会回弹。Idle表示滑动和动画都已经结束，组件停在稳定状态。API 20 的新增声明里已经把这个事件挂在SwiperAttribute上，官方示例和博客里也给出了这三个状态的典型语义。

这三个状态连起来，刚好覆盖了一轮完整的滑动过程。Idle 进入 Dragging，说明用户开始主动操作；Dragging 进入 Settling，说明手指已经离开，组件开始处理后续动画；Settling 回到 Idle，说明最终结果已经落定。业务里只要把这条顺序记住，很多时序判断都会清楚很多。

这里还有一个很容易忽略的点，onScrollStateChanged和onChange解决的不是同一个问题。onScrollStateChanged告诉你滑动过程处在哪个阶段，onChange告诉你索引是否真的变了。用户轻轻拨一下页面又回弹回来，状态回调会完整触发，索引变化可能根本不会发生。做埋点、资源加载、浮层控制时，这个区别一定要分清。

二、先把最小可用版本接起来

这项能力的接法很直接，Swiper 正常写，状态回调挂上去就行。下面这个例子保留了最核心的部分，适合先在项目里跑通。

import{hilog}from'@kit.PerformanceAnalysisKit';import{ScrollState,SwiperController}from'@kit.ArkUI';@Entry@Componentstruct SwiperStateDemo{privateswiperController:SwiperController=newSwiperController();@StatecurrentIndex:number=0;@StatecurrentStateText:string='Idle';build(){Column(){Text(`当前状态:${this.currentStateText}`).fontSize(14).margin({bottom:12});Swiper(this.swiperController){Text('第1页').width('100%').height(280).backgroundColor('#FF6B6B').textAlign(TextAlign.Center).fontSize(36);Text('第2页').width('100%').height(280).backgroundColor('#4ECDC4').textAlign(TextAlign.Center).fontSize(36);Text('第3页').width('100%').height(280).backgroundColor('#45B7D1').textAlign(TextAlign.Center).fontSize(36);}.loop(true).autoPlay(true).interval(3000).indicator(true).onChange((index:number)=>{this.currentIndex=index;hilog.info(0x0000,'SwiperDemo',`当前页索引:${index}`);}).onScrollStateChanged((state:ScrollState)=>{this.currentStateText=this.getStateText(state);hilog.info(0x0000,'SwiperDemo',`滑动状态变化:${this.currentStateText}`);});}.width('100%').padding(20);}privategetStateText(state:ScrollState):string{if(state===ScrollState.Dragging){return'Dragging';}elseif(state===ScrollState.Settling){return'Settling';}return'Idle';}}

这段代码里最重要的地方有两个。一个是索引变化和状态变化分开处理，别把两套逻辑混到一个回调里。另一个是状态值先做一层转换再显示或打日志，后面如果项目里要做统一封装，这层写法会很顺。onScrollStateChanged本身就是 API 20 的新增属性，直接挂在SwiperAttribute上。

三、把状态回调接进业务场景

这项能力最适合优先接到两个地方。一个是浮层控制，一个是资源加载控制。它们都对时序很敏感，也最容易受益于这种状态拆分。

先看浮层控制。Banner 上的标题、说明、按钮，在用户开始拖拽时就应该隐藏，避免遮挡内容。离手动画阶段继续保持隐藏，等页面彻底停住后再恢复。这个逻辑用状态回调来写会非常顺。

import{ScrollState}from'@kit.ArkUI';@Entry@Componentstruct SwiperOverlayDemo{@StateoverlayOpacity:number=1;@StatecurrentIndex:number=0;privaterestoreTimer:number=-1;privatetitles:string[]=['首页推荐','热门活动','新品上架'];build(){Stack({alignContent:Alignment.Bottom}){Swiper(){ForEach(this.titles,(title:string,index:number)=>{Text(title).width('100%').height(320).backgroundColor(index===0?'#FF6B6B':index===1?'#4ECDC4':'#45B7D1').textAlign(TextAlign.Center).fontSize(40).fontColor(Color.White);})}.loop(true).onChange((index:number)=>{this.currentIndex=index;}).onScrollStateChanged((state:ScrollState)=>{this.handleScrollState(state);});Column(){Text(this.titles[this.currentIndex]).fontSize(24).fontColor(Color.White);Text('了解更多 >').fontSize(14).fontColor('#DDDDDD');}.padding(16).backgroundColor('rgba(0,0,0,0.45)').borderRadius(12).margin({bottom:24}).opacity(this.overlayOpacity).transition(TransitionEffect.OPACITY.animation({duration:300}));}.width('100%').height('100%');}privatehandleScrollState(state:ScrollState):void{if(state===ScrollState.Dragging){if(this.restoreTimer!==-1){clearTimeout(this.restoreTimer);this.restoreTimer=-1;}this.overlayOpacity=0;}elseif(state===ScrollState.Settling){this.overlayOpacity=0;}elseif(state===ScrollState.Idle){this.restoreTimer=setTimeout(()=>{this.overlayOpacity=1;this.restoreTimer=-1;},300)asnumber;}}}

这个写法的好处很实际，拖拽一开始就能立刻响应，离手动画阶段不会误闪，恢复显示也有了明确时机。用onChange去做这件事，通常都会慢半拍。

再看图片懒加载。滑动过程中先暂停预加载，等停下来再恢复，这样做很适合图片多、网络紧、设备性能一般的场景。拖拽和惯性动画阶段，用户的注意力本来就在滑动过程里，这时候先把资源压力收住，停下来再补，页面会轻很多。

import{ScrollState}from'@kit.ArkUI';interfaceImageItem{title:string;loaded:boolean;}@Entry@Componentstruct SwiperLazyLoadDemo{@StatecurrentIndex:number=0;@StatecanPreload:boolean=true;@StateimageList:ImageItem[]=[{title:'图片1',loaded:true},{title:'图片2',loaded:false},{title:'图片3',loaded:false},{title:'图片4',loaded:false}];build(){Column(){Swiper(){ForEach(this.imageList,(item:ImageItem)=>{Stack(){if(item.loaded){Text(item.title).width('100%').height(260).backgroundColor('#DCEEFF').textAlign(TextAlign.Center).fontSize(32);}else{Column(){Progress({value:30,total:100}).width(40);Text('加载中...').fontSize(14).margin({top:8});}.width('100%').height(260).backgroundColor('#F5F5F5').justifyContent(FlexAlign.Center);}}})}.onChange((index:number)=>{this.currentIndex=index;this.loadCurrent(index);}).onScrollStateChanged((state:ScrollState)=>{if(state===ScrollState.Dragging||state===ScrollState.Settling){this.canPreload=false;}elseif(state===ScrollState.Idle){this.canPreload=true;this.preloadAdjacent(this.currentIndex);}});Text(`当前页:${this.currentIndex}`).fontSize(12).margin({top:16});}.padding(20);}privateloadCurrent(index:number):void{if(!this.imageList[index].loaded){this.imageList[index].loaded=true;this.imageList=[...this.imageList];}}privatepreloadAdjacent(index:number):void{if(!this.canPreload){return;}consttargets=[(index+1)%this.imageList.length,(index+2)%this.imageList.length];targets.forEach((i)=>{if(!this.imageList[i].loaded){this.imageList[i].loaded=true;}});this.imageList=[...this.imageList];}}

这种写法最适合接在轮播图、图片卡片流、引导页素材预加载这些地方。状态回调一接，资源加载时机会好控制很多。

四、开发里有几个坑要提前避开

第一个坑，是在Dragging状态里塞重逻辑。这个阶段用户正在跟手拖拽，回调触发会很频繁。只要在这里做重计算、网络请求或复杂动画，掉帧的概率会非常高。更稳的做法，是在Dragging里只切轻量状态，把真正耗时的逻辑往Idle挪。

第二个坑，是把Settling当成翻页成功。它只能说明用户已经松手，Swiper 已经进入离手动画，最终结果还没完全落定。翻页成功还是回弹到原位，要靠onChange来判断。做曝光、做索引埋点、做最终状态提交时，这个边界一定要分清。

第三个坑，是忽略版本兼容。onScrollStateChanged从 API 20 开始支持，如果项目还要兼容更低版本，最好加一层能力判断。新版本直接走状态回调，低版本再退回到onAnimationStart、onAnimationEnd和onChange的组合写法。HarmonyOS 的 API 兼容性策略本来就建议按版本做保护，这里也一样。