## 目录

1. [引言：一屏多卡的意义](#1-引言一屏多卡的意义)
2. [displayCount 属性详解](#2-displaycount-属性详解)
   - [2.1 基本概念](#21-基本概念)
   - [2.2 宽度计算公式](#22-宽度计算公式)
   - [2.3 不同数值的视觉效果](#23-不同数值的视觉效果)
3. [itemSpace：卡片间距控制](#3-itemspace卡片间距控制)
4. [实战：8 张电影推荐卡片轮播](#4-实战8-张电影推荐卡片轮播)
5. [代码逐段解析](#5-代码逐段解析)
   - [5.1 数据模型：8 种配色方案](#51-数据模型8-种配色方案)
   - [5.2 CardView：渐变色卡片的叠层构建](#52-cardview渐变色卡片的叠层构建)
   - [5.3 build()：displayCount + itemSpace 核心配置](#53-builddisplaycount--itemspace-核心配置)
6. [displayCount 与常规 Swiper 的对比](#6-displaycount-与常规-swiper-的对比)
7. [常见问题与解决方案](#7-常见问题与解决方案)
8. [本系列七篇全览](#8-本系列七篇全览)
9. [总结](#9-总结)

---

## 1. 引言：一屏多卡的意义

在移动应用中，"横向滚动卡片"是一种极为常见的内容展示形式：

| 应用 | 横向滚动场景 | displayCount 典型值 |
|------|------------|-------------------|
| **Apple Music** | "朋友正在听"推荐列表 | 2.5 |
| **Netflix** | 影片横向分类行 | 3.0~3.5 |
| **App Store** | 今日推荐卡片 | 2.0~2.5 |
| **淘宝** | 商品横向推荐 | 2.5~3.0 |
| **Instagram** | 快拍/故事列表 | 3.5~4.0 |

这些场景的共同特征是：**不希望用户一次只看一张卡片**。一屏展示多张卡片有三大好处：

1. **空间效率**：同样的屏幕空间展示更多内容，信息密度更高
2. **视觉暗示**：右侧露出的半张卡片告诉用户"还可以滑"
3. **对比浏览**：用户可以同时看到相邻的几条内容，快速决定是否滑动

HarmonyOS NEXT 的 Swiper 组件通过 `displayCount` 属性完美支持这种"一屏多卡"布局。

---

## 2. displayCount 属性详解

### 2.1 基本概念

`displayCount` 控制 Swiper 一屏（一页）显示多少个子项：

```ets
Swiper() { ... }
.displayCount(2.5)   // 一屏显示 2.5 张卡片
```

**整数部分** —— 完整可见的卡片数量  
**小数部分** —— 右侧露出的下一张卡片的宽度比例

- `displayCount(1)` = 每次显示 1 张（默认，标准轮播）
- `displayCount(2)` = 每次显示 2 张完整卡片
- `displayCount(2.5)` = 每次显示 2 张完整卡片 + 右半张预览
- `displayCount(3)` = 每次显示 3 张完整卡片

### 2.2 宽度计算公式

```text
卡片宽度 = (Swiper宽度 - (displayCount - 1) × itemSpace) / displayCount
```

**实际计算**（假设 Swiper 宽度 = 360vp）：

| displayCount | itemSpace | 卡片宽度 | 说明 |
|-------------|-----------|---------|------|
| 1.0 | 0 | 360 | 标准轮播，一屏一张 |
| 2.0 | 12 | 174 | 两卡并排，中间 12px 间距 |
| **2.5** | **12** | **~136.8** | **两卡完整 + 右半张预览** |
| 3.0 | 8 | ~114.7 | 三卡并排 |
| 3.5 | 8 | ~98.3 | 三卡 + 半张预览 |

**以 displayCount=2.5, itemSpace=12 为例**：

```text
卡1 (完整) | 12px | 卡2 (完整) | 12px | 卡3 (半张可见)
<───── 136.8 ─────> <───── 136.8 ─────> <── 68.4 ──>
<────────────────── 总宽 360 ─────────────────────>
```

### 2.3 不同数值的视觉效果

| displayCount | 视觉感受 | 适用场景 |
|-------------|---------|---------|
| **1.0** | 全屏轮播，焦点突出 | 首页大 Banner |
| **1.5** | 右侧露出半张，有"下一页"暗示 | 引导页 |
| **2.0** | 两卡并排，信息均衡 | 对比展示 |
| **2.5** | 两卡 + 半张预览，"继续滑"暗示强烈 | **推荐列表（最常用）** |
| **3.0** | 三卡并排，信息密度高 | 视频分类 / 图标网格 |
| **3.5+** | 密集展示，适合小卡片 | 表情 / Emoji 选择器 |

**2.5 是使用最广泛的配置**。它兼顾了内容可见性（2 张完整卡片）和可发现性（半张预览），是 Apple Music、Netflix 等主流应用的首选值。

---

## 3. itemSpace：卡片间距控制

`itemSpace` 设置相邻卡片之间的间距：

```ets
Swiper() { ... }
.displayCount(2.5)
.itemSpace(12)   // 卡片间距 12vp
```

**itemSpace 的作用**：

| itemSpace | 视觉效果 | 适用场景 |
|-----------|---------|---------|
| 0 | 卡片紧贴，无间隙 | 图片无缝拼接 |
| 8 | 紧凑，略有间隔 | 小卡片网格 |
| **12** | **舒适，明显分隔** | **通用卡片列表** |
| 16 | 宽松，呼吸感强 | 高端品牌展示 |
| 24 | 非常宽松 | 大卡片精选推荐 |

**itemSpace 在 displayCount 计算中的角色**：

itemSpace 不占用卡片的宽度，而是消耗 Swiper 总宽度的一部分。itemSpace 越大，每张卡片的可用宽度越小。

---

## 4. 实战：8 张电影推荐卡片轮播

### 4.1 设计目标

创建一个类似"Netflix 推荐行"的横向滑动卡片列表，一屏显示 2.5 张卡片，8 张不同主题的电影卡片自动轮播。

### 4.2 8 张卡片配色

| # | 电影 | 配色 | 色值 |
|---|------|------|------|
| 1 | 🎬 星际穿越 | 深蓝→蓝 | `#0D47A1` → `#1976D2` |
| 2 | 🎭 悲剧之王 | 深紫→紫 | `#4A148C` → `#7B1FA2` |
| 3 | 🎪 马戏迷城 | 橙→金黄 | `#E65100` → `#FF8F00` |
| 4 | 🎨 梵高之眼 | 深绿→绿 | `#2E7D32` → `#43A047` |
| 5 | 🎵 波西米亚 | 深红→红 | `#B71C1C` → `#E53935` |
| 6 | 🧙 中土传奇 | 深棕→棕 | `#3E2723` → `#6D4C41` |
| 7 | 🤖 机械纪元 | 深灰→灰 | `#37474F` → `#607D8B` |
| 8 | 🌊 深海探秘 | 墨绿→青 | `#004D40` → `#00897B` |

8 种配色覆盖蓝、紫、橙、绿、红、棕、灰、青色系，滑动时色彩变化丰富。

### 4.3 布局预览

```
┌──────────────────────────────────────┐
│  🎪 热门推荐                          │
│  displayCount(2.5) 一屏多卡           │
│                                      │
│  ┌──────┐ ┌──────┐ ┌──── ┐           │
│  │ 🎬   │ │ 🎭   │ │ 🎪  │           │
│  │星际穿│ │悲剧之│ │马戏迷│  ← 半张    │
│  │越    │ │王    │ │城    │  ← 预览    │
│  │科幻· │ │剧情· │ │奇幻· │           │
│  │冒险  │ │励志  │ │家庭  │           │
│  └──────┘ └──────┘ └──── ┘           │
│     ← 12px → ← 12px →                │
│         ○ ● ○ ○ ○ ○ ○ ○              │
│                                      │
│  📐 Swiper + displayCount 多卡片布局    │
│  ● displayCount(2.5)                 │
│  ● itemSpace(12)                     │
│  ● 右半张预览 → 继续滑动               │
│  ● autoPlay 自动轮播                  │
└──────────────────────────────────────┘
```

---

## 5. 代码逐段解析

### 5.1 数据模型：8 种配色方案

```ets
interface CardInfo {
  emoji: string;          // 电影图标
  title: string;          // 标题
  category: string;       // 分类 + 标签
  gradientStart: string;  // 渐变起点色
  gradientEnd: string;    // 渐变终点色
}

private readonly cards: CardInfo[] = [
  { emoji: '🎬', title: '星际穿越', category: '科幻 · 冒险', gradientStart: '#0D47A1', gradientEnd: '#1976D2' },
  { emoji: '🎭', title: '悲剧之王', category: '剧情 · 励志', gradientStart: '#4A148C', gradientEnd: '#7B1FA2' },
  // ... 共 8 张
];
```

**配色设计思路**：

每张卡片使用 `linearGradient` 从深色到亮色的垂直渐变，模拟"电影海报"的视觉质感。8 组配色覆盖了完整的色环，确保滑动时色彩跳跃明显：

```
蓝 → 紫 → 橙 → 绿 → 红 → 棕 → 灰 → 青 → 蓝（循环）
```

### 5.2 CardView：渐变色卡片的叠层构建

```ets
@Builder
private CardView(card: CardInfo) {
  Stack() {
    // 底层：渐变背景
    Column()
      .width('100%').height('100%').borderRadius(16)
      .linearGradient({
        direction: GradientDirection.Bottom,
        colors: [[card.gradientStart, 0], [card.gradientEnd, 1]],
      })

    // 中层：底部半透明遮罩（增强文字可读性）
    Column()
      .width('100%').height(80)
      .linearGradient({
        direction: GradientDirection.Bottom,
        colors: [['#00000000', 0], ['#00000066', 1]],
      })
      .borderRadius({ bottomLeft: 16, bottomRight: 16 })
      .position({ y: 140 })

    // 上层：图标
    Text(card.emoji).fontSize(48).position({ x: 0, y: 20 }).width('100%')

    // 上层：标题 + 分类（底部对齐）
    Column() {
      Text(card.title).fontSize(17).fontWeight(FontWeight.Bold).fontColor('#FFFFFF')
      Text(card.category).fontSize(12).fontColor('#FFFFFF').opacity(0.8)
    }
    .position({ x: 14, y: 164 })
  }
  .width('100%').height('100%').clip(true)
}
```

**叠层结构**：

```
┌──────────────────────┐
│        🎬            │  ← 图标 (position y:20)
│                      │
│                      │
│                      │
│  ┌─────────────┐     │  ← 渐变遮罩 (position y:140, height:80)
│  │ 星际穿越     │     │
│  │ 科幻 · 冒险  │     │  ← 文字 (position y:164)
│  └─────────────┘     │
└──────────────────────┘
   ↑ 渐变背景 (铺满)
```

**底部遮罩的作用**：

渐变背景上的白色文字，在浅色背景下可能不易阅读。底部半透明黑色遮罩（从完全透明到 40% 黑色）确保了文字区域始终有足够的对比度，同时不破坏渐变的美感。

### 5.3 build()：displayCount + itemSpace 核心配置

```ets
build() {
  Scroll() {
    Column() {
      // 标题
      Text('🎪 热门推荐').fontSize(22).fontWeight(FontWeight.Bold)

      Swiper() {
        ForEach(this.cards, (card: CardInfo, idx: number) => {
          Stack() { this.CardView(card) }
            .width('100%').height('100%')
        }, (card: CardInfo, idx: number): string => idx.toString())
      }
      .width('100%').height(220)
      .index(this.currentIndex)
      .displayCount(2.5)       // ← 核心属性：一屏显示 2.5 张
      .itemSpace(12)            // ← 核心属性：卡片间距 12vp
      .autoPlay(true).interval(3000).loop(true).duration(500)
      .indicator(false)
      .onChange((index) => { this.currentIndex = index; })

      // 指示器 + 说明卡片
      Stack() { this.DotIndicator() }.margin({ top: 4 })
      Stack() { this.FeatureCard() }.width('90%').margin({ top: 14 })
    }
  }
  .backgroundColor('#F2F3F8')
}
```

**displayCount 与卡片子元素的 width 关系**：

注意子元素使用了 `.width('100%').height('100%')`——它们的宽度由 Swiper 根据 displayCount 自动计算分配，不需要也不应该手动设置固定宽度。

**Swiper 高度 220vp 的选择依据**：

相比标准轮播（通常 300vp 以上），多卡片布局的卡片更小，220vp 高度在手机竖屏下刚好显示 2.5 张卡片 + 底部信息，无需用户滚动页面。

---

## 6. displayCount 与常规 Swiper 的对比

| 对比维度 | 常规 Swiper（displayCount=1） | 多卡片布局（displayCount=2.5） |
|---------|-----------------------------|------------------------------|
| **一屏卡片数** | 1 张 | 2.5 张 |
| **信息密度** | 低（一张大图） | 高（多张卡片） |
| **右侧预览** | 无（看不到下一张） | 有（半张预览暗示可滑） |
| **焦点** | 单卡片焦点集中 | 多卡片对比浏览 |
| **滑动步长** | 1 张卡片 | 1 张卡片（还是在同一个分页体系下） |
| **适合场景** | 首页大 Banner | 推荐列表 / 商品展示 |
| **卡片宽度** | 100% Swiper 宽度 | 由 displayCount 公式计算 |

**滑动行为的一致性**：

无论 `displayCount` 设置为多少，Swiper 的滑动步长始终是"一张卡片"。也就是说，从第 0 张滑到第 1 张，内容会移动一个卡片的宽度（不是半个 Swiper 宽度）。

这使得 `displayCount` 更像是一个"显示"属性而非"行为"属性——它只改变"一屏能看到多少"，不改变"一次能滑多少"。

---

## 7. 常见问题与解决方案

### 7.1 卡片显示不全

**现象**：displayCount 设置后，卡片右侧被裁剪。

**原因**：卡片子元素设置了固定宽度，覆盖了 Swiper 的自动分配。

**解决**：子元素使用 `.width('100%')`，不要设置固定宽度。

```ets
// ✅ 正确：宽度由 Swiper 自动分配
Stack() { this.CardView(card) }
  .width('100%').height('100%')

// ❌ 错误：固定宽度会覆盖 Swiper 的计算
Stack() { this.CardView(card) }
  .width(150).height(220)
```

### 7.2 displayCount 取整问题

**现象**：设置 `displayCount(2.5)` 但最终显示的不是精确的 2.5 张。

**原因**：Swiper 宽度可能不是 itemSpace 和 displayCount 的整数倍，Swiper 会在内部做适应性调整，最终结果可能与理论值有 ±0.1 的偏差。

**解决方案**：这不是 bug，是正常的舍入行为。只要视觉上接近 2.5 即可。

### 7.3 卡片间距不均匀

**现象**：相邻卡片间距不一致。

**原因**：`itemSpace` 是在 Swiper 侧设置的，但 `padding` 是在卡片侧设置的，两者叠加导致间距翻倍。

**解决**：不要在卡片子元素上设置左右 padding/margin，间距统一由 `itemSpace` 控制。

### 7.4 displayCount 与 loop 配合

**现象**：`displayCount(2.5)` + `loop(true)` 时，循环边界出现空白。

**原因**：loop 模式下的虚拟列表增加了额外的页面副本，displayCount 需要在这些副本之间保持一致的布局。

**解决方案**：大多数情况下可以正常工作。如果出现异常，确认 ForEach 的 keyGenerator 返回了稳定的唯一值。

### 7.5 displayCount 在小屏幕上的表现

**现象**：在屏幕宽度较小的设备上，displayCount 2.5 导致卡片过窄。

**解决方案**：使用条件语句适配不同屏幕：

```ets
// 根据屏幕宽度动态调整
aboutToAppear(): void {
  let w = this.getUIContext()?.getWindowWidth() ?? 360;
  if (w < 360) {
    this.cardCount = 2.0;  // 小屏 2 张
  } else {
    this.cardCount = 2.5;  // 正常 2.5 张
  }
}
```

---

## 8. 本系列七篇全览

本文是"鸿蒙原生 ArkTS 布局实战"系列的第六篇（不含项目回顾篇）。以下是全系列概览：

| # | 标题 | 组件 | 核心属性 | 核心知识点 |
|---|------|------|---------|-----------|
| 1 | Tabs + animateTo 切换动画 | Tabs | `animateTo` | 显式动画编排 |
| 2 | Swiper 轮播图 | Swiper | `autoPlay`, `interval` | 基础轮播配置 |
| 3 | Tabs + vertical 侧边栏 | Tabs | `vertical`, `barPosition.Start` | 左侧导航布局 |
| 4 | Swiper + loop 无限循环 | Swiper | `loop(true)` | 虚拟列表原理 |
| 5 | Swiper + Curve 缓动曲线 | Swiper | `.curve(Curve.xxx)` | 动画节奏控制 |
| **6** | **Swiper + displayCount** | **Swiper** | **`displayCount`, `itemSpace`** | **多卡片并排** |
| — | 项目回顾 | — | — | 24 个编译错误总结 |

**三篇 Swiper 文章的递进关系**：

1. **第 2 篇**（基础轮播）：学会 Swiper 的基本使用
2. **第 4 篇**（loop）：理解循环原理
3. **第 5 篇**（Curve）：掌控动画节奏
4. **第 6 篇（本篇）**（displayCount）：掌握多卡片布局

---

## 9. 总结

### 9.1 核心知识点

| 知识点 | 掌握程度 |
|--------|---------|
| displayCount 属性 | ✅ 控制一屏显示的卡片数量 |
| 宽度计算公式 | ✅ `(总宽 - (count-1) × itemSpace) / count` |
| itemSpace 卡片间距 | ✅ 统一间距控制 |
| 2.5 的典型配置 | ✅ 两卡完整 + 半张预览 |
| 卡片子元素 width | ✅ 使用 100%，不设固定值 |
| displayCount vs. 滑动步长 | ✅ 显示 ≠ 行为 |

### 9.2 displayCount 的最佳实践

| 卡片类型 | 推荐 displayCount | 推荐 itemSpace |
|---------|------------------|---------------|
| 大图海报 | 1.5~2.0 | 12~16 |
| 中等卡片 | **2.5** | **12** |
| 小卡片/头像 | 3.5~4.5 | 6~8 |
| Emoji/图标 | 5.0~6.0 | 4~6 |

### 9.3 扩展方向

1. **displayCount 动态切换**：根据屏幕宽度或用户偏好动态调整 count
2. **嵌套 displayCount**：外层 Swiper（全屏轮播）内嵌 displayCount Swiper（分类行）
3. **3D 堆叠效果**：通过自定义动画，让多张卡片在滑动时产生"3D 层叠"效果
4. **drag 手势**：关闭 autoPlay，让用户完全通过拖拽浏览，displayCount 提供预览

### 9.4 推荐阅读

- [HarmonyOS NEXT 开发文档 — Swiper 组件](https://developer.huawei.com/consumer/cn/doc/harmonyos-references-V5/ts-container-swiper-V5)
- [本系列第 2 篇 — Swiper 轮播图基础](./HarmonyOS_Swiper_Blog.md)
- [本系列第 4 篇 — Swiper + loop 无限循环](./HarmonyOS_Swiper_Loop_Blog.md)

---

> **本文配套完整代码**：`entry/src/main/ets/pages/Index.ets`，209 行，已通过编译验证。  
> **编译命令**：`hvigorw assembleApp --no-daemon`  
> **运行方式**：在 DevEco Studio 中打开项目，连接鸿蒙 NEXT 模拟器或真机运行。