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

鸿蒙新特性：Swiper 轮播组件——构建知识卡片浏览器

news 2026/7/8 6:52:19

在移动应用中，水平滑动浏览是仅次于上下滚动的第二高频手势。无论是 App 首次启动时的引导页、电商首页的广告轮播，还是新闻客户端的热点推荐——Swiper 轮播组件都是承载这些场景的核心 UI 单元。

HarmonyOS NEXT ArkUI 提供了 Swiper 组件——一个高度可定制的轮播容器。它不只是一个"可以滑动的容器"：自动播放、循环模式、自定义指示器和翻页动画共同构成了完整的轮播交互体验。本文将深入讲解 Swiper 组件的完整 API，并构建一个"知识卡片浏览器"——支持滑动翻页、自动轮播、圆点指示器和手动导航。

关键词：HarmonyOS、ArkUI、Swiper、轮播组件、引导页、自动播放、指示器

一、Swiper 组件 API

1.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.currentIndex=index;})

核心属性与方法：

属性/方法	类型	说明
`Swiper(controller)`	构造参数	可选的 SwiperController，用于编程式翻页
`.index()`	number	当前显示页索引（@State 绑定）
`.autoPlay()`	boolean	是否自动轮播
`.loop()`	boolean	是否循环播放（最后一页后回到第一页）
`.interval()`	number	自动轮播间隔（毫秒）
`.indicator()`	Indicator	指示器样式配置
`.duration()`	number	翻页动画时长（毫秒）
`.curve()`	Curve	翻页动画曲线
`.onChange()`	callback	页面切换回调，参数为新索引

1.2 SwiperController

SwiperController是 Swiper 的命令式 API，允许开发者通过代码控制翻页：

privateswiperController:SwiperController=newSwiperController();// 跳转到指定页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:boolean=false;Toggle({type:ToggleType.Switch,isOn:$$this.autoPlay}).onChange((value:boolean)=>{this.autoPlay=value;})

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.currentIndex=index;})

各配置项的含义：

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:SwiperController=newSwiperController();goToPage(index:number):void{this.swiperController.changeIndex(index);}goNext():void{letnext=this.currentIndex+1;if(next<this.getCards().length){this.swiperController.changeIndex(next);}}goPrev():void{letprev=this.currentIndex-1;if(prev>=0){this.swiperController.changeIndex(prev);}}

注意goNext()和goPrev()中的边界检查：在非循环模式下（或需要特殊处理首尾页时），必须确保不会跳转到不存在的索引。Demo 中虽然 Swiper 开启了loop(true)，但"上一页"和"下一页"按钮仍然做了边界检查——按钮在到达边界时会变灰禁用，给用户明确的视觉反馈。

3.4 按钮的禁用状态

"上一页"和"下一页"按钮根据currentIndex动态调整样式：

// 上一页按钮：currentIndex > 0 时可用（蓝色），否则禁用（灰色）.fontColor(this.currentIndex>0?'#1677FF':'#CCCCDD').backgroundColor(this.currentIndex>0?'#F0F5FF':'#F8F9FA')// 下一页按钮同理.fontColor(this.currentIndex<this.getCards().length-1?'#1677FF':'#CCCCDD')

这种即时反馈让用户清楚知道"还能不能继续翻"。如果 Swiper 的loop为true，按钮理论上可以永远可点击——但 Demo 中选择在边界禁用按钮，因为循环模式下"从第 6 页跳到第 1 页"会让用户困惑，而手势滑动支持循环翻页更直觉。

四、进度计数器

标题栏右侧显示"1 / 6"格式的进度：

getProgressText():string{return(this.currentIndex+1).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 开发的核心知识点：

卡片	分类	标题	核心内容
0	ArkUI	声明式 UI 开发范式	@State、build()、if/else、ForEach
1	状态管理	状态驱动 UI 更新	@State、@Prop、@Link、@Provide/@Consume
2	组件化	组件化架构设计	@Component、@Builder、@Entry、组件通信
3	网络	HTTP 网络请求封装	http.createHttp()、request()、Promise、错误处理
4	数据持久化	本地数据存储方案	preferences、relationalStore、KVStore、加密
5	动画	动画与交互设计	animateTo、animation、transition、弹簧动画