在移动应用中水平滑动浏览是仅次于上下滚动的第二高频手势。无论是 App 首次启动时的引导页、电商首页的广告轮播还是新闻客户端的热点推荐——Swiper 轮播组件都是承载这些场景的核心 UI 单元。HarmonyOS NEXT ArkUI 提供了 Swiper 组件——一个高度可定制的轮播容器。它不只是一个可以滑动的容器自动播放、循环模式、自定义指示器和翻页动画共同构成了完整的轮播交互体验。本文将深入讲解 Swiper 组件的完整 API并构建一个知识卡片浏览器——支持滑动翻页、自动轮播、圆点指示器和手动导航。关键词HarmonyOS、ArkUI、Swiper、轮播组件、引导页、自动播放、指示器一、Swiper 组件 API1.1 基本用法Swiper(controller?:SwiperController){ForEach(this.cards,(card:StudyCard){Column(){/* 卡片内容 */}})}.index(this.currentIndex).autoPlay(this.autoPlay).loop(true).interval(3000).indicator(Indicator.dot()).duration(400).curve(Curve.EaseInOut).onChange((index:number){this.currentIndexindex;})核心属性与方法属性/方法类型说明Swiper(controller)构造参数可选的 SwiperController用于编程式翻页.index()number当前显示页索引State 绑定.autoPlay()boolean是否自动轮播.loop()boolean是否循环播放最后一页后回到第一页.interval()number自动轮播间隔毫秒.indicator()Indicator指示器样式配置.duration()number翻页动画时长毫秒.curve()Curve翻页动画曲线.onChange()callback页面切换回调参数为新索引1.2 SwiperControllerSwiperController是 Swiper 的命令式 API允许开发者通过代码控制翻页privateswiperController:SwiperControllernewSwiperController();// 跳转到指定页this.swiperController.changeIndex(3);// 显示下一页this.swiperController.showNext();// 显示上一页this.swiperController.showPrevious();changeIndex(index)是最常用的方法——它支持跳转到任意页面并自动播放翻页动画。当用户点击指示器圆点或跳过按钮时都需要通过changeIndex实现编程式跳转。1.3 自动播放与循环自动播放是 Swiper 在轮播广告中的核心价值.autoPlay(true)// 开启自动轮播.interval(3000)// 每 3 秒翻页.loop(true)// 最后一页后回到第一页当loop为true时用户在最后一页继续滑动会回到第一页反之亦然。自动播放也会在到达最后一页后回到第一页继续循环。如果loop为false自动播放到达最后一页后停止。需要注意的是autoPlay的值是一个boolean而非是否开启自动播放的开关。它可以直接绑定State变量让用户通过 Toggle 控制自动播放的开启与关闭StateautoPlay:booleanfalse;Toggle({type:ToggleType.Switch,isOn:$$this.autoPlay}).onChange((value:boolean){this.autoPlayvalue;})1.4 Indicator 指示器指示器是轮播组件最重要的附属 UI——它告诉用户当前在第几页和总共有多少页。ArkUI 提供了Indicator构建器.indicator(Indicator.dot().itemWidth(8).itemHeight(8).selectedItemWidth(20).selectedItemHeight(8).color(#D0D0DD)// 未选中圆点颜色.selectedColor(#1677FF))// 选中圆点颜色.dot()指定指示器样式为圆点也支持.digit()数字样式。selectedItemWidth设为 20未选中时 8可以实现选中圆点变长条的动画效果——这种小细节是用户感知到轮播组件品质感的关键。二、知识卡片浏览器的整体设计2.1 页面架构本文 Demo 构建一个知识卡片浏览器模拟学习类 App 的卡片浏览体验SwiperStudyPage ├── 标题栏 — 知识卡片 进度计数1 / 6 ├── Swiper 区域主体占据剩余空间 │ ├── 卡片 0: ArkUI 声明式开发 │ ├── 卡片 1: 状态管理 │ ├── 卡片 2: 组件化架构 │ ├── 卡片 3: 网络请求 │ ├── 卡片 4: 数据持久化 │ └── 卡片 5: 动画系统 └── 底部控制栏 ├── 自动轮播开关▶ / ⏸ ├── 上一页按钮 └── 下一页按钮2.2 数据结构classStudyCard{id:number;category:string;// 分类名ArkUI / 状态管理 / 网络 / ...catColor:string;// 分类主题色emoji:string;// 卡片图标title:string;// 卡片标题summary:string;// 摘要说明points:string[];// 知识点列表4 条}6 张卡片覆盖了 HarmonyOS 开发的 6 个核心领域。每张卡片的catColor不同确保视觉多样性。卡片采用class定义而非interface原因与前文一致——ArkTS 不支持对象展开运算符class 配合构造函数是创建对象的标准方式。2.3 卡片布局每张卡片是一个白色圆角矩形包含五个元素Emoji 图标顶部56px 大图标视觉锚点分类标签图标下方带主题色的文字 半透明背景标题标签下方20px 加粗黑色摘要标题下方14px 灰色最多 4 行知识点列表摘要下方4 个•开头的条目主题色圆点 灰色文字卡片在 Swiper 内通过padding与屏幕边缘保持间距露出淡灰色背景——这种卡片在背景上滑动的视觉效果比卡片占满整屏更有层次感。三、Swiper 的核心配置3.1 基础配置Swiper(this.swiperController){ForEach(this.getCards(),(card:StudyCard,idx:number){Column(){// 卡片内容}},(card:StudyCard,idx:number)card.id.toString())}.index(this.currentIndex).autoPlay(this.autoPlay).loop(true).interval(3000).indicator(Indicator.dot()...).duration(400).curve(Curve.EaseInOut).onChange((index:number){this.currentIndexindex;})各配置项的含义loop(true)循环模式——第 6 页继续向前滑回到第 1 页interval(3000)自动轮播时每 3 秒翻页一次duration(400)翻页动画持续 400 毫秒curve(Curve.EaseInOut)缓入缓出曲线让翻页动画更自然onChange每次页面切换后更新currentIndex驱动进度文字和按钮状态更新3.2 Indicator 的定制.indicator(Indicator.dot().itemWidth(8).itemHeight(8).selectedItemWidth(20).selectedItemHeight(8).color(#D0D0DD).selectedColor(#1677FF))指示器的关键设计选中圆点宽度为 20未选中为 8——形成加长选中圆点的效果。颜色方面未选中为浅灰#D0D0DD选中为品牌蓝#1677FF视觉对比清晰但不刺眼。指示器位置默认在 Swiper 底部居中。在 Demo 中指示器位于卡片下方、底部控制栏上方这是引导页和卡片浏览器的常见布局。3.3 SwiperController 的编程式控制Demo 中三个操作都需要通过SwiperController实现privateswiperController:SwiperControllernewSwiperController();goToPage(index:number):void{this.swiperController.changeIndex(index);}goNext():void{letnextthis.currentIndex1;if(nextthis.getCards().length){this.swiperController.changeIndex(next);}}goPrev():void{letprevthis.currentIndex-1;if(prev0){this.swiperController.changeIndex(prev);}}注意goNext()和goPrev()中的边界检查在非循环模式下或需要特殊处理首尾页时必须确保不会跳转到不存在的索引。Demo 中虽然 Swiper 开启了loop(true)但上一页和下一页按钮仍然做了边界检查——按钮在到达边界时会变灰禁用给用户明确的视觉反馈。3.4 按钮的禁用状态上一页和下一页按钮根据currentIndex动态调整样式// 上一页按钮currentIndex 0 时可用蓝色否则禁用灰色.fontColor(this.currentIndex0?#1677FF:#CCCCDD).backgroundColor(this.currentIndex0?#F0F5FF:#F8F9FA)// 下一页按钮同理.fontColor(this.currentIndexthis.getCards().length-1?#1677FF:#CCCCDD)这种即时反馈让用户清楚知道还能不能继续翻。如果 Swiper 的loop为true按钮理论上可以永远可点击——但 Demo 中选择在边界禁用按钮因为循环模式下从第 6 页跳到第 1 页会让用户困惑而手势滑动支持循环翻页更直觉。四、进度计数器标题栏右侧显示1 / 6格式的进度getProgressText():string{return(this.currentIndex1).toString().concat( / ).concat(this.getCards().length.toString());}currentIndex从 0 开始与数组索引一致因此显示时加 1。这个数字随着onChange回调更新currentIndex而实时变化——每次翻页进度文字同步更新。进度计数器给用户两个信息当前在第几页第一个数字总共多少页第二个数字在引导页中这种进度表示法比仅显示圆点指示器更精确——用户不仅知道相对位置第 2 个圆点高亮还知道绝对位置第 2 页共 6 页。五、自动播放控制5.1 开关设计底部控制栏左侧是自动播放开关Row(){Text(this.autoPlay?⏸:▶)Text(this.autoPlay?停止轮播:自动轮播)}.onClick((){this.toggleAutoPlay();})开关的文字和图标根据状态变化未开启显示 “▶ 自动轮播”提示用户可以开启已开启显示 “⏸ 停止轮播”提示用户可以暂停toggleAutoPlay()直接翻转this.autoPlay而 Swiper 的.autoPlay(this.autoPlay)双向绑定会自动响应状态变化。5.2 开启自动播放的体验当用户点击自动轮播后Swiper 每 3 秒自动翻到下一页。翻页动画使用Curve.EaseInOut——开始和结束时缓慢、中间加速模拟物理世界中的惯性运动。如果在自动播放过程中用户手动滑动或点击上一页/下一页按钮自动播放的计时器会重置——这是 Swiper 的内置行为确保用户的手动操作不会被自动播放打断。六、6 张知识卡片的内容设计每张卡片是一个 HarmonyOS 开发的核心知识点卡片分类标题核心内容0ArkUI声明式 UI 开发范式State、build()、if/else、ForEach1状态管理状态驱动 UI 更新State、Prop、Link、Provide/Consume2组件化组件化架构设计Component、Builder、Entry、组件通信3网络HTTP 网络请求封装http.createHttp()、request()、Promise、错误处理4数据持久化本地数据存储方案preferences、relationalStore、KVStore、加密5动画动画与交互设计animateTo、animation、transition、弹簧动画每张卡片 4 个知识点以•列表形式展现在摘要下方。这些知识点不是随机的——它们恰好覆盖了 HarmonyOS 应用开发的核心技术栈让 Demo 不仅有展示价值也有学习参考价值。七、交互流程演示7.1 首次进入打开页面Swiper 显示第 1 张卡片ArkUI 声明式开发。标题栏显示1 / 6指示器第一个圆点为蓝色长条其余为灰色小圆点。上一页按钮为灰色禁用状态当前在首页下一页按钮为蓝色可用状态。7.2 手势滑动向左滑动手指从右往左。卡片以 EaseInOut 曲线翻到第 2 张状态管理。onChange触发currentIndex更新为 1。标题栏进度变为2 / 6指示器第二个圆点变蓝变长第一个恢复为灰色小圆点。两个导航按钮都变为蓝色可用状态既不在首页也不在末页。7.3 按钮翻页点击下一页按钮翻到第 3 张卡片组件化架构。再点击上一页翻回第 2 张。按钮导航与手势滑动可以交替使用currentIndex始终保持同步。7.4 自动轮播点击▶ 自动轮播按钮切换为⏸ 停止轮播。Swiper 每 3 秒自动翻页进度文字和指示器实时同步。翻到第 6 张后loop 模式自动回到第 1 张继续循环。点击⏸ 停止轮播自动播放暂停。7.5 到达末页连续点击下一页到达第 6 张动画系统。标题栏显示6 / 6指示器最后一个圆点高亮。下一页按钮变为灰色禁用状态上一页仍为蓝色可用。八、Swiper 的适用场景8.1 引导页App 首次启动时的引导页是 Swiper 最经典的应用。每页展示一个核心功能介绍用户滑动浏览后点击开始使用进入主界面。本文 Demo 的知识卡片浏览器在结构上与引导页一致——Swiper 指示器 导航按钮——只是内容从功能介绍换成了知识卡片。8.2 广告轮播电商和新闻 App 首页顶部的 Banner 轮播是 Swiper 的另一个高频场景。通常配合autoPlay(true)和loop(true)实现自动循环播放每 2-3 秒切换一张广告图。8.3 卡片浏览社交媒体和内容 App 中全屏卡片式内容浏览如 Tinder 的卡片滑动、抖音的上下滑动本质上是 Swiper 的方向变体。ArkUI 的 Swiper 支持.vertical(true)纵向滑动模式可以构建上下翻页的短视频或内容流。8.4 图片浏览器图片详情页中左右滑动查看前后图片也是一个经典的 Swiper 用例。配合Image组件的缩放能力可以实现完整的图片浏览体验。九、总结本文通过知识卡片浏览器这个实战案例全面讲解了 ArkUI Swiper 轮播组件的使用方法。核心知识点包括Swiper 基础 API构造参数、index 绑定、loop 循环、interval 间隔SwiperControllerchangeIndex()编程式翻页支持跳转到任意页Indicator 指示器.dot()圆点样式 尺寸/颜色定制自动播放控制autoPlayloopinterval三件套配合 Toggle 开关onChange 回调页面切换时同步currentIndex驱动进度文字和按钮状态导航按钮上一页/下一页 边界禁用状态 动态颜色Swiper 是移动应用中使用频率最高的组件之一。一个好的轮播体验不仅仅是能左右滑动——它需要清晰的进度指示、平滑的翻页动画、可控的自动播放和精确的编程式导航。ArkUI 的 Swiper 组件提供了这些能力的完整封装让开发者可以将精力集中在卡片内容的设计上。