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

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))  
      }  
    }  
  }  
}  

---

总结 ：

Swiper 组件通过灵活配置可实现：

• 基础轮播 → 广告展示
• 多页同屏 → 商品分类
• 垂直滚动 → 长文阅读
• 自定义动画 → 特色交互

掌握其核心属性和性能优化技巧，可轻松应对复杂场景需求。