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

HarmonyOS之Swiper全解析

news 2025/9/19 5:45:50

一、📌 Swiper 基本功能概述

Swiper 是 HarmonyOS ArkUI 提供的滑动视图容器，用于在多个子组件之间进行横向或纵向滑动切换。常用于：

图片轮播（如首页广告 Banner）
内容页分页切换（如新闻模块）
引导页（App 首次启动）
商品浏览、图册展示等

🌟 核心能力

功能	说明
自动轮播	定时切换页面
循环播放	循环切换首尾项
导航指示器	支持圆点或数字页码样式
动画效果	支持 `fade`、`spring` 等过渡动效
滑动方向	支持横向/纵向滑动切换
控制器	可手动控制切换、监听索引

二、🔰 Swiper 基础用法详解

✅ 1. 最基础的用法

Swiper() {Text('页面 1')Text('页面 2')Text('页面 3')
}

📌 说明：默认横向滑动，不自动播放，无导航点。

✅ 2. 添加基础配置（自动轮播、循环、间隔）

Swiper() {Image('img1.jpg')Image('img2.jpg')Image('img3.jpg')
}
.autoPlay(true)      // 开启自动轮播
.interval(3000)      // 每 3 秒切换
.loop(true)          // 无限循环
.height(200)         // 设置高度
.indicator(true)     // 显示默认圆点导航

✅ 3. 设置滑动方向（纵向滑动）

Swiper() {Text('新闻 A')Text('新闻 B')Text('新闻 C')
}
.vertical(true)      // 设置为纵向滑动

✅ 4. 设置动画时长

Swiper().duration(500)     // 每次切换动画 500ms

✅ 5. 自定义指示器样式

Swiper().indicatorStyle({size: 10,selectedColor: '#FF0000',color: '#AAAAAA',mask: false})

三、🎯 Swiper 高级用法详解

✅ 1. 使用 `onChange()` 监听当前页索引

@State currentPage: number = 0Swiper().onChange((index: number) => {this.currentPage = index})Text(`当前页: ${this.currentPage}`)

✅ 2. 使用 `SwiperController` 精准控制翻页

@State swiperCtrl: SwiperController = new SwiperController()Swiper(this.swiperCtrl) {Text('第一页')Text('第二页')Text('第三页')
}// 外部按钮控制
Row() {Button('上一页').onClick(() => {this.swiperCtrl.showPrevious()})Button('下一页').onClick(() => {this.swiperCtrl.showNext()})
}

✅ 3. 使用 `customIndicator` 自定义页码

@State index: number = 0Swiper().onChange((i) => this.index = i).customIndicator(() => {Row() {Text(`${this.index + 1}/3`).fontColor('#FFFFFF').backgroundColor('#00000080').padding(6).borderRadius(8)}})

✅ 4. 懒加载内容 + 性能优化（LazyForEach + cachedSize）

@State imageList: string[] = ['a.jpg', 'b.jpg', 'c.jpg']Swiper().cachedSize(1)   // 每次缓存前后 1 页
{LazyForEach(this.imageList, (item) => {Image(item).width('100%').height(200)})
}

✅ 5. 禁用滑动 + 手势冲突处理（嵌套 Scroll）

Swiper().disableSwipe(true)
{List() {ForEach([1, 2, 3], (i) => {ListItem() { Text(`内容 ${i}`) }})}
}

📌 手动处理滑动时可用 onTouch() + Gesture 实现手动控制。

四、💼 实际开发场景实战案例

✅ 案例 1：电商首页 Banner 广告轮播图

@State banners: string[] = ['sale.jpg', 'new.jpg', 'hot.jpg']Swiper().autoPlay(true).interval(4000).loop(true).cachedSize(2)
{ForEach(this.banners, (url) => {Image(url).objectFit(ImageFit.Cover).width('100%').height(200)})
}

✅ 案例 2：引导页（带分页数字）

@State currentPage: number = 0Swiper().loop(false).onChange((index) => this.currentPage = index).customIndicator(() => {Row() {Text(`${this.currentPage + 1}/3`).fontColor('#fff').backgroundColor('#00000099').padding(8).borderRadius(12)}})
{Text('欢迎使用 App').fontSize(20).fontWeight(FontWeight.Bold)Text('高效 · 安全 · 美观').fontSize(18)Text('立即开始体验').fontSize(18)
}

✅ 案例 3：嵌套滑动内容（Swiper + Tab 联动）

@State currentTab: number = 0
@State swiperCtrl: SwiperController = new SwiperController()// 顶部 Tab
Row() {['新闻', '视频', '推荐'].forEach((label, index) => {Button(label).backgroundColor(this.currentTab == index ? '#FF0000' : '#CCC').onClick(() => {this.currentTab = indexthis.swiperCtrl.show(index)})})
}Swiper(this.swiperCtrl).onChange((index) => this.currentTab = index)
{Text('新闻内容页')Text('视频内容页')Text('推荐内容页')
}

五、⚠️ 注意事项与实践建议

项目	建议
子组件复杂	使用 `LazyForEach` 配合 `cachedSize`
页面过多	懒加载内容以减少内存占用
手势冲突	使用 `.disableSwipe(true)` 并加自定义手势
轮播稳定性	避免在切换过程中修改数据数组
API 兼容性	`digitIndicator` 需 API 10+
动画优化	使用 `.animationDuration()`、`.animationEasing()` 自定义体验