meida_front/uni_modules/hbxw-stack-carousel/readme.md

# hbxw-stack-carousel 3D堆叠轮播图

## 介绍

一个支持3D堆叠效果的轮播图组件，具有自动播放、无缝循环、触摸滑动等功能，适用于各种图片展示场景。

## 特性

- 3D堆叠效果：轮播图以3D堆叠的方式展示，提供独特的视觉体验
- 自动播放：支持自动轮播功能，可自定义播放间隔时间
- 无缝循环：支持首尾衔接的无缝循环播放
- 手势滑动：支持左右滑动切换图片
- 自定义指示器：支持圆点和线条两种指示器样式
- 自定义尺寸：支持自定义组件的宽度和高度

## 使用示例

推荐先直接复制示例代码到工程中看效果了解下使用方法再投入项目使用。

```vue
<template>
	<view class="container">
		<view class="demo-item">
			<text class="title">3D堆叠轮播</text>
			<hbxw-stack-carousel :list="carouselList" :width="600" :height="300" @change="handleChange" @click="handleClick" />
		</view>
		<view class="demo-item">
			<text class="title">3D堆叠轮播-无缝滚动</text>
			<hbxw-stack-carousel :list="carouselList" :width="600" :height="300" loop indicatorStyle="line"  />
		</view>
		<view class="demo-item">
			<text class="title">插槽使用示例</text>
			<hbxw-stack-carousel :list="carouselList" :width="600" :height="300">
				<template #default="{item}">
					<view class="custom-item">
						<image :src="item.image" mode="aspectFill" />
						<text class="item-title">自定义内容</text>
					</view>
				</template>
				<template #indicator="{currentIndex, total, handleClick}">
					<view class="custom-indicators">
						<view 
							v-for="i in total" 
							:key="i" 
							class="custom-indicator" 
							:class="{'active': currentIndex === i-1}"
							@click="handleClick(i-1)"
						>{{ i }}</view>
					</view>
				</template>
			</hbxw-stack-carousel>
		</view>
	</view>
</template>

<script>
	export default {
		data() {
			return {
				carouselList: [
					{
						image: 'https://picsum.photos/600/300?random=1'
					},
					{
						image: 'https://picsum.photos/600/300?random=2'
					},
					{
						image: 'https://picsum.photos/600/300?random=3'
					},
					{
						image: 'https://picsum.photos/600/300?random=4'
					},
					{
						image: 'https://picsum.photos/600/300?random=5'
					}
				]
			}
		},
    methods: {
			handleChange(index, oldIndex) {
				console.log('---- change ----', index, oldIndex)
			},
			handleClick(index, item) {
				console.log('---- click ----', index, item)
			}
		}
	}
</script>

<style>
.container {
	padding: 20rpx 0;
	width: 100%;
	box-sizing: border-box;
	overflow-x: hidden;
}
.demo-item {
	margin-bottom: 30rpx;
}
.title {
	font-size: 28rpx;
	color: #666;
	margin-bottom: 20rpx;
	display: block;
}
.custom-item {
	position: relative;
	width: 600rpx;
	height: 300rpx;
}
.custom-item image {
	width: 100%;
	height: 100%;
}
.custom-item .item-title {
	position: absolute;
	bottom: 20rpx;
	left: 20rpx;
	color: #ccc;
	font-size: 26rpx;
	text-shadow: 0 2rpx 4rpx rgba(0,0,0,0.5);
}
.custom-indicators {
	display: flex;
	width: 100%;
	gap: 20rpx;
	justify-content: center;
}
.custom-indicator {
	width: 30rpx;
	height: 30rpx;
	background: #ccc;
	border-radius: 6rpx;
	font-size: 24rpx;
	display: flex;
	justify-content: center;
	align-items: center;
	color: #fff;
}
.custom-indicator.active {
	background: #007AFF;
}
</style>
```

## API

### Props 属性说明

| 属性名 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| list | Array | [] | 轮播图数据列表，每个元素必须包含image属性 |
| width | String/Number | '750rpx' | 组件宽度，支持数字（单位rpx）或字符串 |
| height | String/Number | '400rpx' | 组件高度，支持数字（单位rpx）或字符串 |
| autoplay | Boolean | true | 是否自动播放 |
| interval | Number | 3000 | 自动播放间隔时间（毫秒） |
| loop | Boolean | false | 是否启用无缝循环 |
| showIndicator | Boolean | true | 是否显示指示器 |
| indicatorStyle | String | 'dot' | 指示器样式，支持dot（圆点）和line（线条） |

### Events 事件说明

| 事件名 | 说明 | 回调参数 |
| --- | --- | --- |
| change | 轮播图切换时触发 | (index: number, oldIndex: number) index: 当前索引，oldIndex: 上一个索引 |
| click | 点击轮播图时触发 | (index: number, item: object) index: 当前点击的轮播图索引，item: 当前点击的轮播图数据 |

## 注意事项

1. list数组中的每个对象必须包含image属性
2. 组件宽高支持数字（自动添加rpx单位）或带单位的字符串格式
3. 启用无缝循环时，建议list数组至少包含2个元素
4. 使用line样式指示器时，建议搭配较大的组件宽度，以获得更好的视觉效果

## 插槽使用说明

### 默认插槽

用于自定义轮播图内容，接收以下作用域参数：

- `item`: 当前轮播项数据
- `index`: 当前项索引

示例：

```vue
<hbxw-stacked-carousel :list="carouselList">
  <template #default="{ item, index }">
    <view class="custom-content">
      <image :src="item.image" mode="aspectFill" />
      <text class="title">第{{index + 1}}张图片</text>
    </view>
  </template>
</hbxw-stacked-carousel>
```

### 指示器插槽

用于自定义指示器样式，接收以下作用域参数：

- `current-index`: 当前激活的轮播索引
- `total`: 轮播项总数
- `handle-click`: 点击切换轮播的方法

示例：

```vue
<hbxw-stacked-carousel :list="carouselList">
  <template #indicator="{ currentIndex, total, handleClick }">
    <view class="custom-indicator">
      <text>{{currentIndex + 1}}/{{total}}</text>
      <view 
        v-for="i in total" 
        :key="i" 
        class="indicator-item" 
        :class="{ 'active': currentIndex === i - 1 }"
        @click="handleClick(i - 1)"
      />
    </view>
  </template>
</hbxw-stacked-carousel>
```