一、前言：鸿蒙开发为什么首选Swiper做轮播图？

轮播图是鸿蒙APP开发中刚需组件：首页Banner广告、商城活动海报、引导页、图文资讯滑动展示，几乎所有商用鸿蒙项目都会用到。

和前端Web手写轮播不同，鸿蒙ArkUI框架内置Swiper原生轮播组件，无需手写定时器、位移动画、手势监听，官方底层封装好了滑动逻辑、无缝循环、自动播放能力，性能远优于自定义View拼接，适配手机、平板、折叠屏全设备，是鸿蒙开发轮播图的最优解。

很多鸿蒙新手容易踩坑：默认指示器样式丑陋、自动播放不会暂停、循环轮播失效、折叠屏适配异常。本文从零带大家实现商用级轮播图，零第三方依赖，纯官方原生组件，直接复制即可运行。

二、鸿蒙Swiper核心原理初识

Swiper是ArkUI官方提供的容器类组件，核心原理：内部维护页面索引，通过原生渲染引擎完成页面横向/纵向滑动，底层基于鸿蒙图形引擎渲染，脱离JS动画卡顿问题，天然适配鸿蒙万物互联设备。

1. 容器层：Swiper外层容器，定义轮播宽高、滑动方向、动画时长

2. 内容层：通过ForEach循环渲染图片/自定义卡片，作为轮播每一页内容

3. 指示器层：支持官方默认指示器，也可完全自定义圆点指示器

4. 交互层：原生自带手势滑动、自动播放、循环开关，无需额外手势代码

新手小贴士：鸿蒙Swiper默认不开启循环、不开启自动播放，两个属性需要手动配置，这也是新手轮播无法无缝滚动的最常见原因。

三、完整可运行ArkTS代码（HarmonyOS NEXT直接复制运行）

本文代码基于HarmonyOS NEXT Beta5、Stage模型、声明式UI开发，兼容新版鸿蒙开发工具DevEco Studio，分为数据定义、Swiper轮播主体、自定义指示器三部分，注释全覆盖，新手逐行看懂。

1. 完整page页面代码（index.ets）

@Entry @Component struct CarouselPage { // 轮播图网络图片数据源，直接使用公共测试图，无需本地资源 @State bannerList: string[] = [ "https://picsum.photos/id/1/750/360", "https://picsum.photos/id/10/750/360", "https://picsum.photos/id/20/750/360", "https://picsum.photos/id/30/750/360", "https://picsum.photos/id/40/750/360" ] // 记录当前轮播索引，用于联动指示器 @State currentIndex: number = 0 // 轮播自动播放间隔：3000ms = 3秒 private readonly durationTime: number = 3000 build() { Column() { // 轮播图主体 Swiper() { // 循环渲染轮播图片 ForEach(this.bannerList, (imgUrl: string) => { Image(imgUrl) .width('100%') .height(180) .objectFit(ImageFit.Cover) // 图片等比裁切，铺满容器 .borderRadius(12) // 圆角优化，贴合商用UI设计 }, (imgUrl: string) => imgUrl) // 唯一key，提升渲染性能 } // 开启循环轮播 .loop(true) // 开启自动播放 .autoPlay(true) // 设置自动播放间隔时间 .interval(this.durationTime) // 页面拖拽时暂停自动播放，优化交互体验 .disableSwipe(false) // 关闭官方默认指示器，使用自定义圆点指示器 .indicator(false) // 轮播切换动画时长 .duration(400) // 监听轮播切换，更新当前索引 .onChange((index: number) => { this.currentIndex = index }) // 自定义底部圆点指示器 Row() { ForEach(this.bannerList, (item: string, index: number) => { Circle() // 选中圆点放大，未选中圆点缩小 .width(this.currentIndex === index ? 12 : 6) .height(this.currentIndex === index ? 12 : 6) // 选中红色，未选中白色半透明 .fill(this.currentIndex === index ? '#E53E3E' : 'rgba(255,255,255,0.5)') .margin({left:4, right:4}) }) } .margin({top: -20}) .justifyContent(FlexAlign.Center) } .width('100%') .padding(10) .backgroundColor('#F5F5F5') } }