zz-shopify-components/docs/zz-normal-swiper.md

Reusable Shopify components for theme projects

# ZZ Normal Swiper 组件使用文档

## 概述

`zz-normal-swiper` 是一个基于 Swiper.js 的高性能、可复用轮播组件，支持懒加载初始化、响应式配置、自动播放等功能。

## 特性

- ✅ **懒加载初始化**：仅在进入可视区域时初始化，节省资源
- ✅ **响应式设计**：支持 PC/Mobile 不同配置
- ✅ **自动播放**：可配置间隔时间，支持悬停暂停
- ✅ **多种分页器**：圆点、分式、进度条可选
- ✅ **灵活导航**：左右导航按钮，移动端可独立控制
- ✅ **可定制样式**：支持背景色、分页器颜色等自定义
- ✅ **性能优化**：IntersectionObserver 自动控制播放状态

## 基本使用

### 1. 添加组件

在 Shopify 主题编辑器中：
1. 找到需要添加轮播的 Section
2. 点击"添加区块" 
3. 选择"ZZ Components" → "ZZ Normal Swiper"

### 2. 添加内容

添加组件后，可以在其中插入子区块作为轮播内容：
- 默认支持所有主题区块（`@theme`）
- 推荐使用 `zz-flex-layout-block` 等布局组件

## 配置选项

### 基础设置

| 配置项 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| `bg_color` | 颜色 | #ffffff | 组件背景色 |
| `loop` | 复选框 | true | 是否循环播放 |
| `speed` | 范围 | 500ms | 切换动画速度 (100-5000ms) |
| `space_between` | 范围 | 8px | 卡片之间的间距 (0-80px) |
| `centered_slides` | 复选框 | false | 是否居中显示当前卡片 |
| `auto_height` | 复选框 | false | 是否自适应内容高度 |

### 自动播放

| 配置项 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| `autoplay` | 复选框 | false | 是否开启自动播放 |
| `autoplay_delay` | 范围 | 4000ms | 自动播放间隔 (1000-9500ms) |

> 💡 **自动播放特性**：
> - 组件离开可视区域时自动暂停
> - 鼠标悬停时暂停播放
> - 用户交互后不会重置计时器

### 分页器设置

| 配置项 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| `pagination_type` | 选择 | bullets | 分页器类型：隐藏/圆点/分式/进度条 |
| `pagination_color` | 颜色 | #000000 | PC端分页器颜色 |
| `mb_pagination_color` | 颜色 | #000000 | 移动端分页器颜色 |

### 导航设置

| 配置项 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| `show_navigation` | 复选框 | true | 是否显示左右导航按钮 |
| `show_navigation_mobile` | 复选框 | false | 移动端是否显示导航 |
| `prev_next_type` | 选择 | dark | 导航按钮主题：黑色/白色 |

### 响应式配置

| 配置项 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| `slides_per_view_mb` | 范围 | 1 | 移动端同时显示的卡片数 (1-3，支持小数) |
| `slides_per_group_mb` | 范围 | 1 | 移动端每次滑动的卡片数 (1-3) |
| `slides_per_view_pc` | 范围 | 3 | PC端同时显示的卡片数 (1-6，支持小数) |
| `slides_per_group_pc` | 范围 | 1 | PC端每次滑动的卡片数 (1-6) |

## 使用示例

### 示例 1：基础产品轮播

```liquid
<!-- 在 Section 中添加 zz-normal-swiper block -->
<!-- 配置：
- slides_per_view_pc: 3
- slides_per_view_mb: 1.2
- space_between: 16
- autoplay: true
- autoplay_delay: 5000
-->
```

### 示例 2：全宽图片轮播

```liquid
<!-- 配置：
- slides_per_view_pc: 1
- slides_per_view_mb: 1
- centered_slides: true
- pagination_type: bullets
- loop: true
-->
```

### 示例 3：卡片预览轮播

```liquid
<!-- 配置：
- slides_per_view_pc: 4.5
- slides_per_view_mb: 2.2
- space_between: 12
- centered_slides: false
- show_navigation: true
- pagination_type: none
-->
```

## 样式定制

### CSS 变量覆盖

```css
#shopify-block-[block-id] {
  /* 自定义分页器位置 */
  --swiper-pagination-bottom: 20px;
  
  /* 自定义导航按钮位置 */
  --swiper-navigation-size: 44px;
}
```

### 自定义分页器样式

```css
#shopify-block-[block-id] .swiper-pagination-bullet {
  /* 自定义圆点样式 */
  background: #ff6b6b;
  border: 2px solid #fff;
}
```

## 性能优化

### 1. 懒加载机制
- 组件使用 `IntersectionObserver` 实现懒加载
- 仅在进入可视区域后初始化 Swiper 实例
- 离开可视区域时自动暂停自动播放

### 2. 内存管理
- 组件销毁时自动清理事件监听器
- 避免重复初始化

### 3. 性能建议
- 当 `slides_per_view` > 实际卡片数时，自动禁用循环
- 图片使用 `loading="lazy"` 属性
- 避免在轮播中嵌套过于复杂的内容

## 常见问题

### Q: 轮播不显示？
A: 检查以下几点：
1. 确保已添加子区块作为轮播内容
2. 检查是否正确引入了 Swiper 资源文件
3. 查看浏览器控制台是否有 JavaScript 错误

### Q: 自动播放不工作？
A: 确认：
1. `autoplay` 选项已开启
2. 组件在可视区域内
3. 没有用户交互导致暂停

### Q: 移动端显示异常？
A: 检查：
1. `slides_per_view_mb` 设置是否合理
2. `space_between` 是否过大
3. 内容宽度是否超出容器

### Q: 如何自定义导航按钮？
A: 导航按钮使用 `zz-prev-next-btn` 组件渲染，可以：
1. 修改 `prev_next_type` 配置
2. 自定义 CSS 覆盖样式
3. 修改 `zz-prev-next-btn.liquid` 模板

## 技术依赖

- **Swiper.js**: 轮播核心库
- **IntersectionObserver**: 懒加载和性能优化
- **zz-prev-next-btn**: 导航按钮组件

## 浏览器兼容性

- **现代浏览器**: 完全支持
- **IE 11**: 需要 IntersectionObserver polyfill
- **移动端**: iOS 10+, Android 5+

## 更新日志

### v1.0.0
- 初始版本发布
- 支持基础轮播功能
- 懒加载初始化
- 响应式配置
- 自动播放功能

---

## 相关组件

- `zz-flex-layout-block`: 推荐的轮播内容布局组件
- `zz-prev-next-btn`: 导航按钮组件
- `zz-full-screen-swiper`: 全屏轮播组件