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

鸿蒙学习手册(HarmonyOSNext_API16)_应用开发UI设计:Swiper

news 来源：原创 2025/5/14 1:58:21

HarmonyOS Swiper 轮播组件详解

Swiper 组件是 HarmonyOS 中用于实现滑动轮播的核心工具，适用于首页推荐、图片展示等场景。以下从基础使用到高阶功能的全面解析：

一、基础轮播搭建

场景：快速创建一个包含3个页面的水平轮播。

Swiper() {  
  Text('页面1')  
    .width('90%')  
    .height('100%')  
    .backgroundColor(Color.Gray)  
  Text('页面2')  
    .width('90%')  
    .height('100%')  
    .backgroundColor(Color.Green)  
  Text('页面3')  
    .width('90%')  
    .height('100%')  
    .backgroundColor(Color.Pink)  
}  
.loop(true) // 开启循环  
.indicator(true) // 显示默认导航点  
.autoPlay(true) // 自动播放  
.interval(3000) // 3秒切换

效果：

自动循环播放，底部显示导航点。
每3秒切换页面，支持手动滑动。

二、核心功能配置

1. 循环播放 (`loop`)

默认开启 (loop=true)：滑到最后一页可继续滑动到第一页。
关闭循环 (loop=false)：滑到边缘时无法继续滑动。

适用场景：

商品详情页图片展示 → 关闭循环（避免用户误滑出范围）。
广告轮播 → 开启循环（无限滚动提升曝光）。

2. 自动播放 (`autoPlay`)

开启：autoPlay(true) + interval(毫秒)。
暂停：用户手动滑动时自动暂停，需代码手动重启。

优化技巧：

.autoPlay(true)  
.interval(5000) // 5秒切换  
.onTouch(event => {  
  if (event.type === TouchType.Down) {  
    // 用户触摸时暂停自动播放  
    swiperController.stopAutoPlay();  
  }  
})

3. 导航点定制 (`indicator`)

默认样式：

居中显示小圆点，选中态高亮。

自定义样式：

.indicator(  
  Indicator.dot()  
    .left(20) // 左侧偏移20vp  
    .itemWidth(10) // 默认点宽度  
    .itemHeight(10)  
    .selectedItemWidth(20) // 选中点宽度  
    .selectedItemHeight(10)  
    .color(Color.Gray) // 默认颜色  
    .selectedColor(Color.Red) // 选中颜色  
)

箭头显示：

.displayArrow({  
  showBackground: true, // 显示箭头背景板  
  arrowSize: 24, // 箭头大小  
  arrowColor: Color.Blue,  
  backgroundSize: 40, // 背景板尺寸  
  backgroundColor: Color.White  
})

4. 轮播方向 (`vertical`)

水平轮播（默认）：.vertical(false)。
垂直轮播：.vertical(true)。

适用场景：

竖向长图展示（如服装搭配）。
新闻客户端垂直翻页阅读。

5. 多页面同屏 (`displayCount`)

显示2个子页面：

Swiper() {  
  // 添加4个子组件  
}  
.displayCount(2) // 每屏显示2个

效果：

左右滑动时，每次切换2个页面。
导航点数量自动适配（如4页 → 2个导航点）。

三、高阶功能：自定义动画

场景：实现卡片3D翻转效果。

.customContentTransition({  
  timeout: 1000, // 动画时长  
  transition: (proxy: SwiperContentTransitionProxy) => {  
    // 动态修改透明度、缩放、位移  
    this.opacityList[proxy.index] = 1 - Math.abs(proxy.position);  
    this.scaleList[proxy.index] = 1 - Math.abs(proxy.position) * 0.2;  
    this.translateList[proxy.index] = proxy.position * 100;  
  }  
})

参数解析：

proxy.position：当前页面滑动进度（-1到1）。
proxy.mainAxisLength：轮播主轴长度（水平为宽度，垂直为高度）。

四、性能优化与避坑指南

1. 预加载机制

Swiper()  
  .cachedCount(2) // 预加载前后2页

原理：提前加载相邻页面，减少滑动卡顿。

2. 动态数据加载

使用 ForEach 动态渲染子组件：

ForEach(this.imageList, (item: ImageData) => {  
  Image(item.url)  
    .width('100%')  
    .height('100%')  
})

3. 常见问题

导航点错位：确保子组件数量与 displayCount 匹配。
自动播放失效：检查是否在触摸事件中调用了 stopAutoPlay() 但未重启。

五、完整案例：带控制器的轮播

@Entry  
@Component  
struct ControlledSwiper {  
  private swiperController: SwiperController = new SwiperController();  

  build() {  
    Column() {  
      Swiper(this.swiperController) {  
        // 添加子组件  
      }  
      Row() {  
        Button('上一页').onClick(() => this.swiperController.showPrevious())  
        Button('下一页').onClick(() => this.swiperController.showNext())  
        Button('跳转至第3页').onClick(() => this.swiperController.changeIndex(2))  
      }  
    }  
  }  
}