前言：不仅仅是“轮播图”

在移动端应用开发中，轮播图（Carousel / Swiper） 可以说是出场率最高的 UI 组件之一。无论是电商 App 的首页焦点图、工具类 App 的新手引导页，还是社交应用中的卡片滑动浏览，背后都离不开 Swiper 的身影。

在传统的 Android 开发中，实现一个带有视差、3D 堆叠或者炫酷指示器的轮播图，往往需要重写 ViewPager 或 RecyclerView，配合极其复杂的坐标变换矩阵计算。而在前端 Web 领域，大家通常依赖重量级的第三方库（如 Swiper.js）。

但令人惊喜的是，在 HarmonyOS（鸿蒙）的 ArkTS 声明式 UI 框架中，官方原生提供的 Swiper 组件 极其强大。它不仅仅是一个简单的图片轮播器，更是一个高度可定制的通用卡片切换引擎。

本文将基于一份涵盖七大核心应用场景的 ArkTS 源码，带您从基础属性入手，逐层深入，手把手教您如何利用原生 Swiper 轻松实现 3D 堆叠、一屏多显、自定义异形指示器以及代码级别的精准控制。

---

一、 万丈高楼平地起：基础轮播（默认行为）

我们在遇到任何复杂组件时，第一步都应该是掌握其最纯粹的默认形态。

1.1 核心代码剖析

// 一、基础轮播
Swiper() {
  CardItem({ num: 1, color: '#42A5F5', text: '第 1 页' })
  CardItem({ num: 2, color: '#EF5350', text: '第 2 页' })
  CardItem({ num: 3, color: '#66BB6A', text: '第 3 页' })
  CardItem({ num: 4, color: '#FFA726', text: '第 4 页' })
}
.height(150)
.autoPlay(false) // 关闭自动播放
.loop(false)     // 关闭无限循环
.indicator(true) // 开启默认指示器

1.2 行为学解析与业务思考

当你在 Swiper 中直接塞入子组件时，它默认占据整个容器的宽高，并自带分页滑动的手势阻尼效果。

• 非循环模式（loop: false）：在这种模式下，滑到第一页或最后一页时，系统会提供经典的 边缘回弹（Spring 动效）。这明确地向用户传达了“已经没有更多内容”的物理反馈。
• 适用场景：App 的初次启动引导页（Onboarding）、简单的表单分步填写向导。此类场景通常要求用户按照固定顺序阅读，不需要无限循环。

---

二、 视觉欺骗的艺术：实现 3D 卡片堆叠效果

很多设计师喜欢在一屏内展示一张完整的卡片，并在侧边露出下一张卡片的边缘，营造出一种“后面还有内容”的 3D 堆叠错觉。这在音乐播放器的专辑切换、电影票务 App 中非常流行。

2.1 核心代码剖析

// 二、3D 卡片堆叠（核心效果）
Swiper() {
  StackCard({ num: 0, color: '#1A237E' })
  // ... 更多卡片
}
.height(220)
.autoPlay(true)
.loop(true)
.indicator(false) // 隐藏指示器，突出沉浸感
.displayCount(1.5) // 核心魔法：视口内显示 1.5 张卡片
.curve(Curve.FastOutSlowIn) // 使用非线性物理动效曲线
.duration(400)

2.2 核心魔法原理解析：displayCount 的妙用

• 小数视野（displayCount: 1.5）：这是 ArkTS Swiper 的一个杀手级特性。displayCount 不仅可以是整数，还可以是小数！设置为 1.5 意味着当前卡片占据 1/1.5 = 66.6% 的宽度，剩下的 33.3% 用于展示下一张卡片的前半截。
• 配合内边距与阴影：光有 displayCount 还不够。在源码的 StackCard 子组件中，作者将卡片自身宽高设置为 85% 并居中，外加 .shadow({ radius: 16, color: 'rgba(0,0,0,0.2)', offsetY: 6 }) 阴影。这种视口裁切 + 内部缩小 + 阴影渲染的组合拳，直接在二维平面上伪造出了 3D 景深的层次感。

---

三、 高效信息流分发：多卡片同时展示

在电商的“猜你喜欢”或者视频 App 的“相关推荐”板块，一屏只展示一张卡片效率太低，我们需要同时展示多个横向滚动的 Item。

3.1 核心代码剖析

// 三、多卡片同时展示
Swiper() {
  ColorCard({ num: 1, color: '#42A5F5' })
  // ...
}
.height(160)
.displayCount(3) // 核心：视口内固定显示 3 张完整卡片
.loop(true)
.itemSpace(10)   // 核心：卡片之间的物理间距为 10vp
.curve(Curve.Friction) // 使用摩擦力曲线，手感更厚重

3.2 响应式排版的最佳实践

使用 displayCount(3) 配合 itemSpace(10)，Swiper 会自动帮你计算单张卡片的绝对宽度，并且无论屏幕尺寸如何变化（从手机切换到平板、甚至折叠屏折叠展开），都能严丝合缝地保证屏幕内不多不少恰好显示 3 张。这种声明式的布局大大降低了我们适配多终端的屏幕计算压力。

---

四、 拒绝千篇一律：自定义指示器 (Indicator)

默认的小圆点指示器往往无法满足精细化 UI 的设计规范。ArkTS 为我们提供了专门的指示器配置对象。

4.1 核心代码剖析：长短条动态指示器

// 四、自定义指示器
Swiper() {
  // ... 
}
.indicator(
  new DotIndicator()
    .itemWidth(20)         // 未选中时的圆点宽度
    .itemHeight(6)         // 未选中时的高度
    .selectedItemWidth(28) // 选中时的宽度（拉长）
    .selectedItemHeight(8) // 选中时的高度（略微加粗）
    .color('#BBDEFB')      // 默认颜色
    .selectedColor('#1565C0') // 选中时的主色调高亮
)

4.2 为什么这样设计？

这种“选中项拉长变宽”的指示器设计语言在 iOS 和主流 Android 系统中被广泛采用。它比单纯改变颜色具有更高的视觉显著性，不仅对色弱用户更加友好，还能在页面快速滑动时提供清晰的锚点定位。ArkTS 通过 DotIndicator 对象将其彻底封装，开发者只需几个属性即可实现丝滑的形态渐变动画。

---

五、 横竖皆可：打破水平滚动的刻板印象

短视频时代（如抖音、快手）带火了垂直方向的整屏滑动。Swiper 当然也原生支持跨轴滚动。

💡 洞察与纠错：
在原源码的注释中写着“水平 Swiper + 弹性曲线”，但标题却是“五、垂直卡片切换”。这里特别需要指正：要让 Swiper 实现真正的上下垂直滑动，必须显式配置 .vertical(true) 属性。

5.1 垂直滑动的正确打开方式

// 五、垂直卡片切换（修正版）
Swiper() {
  VertCard({ num: 1, color: '#1A237E' })
  // ...
}
.height(300)
.loop(true)
.vertical(true) // 🔥 关键属性：将其设为 true 开启上下滑动
.indicator(
  new DotIndicator()
    .itemWidth(8).itemHeight(8)
    // 垂直模式下，指示器通常需要靠左或靠右放置，可通过定制属性解决
)
.curve(Curve.FastOutSlowIn)

业务应用： 配合 .height('100%') 全屏拉满，即可在五分钟内撸出一个丝滑的短视频上下滑动框架骨架。

---

六、 数据看板的常客：无限循环与数字指示器

如果轮播内容是大量的文本流或者 Banner 广告，采用圆点指示器不仅占地方，还无法精确告知用户总数。此时，数字指示器出场了。

6.1 数字指示器配置

// 六、无限循环 + 自动播放
Swiper() {
  // ...
}
.autoPlay(true)
.loop(true)
.indicator(
  new DigitIndicator() // 使用数字指示器代替圆点
    .digitFont({ size: 14, weight: FontWeight.Bold })
    .fontColor('#FFFFFF')
    .selectedFontColor('#FFD54F')
)

视觉效果： 它会在底部生成如 1 / 5 的字样，并且页码切换时会自动带有淡入淡出的数字更替动效。这在全屏大图预览界面（Gallery） 或 PDF 阅读器 中是标配功能。

---

七、 MVC 理念再现：使用 SwiperController 实现代码控制

并不是所有的滑动都要靠用户的手指。如果我们在页面底部有两个独立于 Swiper 之外的“上一页/下一页”按钮，该如何控制轮播图？

ArkTS 使用控制器模式（Controller Pattern） 实现了 UI 与逻辑的完美解耦。

7.1 控制器实战剖析

@Component
struct InteractiveSwiper {
  // 1. 实例化核心控制器
  private swiperCtx: SwiperController = new SwiperController()

  build() {
    Column() {
      // 2. 将控制器绑定给目标 Swiper
      Swiper(this.swiperCtx) {
        CtrlCard({ num: 1 })
        // ...
      }
      
      Row() {
        // 3. 在外部通过控制器 API 触发滑动
        Button('上一步').onClick(() => { 
          this.swiperCtx.showPrevious() 
        })
        Button('下一步').onClick(() => { 
          this.swiperCtx.showNext() 
        })
      }
    }
  }
}

深度理解：
SwiperController 的实例不仅可以调用 .showNext() 和 .showPrevious()，还提供了一个非常关键的方法 .changeIndex(index: number, useAnimation: boolean)。这让你可以在复杂的业务逻辑中（例如用户提交完表单第一步，网络请求成功后），自动控制页面丝滑跳转到表单的指定步骤。

---

运行界面

八、 核心知识资产盘点与避坑指南

为了方便大家在实际业务中快速查阅，特此总结三份高能速查表。

8.1 Swiper 核心能力一览表

属性名 (Property)	类型与默认值	核心功能与业务场景
loop	boolean (默认 true)	开启无限循环。在非循环下，首尾有弹簧回弹效；循环模式下无缝衔接。
autoPlay	boolean (默认 false)	自动轮播。常用于首页 Banner。注意：页面隐藏或退到后台时，请通过状态机暂停，以节省 CPU 与电池。
interval	number (默认 3000)	配合 autoPlay 使用，设定自动轮播的停留时间（毫秒）。
displayCount	`number	string` (默认 1)
itemSpace	`number	string` (默认 0)
vertical	boolean (默认 false)	决定横滑还是竖滑。实现类似短视频上下翻页核心属性。

8.2 指示器组件深度对比表

指示器类型	适用场景	核心定制能力
DotIndicator	最通用。图文 Banner、新手引导、精简表单	支持宽、高、颜色、选中态高亮的独立定制，可实现“胶囊长条形”渐变动效。
DigitIndicator	多图画廊、漫画阅读、需要显示总页数的场景	支持字体大小、粗细、字体颜色、选中态颜色的独立配置。
false	沉浸式内容、有外部自定义按钮控制的场景	直接隐藏内置指示器，将控制权交给外部自定义组件。

8.3 动效灵魂：Curve（插值曲线）枚举表

曲线类型 (Curve)	视觉体感	推荐用法
Linear	匀速，无任何加减速	极其刻板，除非实现机械式的连续滚动，否则不推荐。
FastOutSlowIn	快速启动，缓慢停止	极其符合人类阅读习惯。滑动瞬间反馈迅速，即将停止时让人眼有足够时间聚焦。【最推荐】
Friction	带有阻尼感，仿佛在砂纸上滑动	适合重量级的卡片翻页，给予一种物理厚重感。
SpringMotion	强烈的弹簧回弹	适合极具活力、年轻化的 UI 风格。

---

九、 性能调优（Performance Tips）：大规模数据的暗礁

本文源码为了演示直观，在 Swiper 内部直接采用了列举多个自定义卡片组件的方式。但是，在企业级真实开发中，请务必当心内存爆炸！

如果你从后端接口获取了 50 张乃至 100 张图片塞进 Swiper，千万不要使用 ForEach！由于 Swiper 是横向预渲染的，庞大的数据量会导致瞬间创建上百个离屏 DOM 节点，直接造成卡顿甚至 OOM（内存溢出）崩溃。

🔥 最佳实践： 面对海量数据的滑动，必须将 Swiper 内部数据源替换为 LazyForEach。LazyForEach 只会实例化当前屏幕可见的卡片以及其前后紧邻的 1-2 张卡片，随着滑动动态销毁和创建节点，将内存占用永远保持在一个极低的常量极别。

---

结语

从小巧灵动的轮播圆点，到深邃优雅的 3D 卡片栈；从水平的画廊漫游，到垂直的视频冲浪，ArkTS 的 Swiper 组件用一套高度内聚的声明式 API，优雅地化解了移动端 UI 交互的无数难题。

它不仅是一个 UI 容器，更是你展现无尽创意的画板。掌握这七大场景，你几乎可以应对主流 App 设计图上的任何横滑/竖滑动效需求。